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.

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.

---

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

tokenIn · string · required

The input token you want to sell. Accepts a ticker symbol (e.g. SOL) or a full contract address.

tokenOut · string · required

The output token you want to receive. Accepts a ticker symbol (e.g. USDC) or a full contract address.

amountIn · string · required

The amount of tokenIn to spend, expressed as a string to preserve decimal precision (e.g. "1.5").

slippage · 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.

network · string · required

The blockchain network on which to execute the swap. Accepted values: solana, ethereum, base, arbitrum.

Example Request

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

{
  "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

data.id · string

Unique identifier for this trade. Use this ID with GET /trades/{id} to track status.

data.status · string

Current status of the trade. Possible values: pending, confirmed, failed.

data.tokenIn · string

The token being sold.

data.tokenOut · string

The token being received.

data.amountIn · string

The exact amount of tokenIn submitted.

data.estimatedAmountOut · string

The estimated amount of tokenOut you will receive, based on current market prices and your slippage setting.

data.fee · 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.

data.network · string

The network on which the swap is being executed.

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.

---

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

token · string

Filter trades involving a specific token symbol or contract address (matches either tokenIn or tokenOut).

status · string

Filter by trade status. Accepted values: pending, confirmed, failed.

network · string

Filter by blockchain network. Accepted values: solana, ethereum, base, arbitrum.

from · string

Return trades submitted on or after this date. Accepts an ISO 8601 date string (e.g. 2024-01-01T00:00:00Z).

to · string

Return trades submitted on or before this date. Accepts an ISO 8601 date string.

limit · number · default: "20"

Maximum number of trades to return per page. Defaults to 20, maximum 100.

offset · number · default: "0"

Number of records to skip before returning results. Use with limit to paginate through large histories.

Example Request

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

Example Response

{
  "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

data.total · number

The total number of trades in your history that match the applied filters.

data.limit · number

The maximum number of records returned in this page, as requested.

data.offset · number

The number of records skipped before this page of results.

data.trades · array

Ordered list of trade objects, from most recent to oldest.

Show trade item fields

id · string

Unique identifier for the trade.

status · string

Current trade status: pending, confirmed, or failed.

tokenIn · string

The token that was sold.

tokenOut · string

The token that was received.

amountIn · string

The amount of tokenIn that was spent.

amountOut · string

The actual amount of tokenOut received after the swap. Only present when status is confirmed.

fee · string

The 0.25% platform fee deducted from the swap, denominated in tokenOut.

network · string

The blockchain network on which the swap was executed.

txHash · string

The on-chain transaction hash. Only present once the trade has been broadcast.

createdAt · string

ISO 8601 UTC timestamp for when the trade was created via the API.

confirmedAt · string

ISO 8601 UTC timestamp for when the transaction received on-chain confirmation. null if not yet confirmed.

---

GET /trades/

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

id · string · required

The unique trade ID returned by POST /trades (e.g. trade_abc123).

Example Request

curl -X GET 'https://api.bigbrainape.com/v1/trades/trade_abc123' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Example Response

{
  "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

data.id · string

The unique trade identifier.

data.status · string

Final or current status: pending, confirmed, or failed.

data.amountOut · string

The actual amount of tokenOut received after the swap settled on-chain. Only present when status is confirmed.

data.estimatedAmountOut · string

The amount estimated at the time the trade was submitted.

data.txHash · string

The on-chain transaction hash. Only present once the trade has been broadcast to the network.

data.walletAddress · string

The wallet address that signed and submitted the transaction.

data.createdAt · string

ISO 8601 timestamp for when the trade was created via the API.

data.submittedAt · string

ISO 8601 timestamp for when the signed transaction was broadcast to the network.

data.confirmedAt · string

ISO 8601 timestamp for when the transaction received on-chain confirmation. null if not yet confirmed.

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.