Get Redemption

curl https://grail-stack-dev.onrender.com/v1/redemptions/red_a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d \
  -H "x-api-key: grail_partner_<hex>"

{
  "redemption_id": "red_a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "status": "submitted",
  "denomination": "1 Tola",
  "weight_g": 11.664,
  "city": "karachi",
  "quote": {
    "spot_price_usd": 4872.84,
    "gold_value_usd": 1827.34,
    "fee_usd": 0,
    "total_usd": 1827.34,
    "tokens_required": "0.375006"
  },
  "submitted_tx_hash": "4ABC...base58",
  "cancellation_reason": null,
  "created_at": "2026-04-17T11:00:00.000Z",
  "updated_at": "2026-04-17T11:00:15.000Z"
}

GET

redemptions

{id}

curl https://grail-stack-dev.onrender.com/v1/redemptions/red_a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d \
  -H "x-api-key: grail_partner_<hex>"

{
  "redemption_id": "red_a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "status": "submitted",
  "denomination": "1 Tola",
  "weight_g": 11.664,
  "city": "karachi",
  "quote": {
    "spot_price_usd": 4872.84,
    "gold_value_usd": 1827.34,
    "fee_usd": 0,
    "total_usd": 1827.34,
    "tokens_required": "0.375006"
  },
  "submitted_tx_hash": "4ABC...base58",
  "cancellation_reason": null,
  "created_at": "2026-04-17T11:00:00.000Z",
  "updated_at": "2026-04-17T11:00:15.000Z"
}

Overview

Returns the redemption record for a given redemption_id. Partner-scoped.

While the redemption is still at the internal quoted status (i.e., before the user’s transaction has been confirmed on-chain and picked up by the indexer), this endpoint returns 404 redemption_not_found. The record becomes visible once status advances to submitted.

Headers

string

required

A valid PARTNER scope key.

Path Parameters

string

required

Redemption identifier (prefixed red_).

Response

string

Redemption identifier.

string

Current status. One of: submitted, preparing, ready, collected, cancellation_requested, cancelled, failed.

string

Denomination label, e.g., "1 Tola".

number

Weight of the denomination in grams.

string

City of pickup.

object

Show properties

number

Gold spot price at quote time.

number

USD value of the gold at spot.

number

Partner redemption fee in USD.

number

gold_value_usd + fee_usd.

string

$GOLD tokens required, formatted to 6 decimal places.

string | null

Solana transaction signature (base58) of the on-chain GOLD transfer, or null.

string | null

If the redemption was cancelled, the reason supplied at cancel time; otherwise null.

string

ISO-8601 timestamp of row creation.

string

ISO-8601 timestamp of most recent status update.

Status lifecycle

quoted (internal)
  └─► submitted  ← indexer writes after on-chain confirmation
        ├─► preparing ── ready ── collected  (ORO admin advances)
        └─► cancellation_requested ── cancelled

quoted is never exposed. collected and cancelled are terminal.

Errors

HTTP	`error`	When
401	`unauthorized`	Missing or invalid `x-api-key`
403	`partner_mismatch`	Redemption belongs to a different partner
404	`redemption_not_found`	No redemption row at or past `submitted` for this id

curl https://grail-stack-dev.onrender.com/v1/redemptions/red_a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d \
  -H "x-api-key: grail_partner_<hex>"

{
  "redemption_id": "red_a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "status": "submitted",
  "denomination": "1 Tola",
  "weight_g": 11.664,
  "city": "karachi",
  "quote": {
    "spot_price_usd": 4872.84,
    "gold_value_usd": 1827.34,
    "fee_usd": 0,
    "total_usd": 1827.34,
    "tokens_required": "0.375006"
  },
  "submitted_tx_hash": "4ABC...base58",
  "cancellation_reason": null,
  "created_at": "2026-04-17T11:00:00.000Z",
  "updated_at": "2026-04-17T11:00:15.000Z"
}

Submit Redemption List Redemptions

API Reference

General

Authentication

Partner

Users

Denominations

Trades

Redemptions

Overview

Headers

Path Parameters

Response

Status lifecycle

Errors

​Overview

​Headers

​Path Parameters

​Response

​Status lifecycle

​Errors

Overview

Headers

Path Parameters

Response

Status lifecycle

Errors