> ## Documentation Index
> Fetch the complete documentation index at: https://docs.capital.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Activity

## Transactions

`GET /api/v1/transactions` · scope `read`

Your account's history, newest first: money moving in and out, and the stock limit orders you placed. Both share one list and one `limit`, except for open orders: up to 500 open orders older than the `limit` newest rows are listed after them, so you can still cancel them.

| Query | Type | Description |
| - | - | - |
| `limit` | integer | Max rows. Default `100`, max `500`. Open orders older than these rows are listed after them, up to 500. |

```json theme={null}
{ "transactions": [ /* Transaction */ ] }
```

Fields marked *order rows only* are left out of money rows.

| Field | Type | Description |
| - | - | - |
| `id` | string | Transaction ID. On an order row, the order ID. |
| `type` | `deposit` \| `send` \| `buy` \| `sell` | What kind of movement. Order rows are `buy` or `sell`. |
| `status` | `pending` \| `in_progress` \| `completed` \| `failed` \| `canceled` | Lifecycle state. (`pending_approval` is reserved and not returned today.) |
| `rail` | `bank` \| `chain` \| `internal` | How it moved. Order rows are `internal`. |
| `method` | `ach` \| `wire` \| `international_wire` \| `stablecoin` \| null | Bank method, on `bank` rows. |
| `asset` | string | Asset, e.g. `USD`. On an order row, the ticker. |
| `amountUsd` | number | Amount in USD. Never negative. For order rows, see [Order rows](#order-rows). |
| `counterparty` | string \| null | The other party, when there is one. |
| `providerRef` | string \| null | The banking partner's reference. On an order row, the broker's order ID, once the broker accepts the order. |
| `date` | string | When it was created. |
| `updatedAt` | string | When it last changed. |
| `orderKind` | `limit` | *Order rows only.* The order type. |
| `timeInForce` | `day` \| `gtc` \| `gtd` | *Order rows only.* How long the order lasts. |
| `expireDate` | string | *`gtd` order rows only.* The last day the order works, `yyyy-MM-dd`. |
| `assetAmount` | number | *Order rows only.* Shares ordered. On an order that ended after filling, the shares filled. |
| `limitPriceUsd` | number | *Order rows only.* The limit price. |
| `filledPercent` | number | *Order rows only.* How much of the order has filled, from `0` to `100`. Not rounded. |
| `executionPriceUsd` | number | *Order rows only.* The average fill price. Present once any part has filled. |
| `feeUsd` | number | *Order rows only.* The broker's fee, on top of `amountUsd`: the estimate while the order is open, the fee charged once it has ended. Absent when no money moved or the broker reported none. |

### Order rows

Each limit order you place with `POST /api/v1/orders` is listed under its order `id`. That is the `id` that `DELETE /api/v1/orders/{id}` takes.

| Order | `status` |
| - | - |
| Waiting for the broker, or open (even if partly filled) | `pending` |
| Filled in full | `completed` |
| Rejected by the broker | `failed` |
| Canceled, or expired (a `day` order at the close, a `gtd` order after its `expireDate`) | `canceled` |

After you ask to cancel, the order stays `pending` until the broker confirms the cancel. It can still fill until then.

`amountUsd` on an order row:

* While the order is open: shares ordered × limit price.
* Once it has ended with fills: shares filled × average fill price. This is the cash that moved.
* Once it has ended with no fills: shares ordered × limit price.

The fee is never folded into `amountUsd`; it is `feeUsd`.

```bash REST theme={null}
curl "$CAPITALAI_API_URL/api/v1/transactions?limit=20" \
  -H "Authorization: Bearer $CAPITALAI_API_KEY"
```

```ts TypeScript theme={null}
const res = await fetch(`${process.env.CAPITALAI_API_URL}/api/v1/transactions?limit=20`, {
  headers: { Authorization: `Bearer ${process.env.CAPITALAI_API_KEY}` },
});
console.log(await res.json());
```

## Brokerage transfers

`GET /api/v1/brokerage-transfers` · scope `read`

Transfers of holdings from an outside brokerage into your account. Returns an array of:

| Field | Type | Description |
| - | - | - |
| `id` | string | Request ID. |
| `brokerageId` | string | The outside brokerage. |
| `brokerageName` | string | Its name. |
| `accountLastFour` | string | Last four digits of the outside account. |
| `scope` | `full` \| `partial` | Whole account, or selected positions. |
| `positions` | array | `partial` only: `securityId`, `ticker`, `name`, `quantity`. |
| `status` | `submitted` \| `validated` \| `transferring` \| `completed` \| `rejected` | Progress. |
| `createdAt` / `updatedAt` | string | Timestamps. |

```bash REST theme={null}
curl "$CAPITALAI_API_URL/api/v1/brokerage-transfers" \
  -H "Authorization: Bearer $CAPITALAI_API_KEY"
```

```ts TypeScript theme={null}
const res = await fetch(`${process.env.CAPITALAI_API_URL}/api/v1/brokerage-transfers`, {
  headers: { Authorization: `Bearer ${process.env.CAPITALAI_API_KEY}` },
});
console.log(await res.json());
```

## Start a brokerage transfer

`POST /api/v1/brokerage-transfers` · scope `trade`

Moves holdings from an outside brokerage into your account.

| Field | Type | Description |
| - | - | - |
| `brokerageId` | string | The outside brokerage: its DTC number as `dtc-1234`, or the ID from linking it in the app. |
| `brokerageName` | string | Its name. |
| `accountLastFour` | string | Last four characters of the outside account number. Only these four are sent. |
| `scope` | `full` \| `partial` | The whole account, or selected positions. |
| `positions` | array | `partial` only: `securityId`, `ticker`, `name`, `quantity`. |

`201` with the request, as in the list above. `400` with a `code` when `accountLastFour` isn't four letters or digits, or `positions` doesn't match `scope`. `409` with `openRequestId` when a request for that account is already open.

```bash REST theme={null}
curl -X POST "$CAPITALAI_API_URL/api/v1/brokerage-transfers" \
  -H "Authorization: Bearer $CAPITALAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"brokerageId": "dtc-1234", "brokerageName": "Example Brokerage", "accountLastFour": "5678", "scope": "full"}'
```

```ts TypeScript theme={null}
const res = await fetch(`${process.env.CAPITALAI_API_URL}/api/v1/brokerage-transfers`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CAPITALAI_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({"brokerageId": "dtc-1234", "brokerageName": "Example Brokerage", "accountLastFour": "5678", "scope": "full"}),
});
console.log(await res.json());
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.