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"
}
Redemptions
Get Redemption
Fetches a single redemption by ID. Returns 404 while the redemption is at the internal quoted state.
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 givenredemption_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
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"
}