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

# Trades API — Execute Token Swaps and View History

> POST /trades executes a token swap and GET /trades returns your full trade history with filtering by token, date, status, and network.

The Trades API lets you initiate token swaps programmatically and query the full history of your trading activity. You can execute cross-network swaps, apply slippage controls, and retrieve detailed status information for any trade — from submission through on-chain confirmation.

<Note>
  Trades are signed by your connected wallet. The API prepares and initiates the transaction, but your wallet must approve it before it is broadcast to the network. If you have configured a delegated signing key in your Big Brain Ape account, approval happens automatically without a manual wallet confirmation step.
</Note>

***

## POST /trades

Initiate a token swap on a supported network. The API returns a trade object immediately with a `pending` status. Poll `GET /trades/{id}` or subscribe to webhook events to track confirmation.

**Required scope:** `trade`

### Request Body

<ParamField body="tokenIn" type="string" required>
  The input token you want to sell. Accepts a ticker symbol (e.g. `SOL`) or a full contract address.
</ParamField>

<ParamField body="tokenOut" type="string" required>
  The output token you want to receive. Accepts a ticker symbol (e.g. `USDC`) or a full contract address.
</ParamField>

<ParamField body="amountIn" type="string" required>
  The amount of `tokenIn` to spend, expressed as a string to preserve decimal precision (e.g. `"1.5"`).
</ParamField>

<ParamField body="slippage" type="number" default="0.5">
  Maximum acceptable slippage tolerance as a percentage. If the price moves beyond this threshold before the transaction is executed, the swap is cancelled. Defaults to `0.5`.
</ParamField>

<ParamField body="network" type="string" required>
  The blockchain network on which to execute the swap. Accepted values: `solana`, `ethereum`, `base`, `arbitrum`.
</ParamField>

### Example Request

```bash theme={null}
curl -X POST https://api.bigbrainape.com/v1/trades \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "tokenIn": "SOL",
    "tokenOut": "USDC",
    "amountIn": "1.5",
    "slippage": 0.5,
    "network": "solana"
  }'
```

### Example Response

```json theme={null}
{
  "success": true,
  "data": {
    "id": "trade_abc123",
    "status": "pending",
    "tokenIn": "SOL",
    "tokenOut": "USDC",
    "amountIn": "1.5",
    "estimatedAmountOut": "215.34",
    "fee": "0.54",
    "network": "solana"
  },
  "timestamp": "2024-01-15T14:32:00Z"
}
```

### Response Fields

<ResponseField name="data.id" type="string">
  Unique identifier for this trade. Use this ID with `GET /trades/{id}` to track status.
</ResponseField>

<ResponseField name="data.status" type="string">
  Current status of the trade. Possible values: `pending`, `confirmed`, `failed`.
</ResponseField>

<ResponseField name="data.tokenIn" type="string">
  The token being sold.
</ResponseField>

<ResponseField name="data.tokenOut" type="string">
  The token being received.
</ResponseField>

<ResponseField name="data.amountIn" type="string">
  The exact amount of `tokenIn` submitted.
</ResponseField>

<ResponseField name="data.estimatedAmountOut" type="string">
  The estimated amount of `tokenOut` you will receive, based on current market prices and your slippage setting.
</ResponseField>

<ResponseField name="data.fee" type="string">
  The platform fee deducted from the swap, denominated in `tokenOut`. Big Brain Ape charges a flat **0.25%** fee on every trade, calculated against the output amount.
</ResponseField>

<ResponseField name="data.network" type="string">
  The network on which the swap is being executed.
</ResponseField>

<Warning>
  The `estimatedAmountOut` is indicative. The final received amount may differ slightly due to price movement between the time of estimation and on-chain execution. Set `slippage` to protect against large deviations.
</Warning>

***

## GET /trades

Retrieve a paginated list of your trade history. Filter results by token, status, network, or date range to narrow down exactly the trades you need.

**Required scope:** `read`

### Query Parameters

<ParamField query="token" type="string">
  Filter trades involving a specific token symbol or contract address (matches either `tokenIn` or `tokenOut`).
</ParamField>

<ParamField query="status" type="string">
  Filter by trade status. Accepted values: `pending`, `confirmed`, `failed`.
</ParamField>

<ParamField query="network" type="string">
  Filter by blockchain network. Accepted values: `solana`, `ethereum`, `base`, `arbitrum`.
</ParamField>

<ParamField query="from" type="string">
  Return trades submitted on or after this date. Accepts an ISO 8601 date string (e.g. `2024-01-01T00:00:00Z`).
</ParamField>

<ParamField query="to" type="string">
  Return trades submitted on or before this date. Accepts an ISO 8601 date string.
</ParamField>

<ParamField query="limit" type="number" default="20">
  Maximum number of trades to return per page. Defaults to `20`, maximum `100`.
</ParamField>

<ParamField query="offset" type="number" default="0">
  Number of records to skip before returning results. Use with `limit` to paginate through large histories.
</ParamField>

### Example Request

```bash theme={null}
curl -X GET 'https://api.bigbrainape.com/v1/trades?status=confirmed&network=solana&limit=5' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

### Example Response

```json theme={null}
{
  "success": true,
  "data": {
    "total": 42,
    "limit": 5,
    "offset": 0,
    "trades": [
      {
        "id": "trade_abc123",
        "status": "confirmed",
        "tokenIn": "SOL",
        "tokenOut": "USDC",
        "amountIn": "1.5",
        "amountOut": "214.98",
        "fee": "0.54",
        "network": "solana",
        "txHash": "5KtB...wX9q",
        "createdAt": "2024-01-15T14:32:00Z",
        "confirmedAt": "2024-01-15T14:32:18Z"
      }
    ]
  },
  "timestamp": "2024-01-15T14:32:30Z"
}
```

### Response Fields

<ResponseField name="data.total" type="number">
  The total number of trades in your history that match the applied filters.
</ResponseField>

<ResponseField name="data.limit" type="number">
  The maximum number of records returned in this page, as requested.
</ResponseField>

<ResponseField name="data.offset" type="number">
  The number of records skipped before this page of results.
</ResponseField>

<ResponseField name="data.trades" type="array">
  Ordered list of trade objects, from most recent to oldest.

  <Expandable title="trade item fields">
    <ResponseField name="id" type="string">
      Unique identifier for the trade.
    </ResponseField>

    <ResponseField name="status" type="string">
      Current trade status: `pending`, `confirmed`, or `failed`.
    </ResponseField>

    <ResponseField name="tokenIn" type="string">
      The token that was sold.
    </ResponseField>

    <ResponseField name="tokenOut" type="string">
      The token that was received.
    </ResponseField>

    <ResponseField name="amountIn" type="string">
      The amount of `tokenIn` that was spent.
    </ResponseField>

    <ResponseField name="amountOut" type="string">
      The actual amount of `tokenOut` received after the swap. Only present when `status` is `confirmed`.
    </ResponseField>

    <ResponseField name="fee" type="string">
      The 0.25% platform fee deducted from the swap, denominated in `tokenOut`.
    </ResponseField>

    <ResponseField name="network" type="string">
      The blockchain network on which the swap was executed.
    </ResponseField>

    <ResponseField name="txHash" type="string">
      The on-chain transaction hash. Only present once the trade has been broadcast.
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      ISO 8601 UTC timestamp for when the trade was created via the API.
    </ResponseField>

    <ResponseField name="confirmedAt" type="string">
      ISO 8601 UTC timestamp for when the transaction received on-chain confirmation. `null` if not yet confirmed.
    </ResponseField>
  </Expandable>
</ResponseField>

***

## GET /trades/{id}

Fetch the full details of a single trade by its ID. This endpoint returns the most up-to-date status, the on-chain transaction hash once confirmed, and precise timestamps for each stage of the trade lifecycle.

**Required scope:** `read`

### Path Parameters

<ParamField path="id" type="string" required>
  The unique trade ID returned by `POST /trades` (e.g. `trade_abc123`).
</ParamField>

### Example Request

```bash theme={null}
curl -X GET 'https://api.bigbrainape.com/v1/trades/trade_abc123' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

### Example Response

```json theme={null}
{
  "success": true,
  "data": {
    "id": "trade_abc123",
    "status": "confirmed",
    "tokenIn": "SOL",
    "tokenOut": "USDC",
    "amountIn": "1.5",
    "amountOut": "214.98",
    "estimatedAmountOut": "215.34",
    "slippage": 0.5,
    "fee": "0.54",
    "network": "solana",
    "txHash": "5KtBm2rFJhZ3oNpVsLcE1dDqAeXkWuY8MgCfRv7nTwX9q",
    "walletAddress": "7xKpQ...mN3a",
    "createdAt": "2024-01-15T14:32:00Z",
    "submittedAt": "2024-01-15T14:32:05Z",
    "confirmedAt": "2024-01-15T14:32:18Z"
  },
  "timestamp": "2024-01-15T14:32:30Z"
}
```

### Response Fields

<ResponseField name="data.id" type="string">
  The unique trade identifier.
</ResponseField>

<ResponseField name="data.status" type="string">
  Final or current status: `pending`, `confirmed`, or `failed`.
</ResponseField>

<ResponseField name="data.amountOut" type="string">
  The actual amount of `tokenOut` received after the swap settled on-chain. Only present when `status` is `confirmed`.
</ResponseField>

<ResponseField name="data.estimatedAmountOut" type="string">
  The amount estimated at the time the trade was submitted.
</ResponseField>

<ResponseField name="data.txHash" type="string">
  The on-chain transaction hash. Only present once the trade has been broadcast to the network.
</ResponseField>

<ResponseField name="data.walletAddress" type="string">
  The wallet address that signed and submitted the transaction.
</ResponseField>

<ResponseField name="data.createdAt" type="string">
  ISO 8601 timestamp for when the trade was created via the API.
</ResponseField>

<ResponseField name="data.submittedAt" type="string">
  ISO 8601 timestamp for when the signed transaction was broadcast to the network.
</ResponseField>

<ResponseField name="data.confirmedAt" type="string">
  ISO 8601 timestamp for when the transaction received on-chain confirmation. `null` if not yet confirmed.
</ResponseField>

<Tip>
  If a trade stays in `pending` status for more than a few minutes, check `txHash` on a block explorer for your network to investigate potential on-chain issues such as insufficient funds or network congestion.
</Tip>