List 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"
    }
  ]
}

GET

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

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

array

Array of trade objects — same shape as Get Trade.

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"
    }
  ]
}

Get Trade Quote Redemption

API Reference

General

Authentication

Partner

Users

Denominations

Trades

Redemptions

Overview

Headers

Query Parameters

Response

Errors

​Overview

​Headers

​Query Parameters

​Response

​Errors

Overview

Headers

Query Parameters

Response

Errors