> ## Documentation Index
> Fetch the complete documentation index at: https://docs.grail.oro.finance/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Trade

> Fetches a single trade by ID. Returns 404 until the indexer has written the row.

## 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

<ParamField header="x-api-key" type="string" required>
  A valid `PARTNER` scope key.
</ParamField>

## Path Parameters

<ParamField path="trade_id" type="string" required>
  Trade identifier (prefixed `trd_`).
</ParamField>

## Response

<ResponseField name="trade_id" type="string">
  Trade identifier.
</ResponseField>

<ResponseField name="side" type="string">
  `"buy"` or `"sell"`.
</ResponseField>

<ResponseField name="status" type="string">
  Final status written by the indexer: `"confirmed"` or `"failed"`.
</ResponseField>

<ResponseField name="usdc_amount" type="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.
</ResponseField>

<ResponseField name="gold_amount" type="number">
  `$GOLD` amount (output on buys, input on sells). Same caveat on `failed` trades.
</ResponseField>

<ResponseField name="price_per_troy_oz" type="number">
  Gold price at the time the on-chain program executed.
</ResponseField>

<ResponseField name="fee_bps" type="integer">
  Fee rate applied, in basis points.
</ResponseField>

<ResponseField name="fee_usd" type="number">
  Fee in USDC.
</ResponseField>

<ResponseField name="submitted_tx_hash" type="string">
  Solana transaction signature (base58).
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO-8601 timestamp of row creation (when the indexer wrote the trade).
</ResponseField>

<ResponseField name="updated_at" type="string">
  ISO-8601 timestamp of most recent update.
</ResponseField>

## 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) |

<RequestExample>
  ```bash cURL theme={null}
  curl https://grail-stack-dev.onrender.com/v1/trades/trd_4e7a1b8f-9c32-4a91-b3e6-7f12a8d4c5e9 \
    -H "x-api-key: grail_partner_<hex>"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "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"
  }
  ```
</ResponseExample>