Skip to main content
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 the Trade 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

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

​
Path Parameters

​
trade_id
string
required
Trade identifier (prefixed trd_).

​
Response

​
trade_id
string
Trade identifier.
​
side
string
"buy" or "sell".
​
status
string
Final status written by the indexer: "confirmed" or "failed".
​
usdc_amount
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.
​
gold_amount
number
$GOLD amount (output on buys, input on sells). Same caveat on failed trades.
​
price_per_troy_oz
number
Gold price at the time the on-chain program executed.
​
fee_bps
integer
Fee rate applied, in basis points.
​
fee_usd
number
Fee in USDC.
​
submitted_tx_hash
string
Solana transaction signature (base58).
​
created_at
string
ISO-8601 timestamp of row creation (when the indexer wrote the trade).
​
updated_at
string
ISO-8601 timestamp of most recent update.

​
Errors

HTTPerrorWhen
401unauthorizedMissing or invalid x-api-key
403partner_mismatchTrade belongs to a different partner
404trade_not_foundNo 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"
}