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"
}
]
}
Trades
List Trades
Lists trades for the authenticated partner, with optional filters.
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 bycreated_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
string
required
A valid
PARTNER scope key.Query Parameters
string
Filter to a single user. If the user doesn’t exist, returns an empty list (not a 404).
string
Filter by side:
"buy" or "sell".string
Filter by status:
"confirmed" or "failed".Response
Errors
| HTTP | error | When |
|---|---|---|
| 401 | unauthorized | Missing 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"
}
]
}