curl https://grail-stack-dev.onrender.com/v1/trades/trd_4e7a1b8f-9c32-4a91-b3e6-7f12a8d4c5e9 \
-H "x-api-key: grail_partner_<hex>"
{
"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
Get Trade
Fetches a single trade by ID. Returns 404 until the indexer has written the row.
GET
/
v1
/
trades
/
{trade_id}
curl https://grail-stack-dev.onrender.com/v1/trades/trd_4e7a1b8f-9c32-4a91-b3e6-7f12a8d4c5e9 \
-H "x-api-key: grail_partner_<hex>"
{
"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
Returns theTrade record for a trade_id. Because GRAIL’s indexer is the sole writer of trade rows, this endpoint returns 404 until the transaction has confirmed on-chain and been indexed (typically 10–15 seconds on devnet after submit).
Partner-scoped — returns 403 partner_mismatch if the trade belongs to a different partner.
Headers
string
required
A valid
PARTNER scope key.Path Parameters
string
required
Trade identifier (prefixed
trd_).Response
string
Trade identifier.
string
"buy" or "sell".string
Final status written by the indexer:
"confirmed" or "failed".number
USDC amount (input on buys, output on sells). For
failed trades, the value is from the transaction’s memo; the opposing side and fees are 0 because the on-chain program never computed them.number
$GOLD amount (output on buys, input on sells). Same caveat on failed trades.number
Gold price at the time the on-chain program executed.
integer
Fee rate applied, in basis points.
number
Fee in USDC.
string
Solana transaction signature (base58).
string
ISO-8601 timestamp of row creation (when the indexer wrote the trade).
string
ISO-8601 timestamp of most recent update.
Errors
| HTTP | error | When |
|---|---|---|
| 401 | unauthorized | Missing or invalid x-api-key |
| 403 | partner_mismatch | Trade belongs to a different partner |
| 404 | trade_not_found | No trade row for this trade_id (often: indexer hasn’t caught up yet) |
curl https://grail-stack-dev.onrender.com/v1/trades/trd_4e7a1b8f-9c32-4a91-b3e6-7f12a8d4c5e9 \
-H "x-api-key: grail_partner_<hex>"
{
"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"
}