Trading API | Market Data, Trading Balances, & Orders

API reference for trading and reselling. Read instrument specs, market data, balances, trades, and place orders. Only necessary for advanced mode users.

The Trading API exposes everything beyond inference: instrument specifications, market data, balances, past trades, transfers, and direct order placement. You call it to read the state of your account, look up an instrument's spec, or place a limit order yourself instead of letting Auto Mode buy on your behalf.

For the canonical instrument catalog and the spec each instrument is benchmarked against, see Current instruments. For Auto Mode versus Advanced Mode and when to use each, see Auto Mode vs Advanced Mode.

Base URL: https://trading.api.thegrid.ai/v1

Authentication uses Ed25519-signed requests with the headers x-thegrid-signature, x-thegrid-timestamp, and x-thegrid-fingerprint. See Authentication for the signing scheme and keypair generation.

Signing payload: {timestamp}{METHOD}{path}{body}. Use the pathname only (for example /v1/orders), never the query string. Filters such as ?status=filled are applied after signature verification. On POST, the JSON body is included in the signature; query parameters on the URL are not. Full details: Authentication — Sign a request.

Before your first order

Run these checks before placing live orders:

GET /v1/health without auth to confirm the Trading API is reachable.
Signed GET /v1/me to verify credentials and read account_mode.
Signed GET /v1/trading-accounts to inspect USD and per-instrument inventory.
GET /v1/markets to read order_controls such as tick_size, lot_size, min_order_size, and max_order_size.
GET /v1/account/limits?market_id=... to read the order rate limit enforced for your user on that market.

The order rate limit applies to submissions, not fills. Pace create-order requests from order_rate_limits.max_orders_per_second; treat max_orders_per_minute as the corresponding derived minute value. Unused capacity does not accumulate into a larger burst. On 429, honor the Retry-After response header.

There is no bare GET /v1/account Trading endpoint. Use signed GET /v1/me for identity and account mode, GET /v1/account/limits?market_id=... for market-specific order rate limits, then GET /v1/trading-accounts and GET /v1/currency-trading-accounts for token and USD balances.

Auto Mode is the default. Signed reads still work in Auto Mode, but order create/update/cancel returns 403 with auto_mode_trading_restricted after onboarding until you switch the account to Advanced Mode in the app or through the Platform API.

For scripts that place or cancel real orders, run Python unbuffered (python3 -u or PYTHONUNBUFFERED=1) so logs are visible immediately.

Instruments

Instrument specifications, including which models qualify, the Quality Score floor, and supplier conditions. See Current instruments for the human-readable catalog.

List instruments

get

Lists all available instruments with optional filtering and sorting.

Authorizations

x-thegrid-signaturestringRequired

Ed25519 signature authentication. All three headers are required for every request:

Header	Description
`x-thegrid-signature`	Base64-encoded Ed25519 signature of `{timestamp}{METHOD}{path}{body}`
`x-thegrid-timestamp`	Unix timestamp in seconds (must be within 30 seconds of server time)
`x-thegrid-fingerprint`	SHA256 hash of your public key (Base64-encoded, padding stripped)

See full authentication docs

Query parameters

nextstringOptional

Cursor for forward pagination. Pass the next_cursor value from a previous response to fetch the next page. Mutually exclusive with prev.

prevstringOptional

Cursor for backward pagination. Pass the prev_cursor value from a previous response to fetch the previous page. Mutually exclusive with next.

limitinteger · max: 100Optional

Number of items to return per page (max: 100)

Default: 50

order_bystring · enumOptional

Field to sort by

Possible values:

order_directionstring · enumOptional

Sort direction

Possible values:

symbolstringOptional

Filter by exact symbol match (e.g., "text-prime")

instrument_typestring · enumOptional

Filter by instrument type

Possible values:

statusstring · enumOptional

Filter by status

Possible values:

Responses

200

List of instruments

application/json

get/instruments

curl -X GET 'https://trading.api.thegrid.ai/v1/instruments' \
  -H 'x-thegrid-signature: YOUR_SIGNATURE' \
  -H 'x-thegrid-timestamp: YOUR_TIMESTAMP' \
  -H 'x-thegrid-fingerprint: YOUR_FINGERPRINT'

200

List of instruments

{
  "data": [
    {
      "instrument_id": "instrument-6a37e447-7993-4fd1-8776-7d0746f07df2",
      "symbol": "TEXT-STANDARD",
      "name": "Text Standard",
      "description": "Price-optimized models with low-latency, high-throughput and shorter outputs",
      "instrument_type": "ai_commodity",
      "status": "draft",
      "basic_info": {
        "service_type": "chat",
        "model_category": null
      },
      "trading_params": {
        "min_quantity": 1,
        "max_quantity": 100,
        "quantity_increment": 1,
        "fee": "0.000"
      },
      "ai_specs": {
        "context_window": "128000",
        "token_throughput": "100",
        "tokens_per_unit": 1000000,
        "usage": "Price-optimized models with low-latency, high-throughput and shorter outputs",
        "qualifying_models": [
          "gpt-5-mini"
        ],
        "max_output_length": 262100,
        "min_performance_benchmark": 18,
        "min_time_to_first_token_ms": 1320,
        "model_id": null,
        "model_version": null
      }
    }
  ],
  "paging": {
    "has_more": false,
    "next_cursor": null,
    "prev_cursor": null
  }
}

Get instrument details

get

Gets a specific instrument by its ID. Returns full instrument details including trading parameters and AI specifications.

Authorizations

x-thegrid-signaturestringRequired

Ed25519 signature authentication. All three headers are required for every request:

Header	Description
`x-thegrid-signature`	Base64-encoded Ed25519 signature of `{timestamp}{METHOD}{path}{body}`
`x-thegrid-timestamp`	Unix timestamp in seconds (must be within 30 seconds of server time)
`x-thegrid-fingerprint`	SHA256 hash of your public key (Base64-encoded, padding stripped)

See full authentication docs

Path parameters

instrument_idstringRequired

Unique identifier for the instrument. Use the instrument_id returned by GET /v1/markets or GET /v1/instruments.

Responses

200

Instrument details

application/json

404

Not found - The requested resource does not exist

application/json

get/instruments/{instrument_id}

curl -X GET 'https://trading.api.thegrid.ai/v1/instruments/instrument-c18a986c-522b-475a-b319-f2d0ba04a64d' \
  -H 'x-thegrid-signature: YOUR_SIGNATURE' \
  -H 'x-thegrid-timestamp: YOUR_TIMESTAMP' \
  -H 'x-thegrid-fingerprint: YOUR_FINGERPRINT'

{
  "data": {
    "name": "Text Standard",
    "status": "draft",
    "description": "Price-optimized models with low-latency, high-throughput and shorter outputs",
    "symbol": "TEXT-STANDARD",
    "instrument_id": "instrument-6a37e447-7993-4fd1-8776-7d0746f07df2",
    "ai_specs": {
      "context_window": "128000",
      "max_output_length": 262100,
      "min_performance_benchmark": 18,
      "min_time_to_first_token_ms": 1320,
      "model_id": null,
      "model_version": null,
      "qualifying_models": [
        "gpt-5-mini"
      ],
      "token_throughput": "100",
      "tokens_per_unit": 1000000,
      "usage": "Price-optimized models with low-latency, high-throughput and shorter outputs"
    },
    "basic_info": {
      "model_category": null,
      "service_type": "chat"
    },
    "trading_params": {
      "fee": "0.000",
      "max_quantity": 100,
      "min_quantity": 1,
      "quantity_increment": 1
    },
    "instrument_type": "ai_commodity"
  }
}

Markets

A market is a tradable pair: an instrument quoted in a currency. Each instrument has one market. These endpoints expose ticker, depth, and recent trades.

Do not derive IDs by changing case, replacing - with _, or transforming a symbol such as TEXT-PRIME / text-prime. Use market_id exactly as returned by /v1/markets for market endpoints. Use the top-level instrument_id on each market, or the same value in /v1/markets[].instruments[].instrument_id, for instrument and balance endpoints.

List markets

get

Returns markets with instrument details.

Authorizations

x-thegrid-signaturestringRequired

Ed25519 signature authentication. All three headers are required for every request:

Header	Description
`x-thegrid-signature`	Base64-encoded Ed25519 signature of `{timestamp}{METHOD}{path}{body}`
`x-thegrid-timestamp`	Unix timestamp in seconds (must be within 30 seconds of server time)
`x-thegrid-fingerprint`	SHA256 hash of your public key (Base64-encoded, padding stripped)

See full authentication docs

Responses

200

List of markets

application/json

get/markets

curl -X GET 'https://trading.api.thegrid.ai/v1/markets' \
  -H 'x-thegrid-signature: YOUR_SIGNATURE' \
  -H 'x-thegrid-timestamp: YOUR_TIMESTAMP' \
  -H 'x-thegrid-fingerprint: YOUR_FINGERPRINT'

200

List of markets

{
  "data": [
    {
      "market_id": "market_02c2a05b-6157-4a34-9af7-aca1d8c79953",
      "name": "Text Standard",
      "description": "Price-optimized models with low-latency, high-throughput and shorter outputs",
      "market_type": "spot",
      "status": "draft",
      "associated_instruments": [
        "instrument-6a37e447-7993-4fd1-8776-7d0746f07df2"
      ],
      "instrument_id": "instrument-6a37e447-7993-4fd1-8776-7d0746f07df2",
      "instrument_symbol": "TEXT-STANDARD",
      "instrument_name": "Text Standard",
      "instruments": [
        {
          "instrument_id": "instrument-6a37e447-7993-4fd1-8776-7d0746f07df2",
          "instrument_type": "ai_commodity",
          "symbol": "TEXT-STANDARD",
          "name": "Text Standard",
          "description": "Price-optimized models with low-latency, high-throughput and shorter outputs"
        }
      ],
      "created_at": "2026-02-17T16:47:45Z",
      "updated_at": "2026-02-24T12:16:25Z"
    }
  ],
  "paging": {
    "has_more": false,
    "next_cursor": null,
    "prev_cursor": null
  }
}

Get market details

get

Returns market details with instruments.

Authorizations

x-thegrid-signaturestringRequired

Ed25519 signature authentication. All three headers are required for every request:

Header	Description
`x-thegrid-signature`	Base64-encoded Ed25519 signature of `{timestamp}{METHOD}{path}{body}`
`x-thegrid-timestamp`	Unix timestamp in seconds (must be within 30 seconds of server time)
`x-thegrid-fingerprint`	SHA256 hash of your public key (Base64-encoded, padding stripped)

See full authentication docs

Path parameters

market_idstringRequired

Unique identifier for the market (e.g., "market_20536b70-3b9a-44be-aa50-3cd72d1ab8dd")

Responses

200

Market details

application/json

404

Not found - The requested resource does not exist

application/json

get/markets/{market_id}

curl -X GET 'https://trading.api.thegrid.ai/v1/markets/market_20536b70-3b9a-44be-aa50-3cd72d1ab8dd' \
  -H 'x-thegrid-signature: YOUR_SIGNATURE' \
  -H 'x-thegrid-timestamp: YOUR_TIMESTAMP' \
  -H 'x-thegrid-fingerprint: YOUR_FINGERPRINT'

{
  "data": {
    "market_id": "market_20536b70-3b9a-44be-aa50-3cd72d1ab8dd",
    "name": "Text Standard",
    "description": "Price-optimized models with low-latency, high-throughput and shorter outputs",
    "market_type": "spot",
    "status": "draft",
    "created_at": "2026-02-17T16:47:45Z",
    "updated_at": "2026-02-24T12:16:25Z",
    "associated_instruments": [
      "instrument-6a37e447-7993-4fd1-8776-7d0746f07df2"
    ],
    "instrument_id": "instrument-6a37e447-7993-4fd1-8776-7d0746f07df2",
    "instrument_symbol": "TEXT-STANDARD",
    "instrument_name": "Text Standard",
    "instruments": [
      {
        "instrument_id": "instrument-6a37e447-7993-4fd1-8776-7d0746f07df2",
        "instrument_type": "ai_commodity",
        "symbol": "TEXT-STANDARD",
        "name": "Text Standard",
        "description": "Price-optimized models with low-latency, high-throughput and shorter outputs"
      }
    ]
  }
}

Get market ticker

get

Get current ticker data including best bid/ask, last price, and 24h volume.

Authorizations

x-thegrid-signaturestringRequired

Ed25519 signature authentication. All three headers are required for every request:

Header	Description
`x-thegrid-signature`	Base64-encoded Ed25519 signature of `{timestamp}{METHOD}{path}{body}`
`x-thegrid-timestamp`	Unix timestamp in seconds (must be within 30 seconds of server time)
`x-thegrid-fingerprint`	SHA256 hash of your public key (Base64-encoded, padding stripped)

See full authentication docs

Path parameters

market_idstringRequired

Unique identifier for the market (e.g., "market_20536b70-3b9a-44be-aa50-3cd72d1ab8dd")

Responses

200

Ticker data including last trade, bid/ask, and 24h volume

application/json

401

Unauthorized - Invalid or missing authentication headers

application/json

404

Not found - The requested resource does not exist

application/json

get/markets/{market_id}/ticker

curl -X GET 'https://trading.api.thegrid.ai/v1/markets/market_20536b70-3b9a-44be-aa50-3cd72d1ab8dd/ticker' \
  -H 'x-thegrid-signature: YOUR_SIGNATURE' \
  -H 'x-thegrid-timestamp: YOUR_TIMESTAMP' \
  -H 'x-thegrid-fingerprint: YOUR_FINGERPRINT'

{
  "data": {
    "volume_24h": 228,
    "highest_bid": "0.7",
    "lowest_ask": "0.824",
    "last_price": "0.824",
    "last_trade_timestamp": "2026-02-23T09:23:11Z",
    "last_trade_quantity": 1
  }
}

Get order book

get

Get the order book (depth of market) for a specific market.

Authorizations

x-thegrid-signaturestringRequired

Ed25519 signature authentication. All three headers are required for every request:

Header	Description
`x-thegrid-signature`	Base64-encoded Ed25519 signature of `{timestamp}{METHOD}{path}{body}`
`x-thegrid-timestamp`	Unix timestamp in seconds (must be within 30 seconds of server time)
`x-thegrid-fingerprint`	SHA256 hash of your public key (Base64-encoded, padding stripped)

See full authentication docs

Path parameters

market_idstringRequired

Unique identifier for the market (e.g., "market_20536b70-3b9a-44be-aa50-3cd72d1ab8dd")

Query parameters

depthinteger · min: 1 · max: 100Optional

Maximum number of price levels to return per side (bids and asks). Default: 10. Use lower values for quick price checks, higher values for detailed market depth analysis.

Default: 10

Responses

200

Order book data

application/json

get/markets/{market_id}/orderbook

curl -X GET 'https://trading.api.thegrid.ai/v1/markets/market_20536b70-3b9a-44be-aa50-3cd72d1ab8dd/orderbook' \
  -H 'x-thegrid-signature: YOUR_SIGNATURE' \
  -H 'x-thegrid-timestamp: YOUR_TIMESTAMP' \
  -H 'x-thegrid-fingerprint: YOUR_FINGERPRINT'

200

Order book data

{
  "data": {
    "updated_at": "2026-03-06T21:36:12.864367Z",
    "buy": [
      {
        "total": 1,
        "quantity": 1,
        "price": "0.70",
        "order_count": 1
      }
    ],
    "sell": [
      {
        "total": 1573,
        "quantity": 1573,
        "price": "0.85",
        "order_count": 16
      },
      {
        "total": 3973,
        "quantity": 2400,
        "price": "0.90",
        "order_count": 24
      }
    ],
    "highest_bid": "0.7000",
    "lowest_ask": "0.8240"
  }
}

Get market trades

get

Returns all trades for a specific market (not scoped to authenticated user).

Authorizations

x-thegrid-signaturestringRequired

Ed25519 signature authentication. All three headers are required for every request:

Header	Description
`x-thegrid-signature`	Base64-encoded Ed25519 signature of `{timestamp}{METHOD}{path}{body}`
`x-thegrid-timestamp`	Unix timestamp in seconds (must be within 30 seconds of server time)
`x-thegrid-fingerprint`	SHA256 hash of your public key (Base64-encoded, padding stripped)

See full authentication docs

Path parameters

market_idstringRequired

Unique identifier for the market (e.g., "market_20536b70-3b9a-44be-aa50-3cd72d1ab8dd")

Query parameters

statusstringOptional

Filter by trade status

sidestring · enumOptional

Filter by taker side

Possible values:

min_quantityintegerOptional

Filter trades with quantity >= this value

max_quantityintegerOptional

Filter trades with quantity <= this value

min_pricestringOptional

Filter trades with price >= this value

max_pricestringOptional

Filter trades with price <= this value

start_datestring · date-timeOptional

Filter trades executed at or after this time (ISO8601 or Unix timestamp)

end_datestring · date-timeOptional

Filter trades executed at or before this time (ISO8601 or Unix timestamp)

order_bystring · enumOptional

Field to sort by

Possible values:

order_directionstring · enumOptional

Sort direction

Default: ascPossible values:

nextstringOptional

Cursor for forward pagination. Pass the next_cursor value from a previous response to fetch the next page. Mutually exclusive with prev.

prevstringOptional

Cursor for backward pagination. Pass the prev_cursor value from a previous response to fetch the previous page. Mutually exclusive with next.

limitinteger · max: 100Optional

Number of trades to return (max: 100)

Default: 50

Responses

200

Recent trades

application/json

get/markets/{market_id}/trades

curl -X GET 'https://trading.api.thegrid.ai/v1/markets/market_20536b70-3b9a-44be-aa50-3cd72d1ab8dd/trades' \
  -H 'x-thegrid-signature: YOUR_SIGNATURE' \
  -H 'x-thegrid-timestamp: YOUR_TIMESTAMP' \
  -H 'x-thegrid-fingerprint: YOUR_FINGERPRINT'

200

Recent trades

{
  "data": [
    {
      "trade_id": "trade_20f3fddc-bf0f-40ee-89e9-27eb1bfff3e6",
      "market_id": "market_02c2a05b-6157-4a34-9af7-aca1d8c79953",
      "market_name": "Text Standard",
      "instrument_id": "instrument-6a37e447-7993-4fd1-8776-7d0746f07df2",
      "instrument_symbol": "TEXT-STANDARD",
      "instrument_name": "Text Standard",
      "price": "0.8240",
      "quantity": 1,
      "side": "buy",
      "total_value": "0.8240",
      "status": "settled",
      "execution_timestamp": "2026-02-23T09:23:11.081722Z",
      "settlement_timestamp": "2026-02-23T09:23:11.721282Z"
    }
  ],
  "paging": {
    "has_more": false,
    "next_cursor": null,
    "prev_cursor": null
  }
}

Orders

Place market and limit orders, list your open orders, fetch a single order, or cancel one. You can both buy and sell tokens on the order book. Purchased tokens are credited to your Trading account. When those tokens are sold, the proceeds are credited to your Currency Trading (USD) account. See Reselling tokens for the full flow. For when to operate at this level versus letting Auto Mode handle it, see Auto Mode vs Advanced Mode.

For limit orders, send price as a JSON string: "0.68", not 0.68. The Trading API rejects numeric JSON prices with 422 because decimal precision matters. quantity is a whole integer lot count.

If a 422 response mentions order controls, refresh /v1/markets and round to the market's tick_size and lot_size before retrying. Common order-control failures include errors.code and errors.context, including your submitted price / quantity, the client_order_id when provided, and relevant limits such as min_order_size, lot_size, and tick_size.

price_collar_pct is also an order control. When a reference-price band is active, the API validates limit orders at submission and returns 422 price_collar_violation for a price outside the band. Treat the collar as a server-side backstop, not as a substitute for client-side price bounds.

Order identifiers

Use order_id exactly as returned by the API. Compare POST data.order_id with LIST/GET data[].order_id byte-for-byte, and send that value back on GET or DELETE. Do not derive or normalize identifiers.

GET /v1/orders?status=... accepts public aliases and internal lifecycle values. Use open for active resting orders; active, pending, partially_filled, and cancellation_pending for specific open states; filled for filled orders; and closed, cancelled, expired, or rejected for terminal closed orders. Invalid status values return 422.

List trader's orders

get

Returns the authenticated trader's orders using Ed25519 signature authentication.

Authorizations

x-thegrid-signaturestringRequired

Ed25519 signature authentication. All three headers are required for every request:

Header	Description
`x-thegrid-signature`	Base64-encoded Ed25519 signature of `{timestamp}{METHOD}{path}{body}`
`x-thegrid-timestamp`	Unix timestamp in seconds (must be within 30 seconds of server time)
`x-thegrid-fingerprint`	SHA256 hash of your public key (Base64-encoded, padding stripped)

See full authentication docs

Query parameters

market_idstringOptional

Filter by market ID

trader_idstringOptional

Filter by trader ID

instrument_idstringOptional

Filter by instrument ID

sidestring · enumOptional

Filter by order side

Possible values:

statusstring · enumOptional

Filter by order status. open expands to active resting states. Terminal aliases cancelled, expired, and rejected currently return closed terminal orders.

Possible values:

start_datetimestring · date-timeOptional

Filter orders submitted at or after this time (ISO8601 or Unix timestamp)

end_datetimestring · date-timeOptional

Filter orders submitted at or before this time (ISO8601 or Unix timestamp)

order_bystring · enumOptional

Field to sort by (quantity is alias for original_quantity)

Possible values:

order_directionstring · enumOptional

Sort direction

Default: ascPossible values:

nextstringOptional

Cursor for forward pagination. Pass the next_cursor value from a previous response to fetch the next page. Mutually exclusive with prev.

prevstringOptional

Cursor for backward pagination. Pass the prev_cursor value from a previous response to fetch the previous page. Mutually exclusive with next.

limitinteger · max: 100Optional

Number of items to return per page (max: 100)

Default: 50

Responses

200

List of orders

application/json

429

Rate limit exceeded - Too many requests in the current time window

application/json

get/orders

curl -X GET 'https://trading.api.thegrid.ai/v1/orders' \
  -H 'x-thegrid-signature: YOUR_SIGNATURE' \
  -H 'x-thegrid-timestamp: YOUR_TIMESTAMP' \
  -H 'x-thegrid-fingerprint: YOUR_FINGERPRINT'

{
  "data": [
    {
      "order_id": "order_ZVFOAGG4JWRNXMCK",
      "market_id": "market_20536b70-3b9a-44be-aa50-3cd72d1ab8dd",
      "market_name": "Text Prime",
      "instrument_id": "instrument-e0b04b8a-ce1f-4ccc-a4ca-2a47825d69b0",
      "instrument_name": "Text Prime",
      "instrument_symbol": "text-prime",
      "trader_id": "user_1b8dafe4-cea0-415a-8e4c-089c5af0168f",
      "type": "limit",
      "side": "buy",
      "price": "45.50000000",
      "quantity": 100,
      "filled_quantity": 0,
      "filled_at": null,
      "average_price": "45.50000000",
      "fee": "1137.50000000000",
      "status": "active",
      "closure_reason": null,
      "time_in_force": "gtc",
      "stop_price": null,
      "client_order_id": "my-order-123",
      "triggered_by_auto_buy": false,
      "triggered_by_auto_top_up": false,
      "should_autotransfer": null,
      "submitted_at": "2025-12-23T15:15:16Z"
    }
  ],
  "paging": {
    "has_more": false,
    "next_cursor": null,
    "prev_cursor": null
  }
}

Place order

post

Create a new order using Ed25519 signature authentication.

Authorizations

x-thegrid-signaturestringRequired

Ed25519 signature authentication. All three headers are required for every request:

Header	Description
`x-thegrid-signature`	Base64-encoded Ed25519 signature of `{timestamp}{METHOD}{path}{body}`
`x-thegrid-timestamp`	Unix timestamp in seconds (must be within 30 seconds of server time)
`x-thegrid-fingerprint`	SHA256 hash of your public key (Base64-encoded, padding stripped)

See full authentication docs

Body

market_idstringRequired

Market identifier where the order will be placed

Example: market_20536b70-3b9a-44be-aa50-3cd72d1ab8dd

client_order_idstring · nullableOptional

Optional client-provided order ID for idempotency. Must be unique per account. Duplicate IDs will return a 422 error with message "client_order_id already exists".

Example: order_ZVFOAGG4JWRNXMCK

sidestring · enumRequired

Order side: "buy" to purchase the instrument, "sell" to sell. Value is normalized to lowercase.

Example: buyPossible values:

typestring · enumRequired

Order type: "limit" executes at specified price or better, "market" executes immediately at best available price. Value is normalized to lowercase.

Example: limitPossible values:

pricestringOptional

Price per unit in quote currency (USD). Required for limit orders, must be omitted for market orders. Send as a decimal string such as "0.68", not a JSON number such as 0.68; numeric JSON prices are rejected with 422. Must be a positive number >= 0.0001 with at most 4 decimal places (tick size).

Example: 45.50

quantityinteger · min: 1Required

Number of units to buy or sell. Must be a positive integer no greater than the max_order_size returned by GET /v1/markets/{market_id}/controls. Orders above the limit return 422 with errors.code: "quantity_above_max_order_size".

Example: 100

time_in_forcestring · enumOptional

Order duration policy. Value is normalized to lowercase.

gtc (Good Till Cancelled): Order remains active until completely filled or manually cancelled
ioc (Immediate Or Cancel): Order executes immediately for available quantity, remainder is cancelled
fok (Fill Or Kill): Order must be completely filled immediately or entirely cancelled
day: Order expires at the end of the trading day if not filled

Default: gtcExample: gtcPossible values:

should_autotransferboolean · nullableOptional

Optional. Advanced Mode opt-in to automatically transfer a filled buy order's instrument units into the matching Consumption account, so they are immediately usable for inference. Defaults to false when omitted.

Ignored (and effectively always true) in Auto Mode and for auto-buy orders, which always auto-transfer. Ignored for sell orders — only the buy side receives the instrument, so a sell always resolves to false.

Default: falseExample: true

Responses

201

Order created

application/json

400

Invalid order parameters

application/json

401

Unauthorized - Invalid or missing authentication headers

application/json

422

Validation error - Request parameters failed validation

application/json

post/orders

curl -X POST 'https://trading.api.thegrid.ai/v1/orders' \
  -H 'Content-Type: application/json' \
  -H 'x-thegrid-signature: YOUR_SIGNATURE' \
  -H 'x-thegrid-timestamp: YOUR_TIMESTAMP' \
  -H 'x-thegrid-fingerprint: YOUR_FINGERPRINT' \
  -d '{
    "market_id": "market_20536b70-3b9a-44be-aa50-3cd72d1ab8dd",
    "side": "buy",
    "type": "limit",
    "quantity": 1,
    "price": "1.19",
    "should_autotransfer": true
  }'

{
  "data": {
    "order_id": "order_TT64AI5BZNLKUFTL",
    "client_order_id": "my-order-123"
  }
}

Get order details

get

Returns details of a specific order.

Authorizations

x-thegrid-signaturestringRequired

Ed25519 signature authentication. All three headers are required for every request:

Header	Description
`x-thegrid-signature`	Base64-encoded Ed25519 signature of `{timestamp}{METHOD}{path}{body}`
`x-thegrid-timestamp`	Unix timestamp in seconds (must be within 30 seconds of server time)
`x-thegrid-fingerprint`	SHA256 hash of your public key (Base64-encoded, padding stripped)

See full authentication docs

Path parameters

order_idstringRequired

Unique identifier for the order (e.g., "order_TT64AI5BZNLKUFTL")

Responses

200

Order details

application/json

404

Not found - The requested resource does not exist

application/json

get/orders/{order_id}

curl -X GET 'https://trading.api.thegrid.ai/v1/orders/order_ZVFOAGG4JWRNXMCK' \
  -H 'x-thegrid-signature: YOUR_SIGNATURE' \
  -H 'x-thegrid-timestamp: YOUR_TIMESTAMP' \
  -H 'x-thegrid-fingerprint: YOUR_FINGERPRINT'

{
  "data": {
    "order_id": "order_ZVFOAGG4JWRNXMCK",
    "market_id": "market_20536b70-3b9a-44be-aa50-3cd72d1ab8dd",
    "market_name": "Text Prime",
    "instrument_id": "instrument-c18a986c-522b-475a-b319-f2d0ba04a64d",
    "instrument_name": "Text Prime",
    "instrument_symbol": "text-prime",
    "trader_id": "user_0e393ba0-84a3-49e2-9795-59174ddb29a4",
    "type": "limit",
    "side": "buy",
    "price": "45.50000000",
    "quantity": 100,
    "filled_quantity": 0,
    "filled_at": null,
    "average_price": "45.50000000",
    "fee": "1137.50000000000",
    "status": "active",
    "closure_reason": null,
    "time_in_force": "gtc",
    "stop_price": null,
    "client_order_id": null,
    "triggered_by_auto_buy": false,
    "triggered_by_auto_top_up": false,
    "should_autotransfer": null,
    "submitted_at": "2025-12-23T15:15:16Z"
  }
}

Cancel order

delete

Cancel an order using Ed25519 signature authentication.

Authorizations

x-thegrid-signaturestringRequired

Ed25519 signature authentication. All three headers are required for every request:

Header	Description
`x-thegrid-signature`	Base64-encoded Ed25519 signature of `{timestamp}{METHOD}{path}{body}`
`x-thegrid-timestamp`	Unix timestamp in seconds (must be within 30 seconds of server time)
`x-thegrid-fingerprint`	SHA256 hash of your public key (Base64-encoded, padding stripped)

See full authentication docs

Path parameters

order_idstringRequired

Unique identifier for the order (e.g., "order_TT64AI5BZNLKUFTL")

Responses

204

Order cancelled successfully

No content

404

Not found - The requested resource does not exist

application/json

409

Order already cancelled

application/json

delete/orders/{order_id}

curl -X DELETE 'https://trading.api.thegrid.ai/v1/orders/order_ZVFOAGG4JWRNXMCK' \
  -H 'x-thegrid-signature: YOUR_SIGNATURE' \
  -H 'x-thegrid-timestamp: YOUR_TIMESTAMP' \
  -H 'x-thegrid-fingerprint: YOUR_FINGERPRINT'

No content

Trades

Your filled trades, paginated.

Get user's trade history

get

Get your trade history (fills). Results are always the authenticated user's trades. Use the order_id filter to limit results to trades for a specific order (the user's order associated with each trade, as returned in the response order_id field).

Authorizations

x-thegrid-signaturestringRequired

Ed25519 signature authentication. All three headers are required for every request:

Header	Description
`x-thegrid-signature`	Base64-encoded Ed25519 signature of `{timestamp}{METHOD}{path}{body}`
`x-thegrid-timestamp`	Unix timestamp in seconds (must be within 30 seconds of server time)
`x-thegrid-fingerprint`	SHA256 hash of your public key (Base64-encoded, padding stripped)

See full authentication docs

Query parameters

market_idstringOptional

Filter by market ID

instrument_idstringOptional

Filter by instrument ID

trade_idstringOptional

Filter by trade ID

order_idstringOptional

Filter by the user's order ID associated with the trade (canonical filter for "my" trades). Matches the order_id field returned on each trade.

statusstringOptional

Filter by trade status

buyer_order_idstringOptional

Filter by buyer's order ID (legacy; prefer order_id for user's trades)

seller_order_idstringOptional

Filter by seller's order ID (legacy; prefer order_id for user's trades)

triggering_order_idstringOptional

Filter by the order that triggered the trade (legacy; prefer order_id for user's trades)

start_datetimestring · date-timeOptional

Filter trades executed at or after this time (ISO8601 or Unix timestamp)

end_datetimestring · date-timeOptional

Filter trades executed at or before this time (ISO8601 or Unix timestamp)

order_bystring · enumOptional

Field to sort by

Possible values:

order_directionstring · enumOptional

Sort direction

Default: ascPossible values:

nextstringOptional

Cursor for forward pagination. Pass the next_cursor value from a previous response to fetch the next page. Mutually exclusive with prev.

prevstringOptional

Cursor for backward pagination. Pass the prev_cursor value from a previous response to fetch the previous page. Mutually exclusive with next.

limitinteger · max: 100Optional

Number of items to return per page (max: 100)

Default: 50

Responses

200

List of trades

application/json

get/trades

curl -X GET 'https://trading.api.thegrid.ai/v1/trades' \
  -H 'x-thegrid-signature: YOUR_SIGNATURE' \
  -H 'x-thegrid-timestamp: YOUR_TIMESTAMP' \
  -H 'x-thegrid-fingerprint: YOUR_FINGERPRINT'

200

List of trades

{
  "data": [
    {
      "trade_id": "trade_c220ad14-8adb-4394-ab42-831d4ede599e",
      "market_id": "market_1d2124dd-a403-42aa-bc0a-639bd7039b3a",
      "market_name": "Text Prime",
      "instrument_id": "instrument-02c2a05b-6157-4a34-9af7-aca1d8c79953",
      "instrument_symbol": "TEXT-PRIME",
      "instrument_name": "Text Prime",
      "price": "0.8240",
      "quantity": 1,
      "side": "buy",
      "total_value": "0.8240",
      "fee": "0.0000",
      "order_id": "order_3DY2CYJ24HYUDNVQ",
      "trading_account_id": "trading_account_52b11e997c7cdadc",
      "status": "settled",
      "execution_timestamp": "2026-03-06T20:29:12.501213Z",
      "settlement_timestamp": "2026-03-06T20:29:12.654225Z",
      "buyer_should_autotransfer": null
    }
  ],
  "paging": {
    "has_more": false,
    "next_cursor": null,
    "prev_cursor": null
  }
}

Get single trade

get

Returns a single trade with metadata.

Authorizations

x-thegrid-signaturestringRequired

Ed25519 signature authentication. All three headers are required for every request:

Header	Description
`x-thegrid-signature`	Base64-encoded Ed25519 signature of `{timestamp}{METHOD}{path}{body}`
`x-thegrid-timestamp`	Unix timestamp in seconds (must be within 30 seconds of server time)
`x-thegrid-fingerprint`	SHA256 hash of your public key (Base64-encoded, padding stripped)

See full authentication docs

Path parameters

trade_idstringRequired

Unique identifier for the trade (e.g., "trade_d7b40819-0ea6-428b-b00c-deb559206cb7")

Responses

200

Trade details

application/json

404

Not found - The requested resource does not exist

application/json

get/trades/{trade_id}

curl -X GET 'https://trading.api.thegrid.ai/v1/trades/trade_d7b40819-0ea6-428b-b00c-deb559206cb7' \
  -H 'x-thegrid-signature: YOUR_SIGNATURE' \
  -H 'x-thegrid-timestamp: YOUR_TIMESTAMP' \
  -H 'x-thegrid-fingerprint: YOUR_FINGERPRINT'

{
  "data": {
    "trade_id": "trade_c220ad14-8adb-4394-ab42-831d4ede599e",
    "market_id": "market_1d2124dd-a403-42aa-bc0a-639bd7039b3a",
    "market_name": "Text Prime",
    "instrument_id": "instrument-02c2a05b-6157-4a34-9af7-aca1d8c79953",
    "instrument_name": "Text Prime",
    "instrument_symbol": "TEXT-PRIME",
    "order_id": "order_3DY2CYJ24HYUDNVQ",
    "trading_account_id": "trading_account_52b11e997c7cdadc",
    "price": "0.8240",
    "quantity": 1,
    "side": "buy",
    "total_value": "0.8240",
    "fee": "0.0000",
    "status": "settled",
    "execution_timestamp": "2026-03-06T20:29:12.501213Z",
    "settlement_timestamp": "2026-03-06T20:29:12.654225Z",
    "buyer_should_autotransfer": null
  }
}

Accounts

You hold three account types: Consumption accounts (token balances per instrument, drawn down by inference calls), Trading accounts (token balances per instrument, used to place orders), and Currency Trading accounts (your USD balance for funding orders). These endpoints expose all three.

Get effective order limits

get

Returns the order submission rate limit enforced for the authenticated user on a specific market. Pass the exact market_id returned by GET /v1/markets.

Query parameters

market_idstringRequired

Exact market id returned by GET /v1/markets.

Responses

200

Effective order limits for the authenticated user and market.

application/json

401

Unauthorized - Invalid or missing authentication headers

application/json

404

Not found - The requested resource does not exist

application/json

422

Validation error - Request parameters failed validation

application/json

get/account/limits

GET /v1/account/limits?market_id=text HTTP/1.1
Host: trading.api.thegrid.ai
Accept: */*

{
  "data": {
    "market_id": "market_20536b70-3b9a-44be-aa50-3cd72d1ab8dd",
    "order_rate_limits": {
      "scope": "user_market",
      "max_orders_per_second": 10,
      "max_orders_per_minute": 600,
      "burst_capacity": 10,
      "window_seconds": 1
    },
    "response_headers": {
      "limit": "x-ratelimit-limit",
      "remaining": "x-ratelimit-remaining",
      "retry_after": "retry-after"
    }
  }
}

List consumption accounts

get

View your consumption accounts by instrument, including balances and tokens used.

Authorizations

x-thegrid-signaturestringRequired

Ed25519 signature authentication. All three headers are required for every request:

Header	Description
`x-thegrid-signature`	Base64-encoded Ed25519 signature of `{timestamp}{METHOD}{path}{body}`
`x-thegrid-timestamp`	Unix timestamp in seconds (must be within 30 seconds of server time)
`x-thegrid-fingerprint`	SHA256 hash of your public key (Base64-encoded, padding stripped)

See full authentication docs

Query parameters

account_idstringOptional

Filter by account ID

instrument_idstringOptional

Filter by instrument ID

statusstring · enumOptional

Filter by account status

Possible values:

order_bystring · enumOptional

Field to sort by

Possible values:

order_directionstring · enumOptional

Sort direction

Default: ascPossible values:

nextstringOptional

Cursor for forward pagination. Pass the next_cursor value from a previous response to fetch the next page. Mutually exclusive with prev.

prevstringOptional

Cursor for backward pagination. Pass the prev_cursor value from a previous response to fetch the previous page. Mutually exclusive with next.

limitinteger · max: 100Optional

Number of items to return per page (max: 100)

Default: 50

Responses

200

Consumption accounts

application/json

get/consumption-accounts

curl -X GET 'https://trading.api.thegrid.ai/v1/consumption-accounts' \
  -H 'x-thegrid-signature: YOUR_SIGNATURE' \
  -H 'x-thegrid-timestamp: YOUR_TIMESTAMP' \
  -H 'x-thegrid-fingerprint: YOUR_FINGERPRINT'

200

Consumption accounts

{
  "data": [
    {
      "status": "active",
      "created_at": "2026-02-27T20:14:07Z",
      "updated_at": "2026-03-06T20:29:12Z",
      "user_id": "user_5aac8f55-ea85-4451-a896-4833eae16182",
      "account_id": "consumption_account_534f6f09e051a1e2",
      "instrument_id": "instrument-02c2a05b-6157-4a34-9af7-aca1d8c79953",
      "total_balance": 186,
      "tokens_allocated": 3000000,
      "committed_balance": 186,
      "total_commitments": 29,
      "total_deposits": 29,
      "total_transfers_in": 29,
      "total_transfers_out": 0,
      "total_withdrawals": 0,
      "uncommitted_balance": 0,
      "last_deposit_at": "2026-03-06T20:29:12Z",
      "last_transfer_at": null,
      "last_commitment_at": "2026-03-06T20:29:12Z",
      "last_withdrawal_at": null,
      "tokens_available": 1730940
    }
  ],
  "paging": {
    "has_more": false,
    "next_cursor": null,
    "prev_cursor": null
  }
}

Get consumption account details

get

Get detailed information about a specific consumption account.

Authorizations

x-thegrid-signaturestringRequired

Ed25519 signature authentication. All three headers are required for every request:

Header	Description
`x-thegrid-signature`	Base64-encoded Ed25519 signature of `{timestamp}{METHOD}{path}{body}`
`x-thegrid-timestamp`	Unix timestamp in seconds (must be within 30 seconds of server time)
`x-thegrid-fingerprint`	SHA256 hash of your public key (Base64-encoded, padding stripped)

See full authentication docs

Path parameters

account_idstringRequired

Unique identifier for the consumption account (e.g., "consumption_account_534f6f09e051a1e2")

Responses

200

Consumption account details

application/json

404

Not found - The requested resource does not exist

application/json

get/consumption-accounts/{account_id}

curl -X GET 'https://trading.api.thegrid.ai/v1/consumption-accounts/consumption_account_cbf73393ef9e2ed0' \
  -H 'x-thegrid-signature: YOUR_SIGNATURE' \
  -H 'x-thegrid-timestamp: YOUR_TIMESTAMP' \
  -H 'x-thegrid-fingerprint: YOUR_FINGERPRINT'

{
  "data": {
    "status": "active",
    "created_at": "2026-02-27T20:14:07Z",
    "updated_at": "2026-03-06T20:29:12Z",
    "user_id": "user_5aac8f55-ea85-4451-a896-4833eae16182",
    "account_id": "consumption_account_534f6f09e051a1e2",
    "instrument_id": "instrument-02c2a05b-6157-4a34-9af7-aca1d8c79953",
    "total_balance": 186,
    "tokens_allocated": 3000000,
    "committed_balance": 186,
    "total_commitments": 29,
    "total_deposits": 29,
    "total_transfers_in": 29,
    "total_transfers_out": 0,
    "total_withdrawals": 0,
    "uncommitted_balance": 0,
    "last_deposit_at": "2026-03-06T20:29:12Z",
    "last_transfer_at": null,
    "last_commitment_at": "2026-03-06T20:29:12Z",
    "last_withdrawal_at": null
  }
}

List trading account balances

get

List all trading account balances across instruments.

Authorizations

x-thegrid-signaturestringRequired

Ed25519 signature authentication. All three headers are required for every request:

Header	Description
`x-thegrid-signature`	Base64-encoded Ed25519 signature of `{timestamp}{METHOD}{path}{body}`
`x-thegrid-timestamp`	Unix timestamp in seconds (must be within 30 seconds of server time)
`x-thegrid-fingerprint`	SHA256 hash of your public key (Base64-encoded, padding stripped)

See full authentication docs

Query parameters

account_idstringOptional

Filter by account ID

market_idstringOptional

Filter by market ID

instrument_idstringOptional

Filter by instrument ID

statusstring · enumOptional

Filter by account status

Possible values:

order_bystring · enumOptional

Field to sort by

Possible values:

order_directionstring · enumOptional

Sort direction

Default: ascPossible values:

nextstringOptional

Cursor for forward pagination. Pass the next_cursor value from a previous response to fetch the next page. Mutually exclusive with prev.

prevstringOptional

Cursor for backward pagination. Pass the prev_cursor value from a previous response to fetch the previous page. Mutually exclusive with next.

limitinteger · max: 100Optional

Number of items to return per page (max: 100)

Default: 50

Responses

200

List of trading accounts

application/json

get/trading-accounts

curl -X GET 'https://trading.api.thegrid.ai/v1/trading-accounts' \
  -H 'x-thegrid-signature: YOUR_SIGNATURE' \
  -H 'x-thegrid-timestamp: YOUR_TIMESTAMP' \
  -H 'x-thegrid-fingerprint: YOUR_FINGERPRINT'

200

List of trading accounts

{
  "data": [
    {
      "status": "active",
      "created_at": "2026-02-26T13:46:06Z",
      "updated_at": "2026-02-27T19:35:03Z",
      "user_id": "user_5aac8f55-ea85-4451-a896-4833eae16182",
      "account_id": "trading_account_86e1fd9b00bac94c",
      "instrument_name": "Text Standard",
      "instrument_id": "instrument-6a37e447-7993-4fd1-8776-7d0746f07df2",
      "market_id": "market_20536b70-3b9a-44be-aa50-3cd72d1ab8dd",
      "market_name": "Text Standard",
      "total_balance": "0",
      "available_balance": "0",
      "last_trade_price": "0.0927",
      "last_deposit_at": null,
      "last_withdrawal_at": null,
      "instrument_symbol": "TEXT-STANDARD",
      "locked_balance": "0",
      "last_trading_activity_at": null
    }
  ],
  "paging": {
    "has_more": false,
    "next_cursor": null,
    "prev_cursor": null
  }
}

Get trading account details

get

Get detailed information about a specific trading account.

Authorizations

x-thegrid-signaturestringRequired

Ed25519 signature authentication. All three headers are required for every request:

Header	Description
`x-thegrid-signature`	Base64-encoded Ed25519 signature of `{timestamp}{METHOD}{path}{body}`
`x-thegrid-timestamp`	Unix timestamp in seconds (must be within 30 seconds of server time)
`x-thegrid-fingerprint`	SHA256 hash of your public key (Base64-encoded, padding stripped)

See full authentication docs

Path parameters

account_idstringRequired

Unique identifier for the trading account (e.g., "trading_account_86e1fd9b00bac94c")

Responses

200

Trading account details

application/json

404

Not found - The requested resource does not exist

application/json

get/trading-accounts/{account_id}

curl -X GET 'https://trading.api.thegrid.ai/v1/trading-accounts/trading_account_86e1fd9b00bac94c' \
  -H 'x-thegrid-signature: YOUR_SIGNATURE' \
  -H 'x-thegrid-timestamp: YOUR_TIMESTAMP' \
  -H 'x-thegrid-fingerprint: YOUR_FINGERPRINT'

{
  "data": {
    "account_id": "trading_account_86e1fd9b00bac94c",
    "user_id": "user_5aac8f55-ea85-4451-a896-4833eae16182",
    "instrument_id": "instrument-6a37e447-7993-4fd1-8776-7d0746f07df2",
    "instrument_name": "Text Standard",
    "instrument_symbol": "TEXT-STANDARD",
    "market_id": "market_20536b70-3b9a-44be-aa50-3cd72d1ab8dd",
    "market_name": "Text Standard",
    "total_balance": "0",
    "available_balance": "0",
    "locked_balance": "0",
    "last_trade_price": "0.0927",
    "status": "active",
    "last_deposit_at": null,
    "last_trading_activity_at": null,
    "last_withdrawal_at": null,
    "created_at": "2026-02-26T13:46:06Z",
    "updated_at": "2026-02-27T19:35:03Z"
  }
}

List currency trading accounts

get

List all currency trading accounts (USD, etc.).

Authorizations

x-thegrid-signaturestringRequired

Ed25519 signature authentication. All three headers are required for every request:

Header	Description
`x-thegrid-signature`	Base64-encoded Ed25519 signature of `{timestamp}{METHOD}{path}{body}`
`x-thegrid-timestamp`	Unix timestamp in seconds (must be within 30 seconds of server time)
`x-thegrid-fingerprint`	SHA256 hash of your public key (Base64-encoded, padding stripped)

See full authentication docs

Query parameters

user_idstringOptional

Filter by user ID

account_idstringOptional

Filter by account ID

currencystringOptional

Filter by currency (e.g., "USD")

statusstring · enumOptional

Filter by account status

Possible values:

order_bystring · enumOptional

Field to sort by

Possible values:

order_directionstring · enumOptional

Sort direction

Default: ascPossible values:

nextstringOptional

Cursor for forward pagination. Pass the next_cursor value from a previous response to fetch the next page. Mutually exclusive with prev.

prevstringOptional

Cursor for backward pagination. Pass the prev_cursor value from a previous response to fetch the previous page. Mutually exclusive with next.

limitinteger · max: 100Optional

Number of items to return per page (max: 100)

Default: 50

Responses

200

List of currency trading accounts

application/json

get/currency-trading-accounts

curl -X GET 'https://trading.api.thegrid.ai/v1/currency-trading-accounts' \
  -H 'x-thegrid-signature: YOUR_SIGNATURE' \
  -H 'x-thegrid-timestamp: YOUR_TIMESTAMP' \
  -H 'x-thegrid-fingerprint: YOUR_FINGERPRINT'

200

List of currency trading accounts

{
  "data": [
    {
      "status": "active",
      "currency": "usd",
      "created_at": "2026-02-19T19:55:39Z",
      "updated_at": "2026-03-06T20:29:12Z",
      "user_id": "user_5aac8f55-ea85-4451-a896-4833eae16182",
      "account_id": "currency_trading_account_cd2f277756f2ae60",
      "total_balance": "256.1906",
      "available_balance": "256.1906",
      "last_deposit_at": "2026-02-23T18:02:46Z",
      "last_withdrawal_at": null,
      "locked_balance": "0.0000",
      "last_trading_activity_at": null
    }
  ],
  "paging": {
    "has_more": false,
    "next_cursor": null,
    "prev_cursor": null
  }
}

Get currency account details

get

Get specific currency trading account details.

Authorizations

x-thegrid-signaturestringRequired

Ed25519 signature authentication. All three headers are required for every request:

Header	Description
`x-thegrid-signature`	Base64-encoded Ed25519 signature of `{timestamp}{METHOD}{path}{body}`
`x-thegrid-timestamp`	Unix timestamp in seconds (must be within 30 seconds of server time)
`x-thegrid-fingerprint`	SHA256 hash of your public key (Base64-encoded, padding stripped)

See full authentication docs

Path parameters

account_idstringRequired

Unique identifier for the currency trading account (e.g., "currency_trading_account_cd2f277756f2ae60")

Responses

200

Currency account details

application/json

404

Not found - The requested resource does not exist

application/json

get/currency-trading-accounts/{account_id}

curl -X GET 'https://trading.api.thegrid.ai/v1/currency-trading-accounts/currency_trading_account_cd2f277756f2ae60' \
  -H 'x-thegrid-signature: YOUR_SIGNATURE' \
  -H 'x-thegrid-timestamp: YOUR_TIMESTAMP' \
  -H 'x-thegrid-fingerprint: YOUR_FINGERPRINT'

{
  "data": {
    "status": "active",
    "currency": "usd",
    "created_at": "2026-02-19T19:55:39Z",
    "updated_at": "2026-03-06T20:29:12Z",
    "user_id": "user_5aac8f55-ea85-4451-a896-4833eae16182",
    "account_id": "currency_trading_account_cd2f277756f2ae60",
    "total_balance": "256.1906",
    "available_balance": "256.1906",
    "last_deposit_at": "2026-02-23T18:02:46Z",
    "last_withdrawal_at": null,
    "locked_balance": "0.0000",
    "last_trading_activity_at": null
  }
}

Transfers

Transfers move tokens from a Trading account to a Consumption account. They are one-way and final: once tokens land in a Consumption account, they can only be drawn down by inference calls. This is also the boundary for reselling: tokens are sellable while they sit in the Trading account, so transfer what you plan to consume and leave the rest where it can still be sold.

Transfer to consumption

post

Transfers a specified quantity of an instrument from trading account to consumption account.

Authorizations

x-thegrid-signaturestringRequired

Ed25519 signature authentication. All three headers are required for every request:

Header	Description
`x-thegrid-signature`	Base64-encoded Ed25519 signature of `{timestamp}{METHOD}{path}{body}`
`x-thegrid-timestamp`	Unix timestamp in seconds (must be within 30 seconds of server time)
`x-thegrid-fingerprint`	SHA256 hash of your public key (Base64-encoded, padding stripped)

See full authentication docs

Body

instrument_idstringRequired

The instrument to transfer from your trading account to your consumption account

Example: instrument-c18a986c-522b-475a-b319-f2d0ba04a64d

quantityinteger · min: 1Required

Number of units to transfer. Must have sufficient available balance in your trading account.

Example: 100

Responses

202

Transfer initiated (processed asynchronously)

application/json

statusstring · enumOptionalPossible values:

transfer_idstringOptional

post/transfers/trading-to-consumption

curl -X POST 'https://trading.api.thegrid.ai/v1/transfers/trading-to-consumption' \
  -H 'Content-Type: application/json' \
  -H 'x-thegrid-signature: YOUR_SIGNATURE' \
  -H 'x-thegrid-timestamp: YOUR_TIMESTAMP' \
  -H 'x-thegrid-fingerprint: YOUR_FINGERPRINT' \
  -d '{
    "instrument_id": "instrument-e0b04b8a-ce1f-4ccc-a4ca-2a47825d69b0",
    "quantity": 100
  }'

202

Transfer initiated (processed asynchronously)

{
  "status": "success",
  "transfer_id": "text"
}

List transfer history

get

Returns transfer histories for authenticated user.

Authorizations

x-thegrid-signaturestringRequired

Ed25519 signature authentication. All three headers are required for every request:

Header	Description
`x-thegrid-signature`	Base64-encoded Ed25519 signature of `{timestamp}{METHOD}{path}{body}`
`x-thegrid-timestamp`	Unix timestamp in seconds (must be within 30 seconds of server time)
`x-thegrid-fingerprint`	SHA256 hash of your public key (Base64-encoded, padding stripped)

See full authentication docs

Query parameters

market_idstringOptional

Filter by market ID

instrument_idstringOptional

Filter by instrument ID

start_datetimestring · date-timeOptional

Filter transfers at or after this time (ISO8601 or Unix timestamp)

end_datetimestring · date-timeOptional

Filter transfers at or before this time (ISO8601 or Unix timestamp)

order_bystring · enumOptional

Field to sort by

Possible values:

order_directionstring · enumOptional

Sort direction

Default: ascPossible values:

nextstringOptional

Cursor for forward pagination. Pass the next_cursor value from a previous response to fetch the next page. Mutually exclusive with prev.

prevstringOptional

Cursor for backward pagination. Pass the prev_cursor value from a previous response to fetch the previous page. Mutually exclusive with next.

limitinteger · max: 100Optional

Number of items to return per page (max: 100)

Default: 50

Responses

200

Transfer history

application/json

get/transfer-histories

curl -X GET 'https://trading.api.thegrid.ai/v1/transfer-histories' \
  -H 'x-thegrid-signature: YOUR_SIGNATURE' \
  -H 'x-thegrid-timestamp: YOUR_TIMESTAMP' \
  -H 'x-thegrid-fingerprint: YOUR_FINGERPRINT'

200

Transfer history

{
  "data": [
    {
      "inserted_at": "2026-03-06T20:29:12.716364Z",
      "updated_at": "2026-03-06T20:29:12.716364Z",
      "account_id": "consumption_account_534f6f09e051a1e2",
      "quantity": 1,
      "instrument_id": "instrument-02c2a05b-6157-4a34-9af7-aca1d8c79953",
      "market_id": "market_1d2124dd-a403-42aa-bc0a-639bd7039b3a",
      "instrument_name": "Text Prime",
      "transfer_id": "auto_transfer_trade_c220ad14-8adb-4394-ab42-831d4ede599e",
      "sender_account_id": "trading_account_52b11e997c7cdadc",
      "transferred_at": "2026-03-06T20:29:12.687641Z"
    }
  ],
  "paging": {
    "has_more": false,
    "next_cursor": null,
    "prev_cursor": null
  }
}

Price histories

Time-series OHLCV data for instruments.

Get price history (OHLCV)

get

Returns OHLCV (Open, High, Low, Close, Volume) candle data for charting. Use this endpoint to build price charts and analyze historical market data.

Authorizations

x-thegrid-signaturestringRequired

Ed25519 signature authentication. All three headers are required for every request:

Header	Description
`x-thegrid-signature`	Base64-encoded Ed25519 signature of `{timestamp}{METHOD}{path}{body}`
`x-thegrid-timestamp`	Unix timestamp in seconds (must be within 30 seconds of server time)
`x-thegrid-fingerprint`	SHA256 hash of your public key (Base64-encoded, padding stripped)

See full authentication docs

Query parameters

market_idstringOptional

Filter by market ID

resolutionstring · enumOptional

Candle resolution/timeframe. Determines the time period each candle represents.

Possible values:

fromintegerOptional

Start of time range (Unix timestamp in seconds)

tointegerOptional

End of time range (Unix timestamp in seconds)

order_bystring · enumOptional

Field to sort by

Possible values:

order_directionstring · enumOptional

Sort direction

Default: ascPossible values:

nextstringOptional

Cursor for forward pagination. Pass the next_cursor value from a previous response to fetch the next page. Mutually exclusive with prev.

prevstringOptional

Cursor for backward pagination. Pass the prev_cursor value from a previous response to fetch the previous page. Mutually exclusive with next.

limitinteger · max: 100Optional

Number of items to return per page (max: 100)

Default: 50

Responses

200

OHLCV candle data

application/json

401

Unauthorized - Invalid or missing authentication headers

application/json

422

Validation error - Request parameters failed validation

application/json

get/price-histories

curl -X GET 'https://trading.api.thegrid.ai/v1/price-histories' \
  -H 'x-thegrid-signature: YOUR_SIGNATURE' \
  -H 'x-thegrid-timestamp: YOUR_TIMESTAMP' \
  -H 'x-thegrid-fingerprint: YOUR_FINGERPRINT'

{
  "data": [
    {
      "time": "2026-02-12T07:00:00Z",
      "market_id": "market_20536b70-3b9a-44be-aa50-3cd72d1ab8dd",
      "resolution": "1h",
      "open": "45.00",
      "high": "45.75",
      "low": "44.80",
      "close": "45.50",
      "volume": 1200,
      "trade_count": 48
    },
    {
      "time": "2026-02-12T08:00:00Z",
      "market_id": "market_20536b70-3b9a-44be-aa50-3cd72d1ab8dd",
      "resolution": "1h",
      "open": "45.50",
      "high": "46.25",
      "low": "45.25",
      "close": "46.00",
      "volume": 1500,
      "trade_count": 62
    }
  ],
  "paging": {
    "has_more": true,
    "next_cursor": "eyJpZCI6InByaWNlXzEyMyJ9",
    "prev_cursor": null
  }
}

Where next

Authentication: Ed25519 keypair generation and the request-signing scheme
Current instruments: the human-readable instrument catalog
Errors and rate limits
Trading bot safety patterns

PreviousConsumption API

NextPlatform API

Last updated 1 month ago

Was this helpful?