# Trade It API

Source: https://docs.tradeit.app/api

Base URL: 
https://api.tradeit.app

Use the Trade It REST API to read connected brokerage accounts and holdings, create equity or options trade drafts, execute approved orders, and cancel eligible orders. These endpoints work without an embedded Trade It modal, so a partner can build the entire review and trading experience in its own application.

## Authentication [#authentication]

Send either a Trade It API key or an OAuth access token as a bearer token for account, trading, and connection requests:

```http
Authorization: Bearer <access_token_or_api_key>
Content-Type: application/json
```

Create an API key from the [API keys page](https://tradeit.app/account/api-keys). For a multi-user partner integration, use OAuth so every request is authorized for the correct Trade It user.

OAuth discovery is available at:

```text
https://tradeit.app/.well-known/oauth-authorization-server
```

> **Note**
>
> Keep the partner `client_secret`, API keys, access tokens, and refresh tokens on your server. Do not expose them in browser code.

## Tool execution [#tool-execution]

The account and trading operations documented here use one canonical endpoint:

```http
POST https://api.tradeit.app/api/tool/execute
```

Select the operation with `tool_name` and pass its input in `params`:

```json
{
  "tool_name": "get_accounts",
  "params": {}
}
```

> **Note**
>
> The response body is the operation result itself; it is not wrapped in a `result` property.

## API reference [#api-reference]

| Operation | `tool_name` | Purpose |
| --- | --- | --- |
| [Get accounts](/api/get-accounts) | `get_accounts` | List the user's connected brokerage accounts. |
| [Get holdings](/api/get-holdings) | `get_holdings` | List positions for one brokerage account. |
| [Get trades](/api/get-trades) | `get_trades` | Read recent trades and refresh order state. |
| [Create trade](/api/create-trade) | `create_trade` | Create a stock or crypto trade draft. |
| [Create options trade](/api/create-options-trade) | `create_options_trade` | Create a single-leg or multi-leg options draft. |
| [Execute trade](/api/execute-trade) | `execute_trade` | Submit a reviewed draft to the brokerage. |
| [Cancel trade](/api/cancel-trade) | `cancel_trade` | Cancel a draft or request brokerage cancellation. |

Responses use these data models, each documented field by field: [Account](/models/account) [Holding](/models/holding) [Trade](/models/trade)

### Brokerage connections [#brokerage-connections]

| Operation | Endpoint | Purpose |
| --- | --- | --- |
| [Delete connection](/api/delete-connection) | `DELETE /api/brokerageConnection/{id}` | Delete the user's entire connection, its accounts, and their stored trades across Trade It and all partners. |

### Organization membership [#organization-membership]

| Operation | Endpoint | Purpose |
| --- | --- | --- |
| [Remove membership](/api/remove-membership) | `DELETE /api/partner/membership` | Remove a member using your client credentials and their Trade It `user_id`. |

## Recommended trading flow [#recommended-trading-flow]

1. Call [Get accounts](/api/get-accounts) and let the user choose an account.
2. Call [Create trade](/api/create-trade) or [Create options trade](/api/create-options-trade).
3. Render the returned order, including its account, action, quantity, order type, prices, and legs.
4. Ask the user to approve that specific order.
5. Only after approval, pass its `id` to [Execute trade](/api/execute-trade).
6. Use [Get trades](/api/get-trades) to refresh the order state or [Cancel trade](/api/cancel-trade) when the user requests cancellation.

> **Explicit approval**
>
> Creating a draft and executing it are separate operations. It's best practice not to call `execute_trade` immediately after a create operation so users can review and explicitly approve trades. Note that an account configured for automatic execution may return an already submitted trade from a create call. Check the `status` to confirm.

## OAuth scopes [#oauth-scopes]

Request only the scopes the integration needs:

| Scope | Used for |
| --- | --- |
| `brokerage:read` | Accounts and holdings |
| `trade:read` | Trade history and current order state |
| `trade:write` | Creating, executing, and canceling trades |
| `tool:execute` | Calling the tool execution endpoint |

## Errors [#errors]

Errors use a consistent JSON shape:

```json
{
  "error": "invalid_request",
  "error_description": "The request body is invalid.",
  "resolution": null,
  "validation_errors": []
}
```

Common status codes include `400` for invalid input or an invalid trade state, `401` for missing or invalid authentication, and `403` for insufficient access or an unavailable plan feature.

## Partner setup [#partner-setup]

If you need OAuth credentials for a multi-user integration:

1. Sign in at [tradeit.app](https://tradeit.app).
2. Choose `Organization` on first login.
3. Complete the partner setup flow in the partner portal.
4. Save the generated `client_id` and one-time `client_secret`.

> **TIP**
>
> The [Trade It Postman collection](https://www.postman.com/trade-it/workspace/trade-it-apis/collection/5398302-70e1f409-c978-4701-a2fa-6f58b8b11932?action=share&source=copy-link&creator=5398302) remains available as a runnable companion to this reference.

If you have questions or want to discuss your use case, [contact us](https://tradeit.app/contact).