Skip to main content
GET
/
v1
/
trades
curl "https://grail-stack-dev.onrender.com/v1/trades?side=buy&status=confirmed" \
  -H "x-api-key: grail_partner_<hex>"

{
  "trades": [
    {
      "trade_id": "trd_4e7a1b8f-9c32-4a91-b3e6-7f12a8d4c5e9",
      "side": "buy",
      "status": "confirmed",
      "usdc_amount": 100,
      "gold_amount": 0.020528,
      "price_per_troy_oz": 4872.84,
      "fee_bps": 50,
      "fee_usd": 0.50,
      "submitted_tx_hash": "5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp...base58",
      "created_at": "2026-04-17T10:18:30.000Z",
      "updated_at": "2026-04-17T10:18:30.000Z"
    }
  ]
}

​
Overview

Lists trade rows for the authenticated partner. All filters are optional; omit them to list everything. Results are ordered by created_at descending. Only trades that the indexer has written are returned. Trades that have just been submitted but not yet confirmed on-chain do not appear until the indexer processes them.

​
Headers

​
x-api-key
string
required
A valid PARTNER scope key.

​
Query Parameters

​
grail_user_id
string
Filter to a single user. If the user doesn’t exist, returns an empty list (not a 404).
​
side
string
Filter by side: "buy" or "sell".
​
status
string
Filter by status: "confirmed" or "failed".

​
Response

​
trades
array
Array of trade objects — same shape as Get Trade.

​
Errors

HTTPerrorWhen
401unauthorizedMissing or invalid x-api-key
curl "https://grail-stack-dev.onrender.com/v1/trades?side=buy&status=confirmed" \
  -H "x-api-key: grail_partner_<hex>"

{
  "trades": [
    {
      "trade_id": "trd_4e7a1b8f-9c32-4a91-b3e6-7f12a8d4c5e9",
      "side": "buy",
      "status": "confirmed",
      "usdc_amount": 100,
      "gold_amount": 0.020528,
      "price_per_troy_oz": 4872.84,
      "fee_bps": 50,
      "fee_usd": 0.50,
      "submitted_tx_hash": "5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp...base58",
      "created_at": "2026-04-17T10:18:30.000Z",
      "updated_at": "2026-04-17T10:18:30.000Z"
    }
  ]
}