Skip to main content
GET
/
v1
/
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

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

​
Path Parameters

​
id
string
required
Redemption identifier (prefixed red_).

​
Response

​
redemption_id
string
Redemption identifier.
​
status
string
Current status. One of: submitted, preparing, ready, collected, cancellation_requested, cancelled, failed.
​
denomination
string
Denomination label, e.g., "1 Tola".
​
weight_g
number
Weight of the denomination in grams.
​
city
string
City of pickup.
​
quote
object
​
submitted_tx_hash
string | null
Solana transaction signature (base58) of the on-chain GOLD transfer, or null.
​
cancellation_reason
string | null
If the redemption was cancelled, the reason supplied at cancel time; otherwise null.
​
created_at
string
ISO-8601 timestamp of row creation.
​
updated_at
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

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