curl -X POST https://grail-stack-dev.onrender.com/v1/redemptions \
-H "x-api-key: grail_partner_<hex>" \
-H "Content-Type: application/json" \
-d '{
"grail_user_id": "gu_6b60956e-a8ee-4de2-8128-04c7fdf633c3",
"denomination_id": "pk_tola_1",
"city": "karachi"
}'
{
"redemption_id": "red_a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
"quote": {
"denomination": "1 Tola",
"weight_g": 11.664,
"spot_price_usd": 4872.84,
"gold_value_usd": 1827.34,
"fee_usd": 0,
"total_usd": 1827.34,
"tokens_required": "0.375006"
},
"partially_signed_transaction": "AQAAAAABAAEC...<base64>..."
}
Redemptions
Quote Redemption
Quotes a physical-gold redemption. Returns a partially-signed transaction for the user to co-sign.
POST
/
v1
/
redemptions
curl -X POST https://grail-stack-dev.onrender.com/v1/redemptions \
-H "x-api-key: grail_partner_<hex>" \
-H "Content-Type: application/json" \
-d '{
"grail_user_id": "gu_6b60956e-a8ee-4de2-8128-04c7fdf633c3",
"denomination_id": "pk_tola_1",
"city": "karachi"
}'
{
"redemption_id": "red_a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
"quote": {
"denomination": "1 Tola",
"weight_g": 11.664,
"spot_price_usd": 4872.84,
"gold_value_usd": 1827.34,
"fee_usd": 0,
"total_usd": 1827.34,
"tokens_required": "0.375006"
},
"partially_signed_transaction": "AQAAAAABAAEC...<base64>..."
}
Overview
Quotes a redemption of$GOLD tokens for a physical-gold denomination and returns the transaction the user must sign to transfer the tokens into GRAIL’s escrow.
Unlike trades, a redemption does write a row at quote time — with status quoted (internal-only, not returned via Get Redemption until the indexer advances it to submitted after the user’s transaction confirms on-chain).
Only the user wallet needs to co-sign — there is no partner signature on redemptions. The transaction transfers tokens_required $GOLD from the user’s wallet to GRAIL’s escrow.
The partial-signed transaction expires in ~60 seconds (Solana
recentBlockhash TTL). Re-quote if you miss the window.Headers
string
required
A valid
PARTNER scope key.Request Body
string
required
GRAIL user ID (prefixed
gu_). User must belong to the authenticated partner, be active, and have kyc_level: "full".string
required
Denomination ID from List Denominations, e.g.,
"pk_tola_1".string
required
City of pickup. Must match the denomination’s registered
city (case-insensitive).Response
string
Redemption identifier, prefixed
red_. Use with Submit Redemption, Get Redemption, and Cancel Redemption.object
Show properties
Show properties
string
Denomination label, e.g.,
"1 Tola".number
Weight of the denomination in grams.
number
Gold spot price in USD per troy ounce at quote time.
number
USD value of the gold at spot.
number
Partner redemption fee in USD (partner’s
fee_percentage × gold_value_usd).number
gold_value_usd + fee_usd. The USD value of tokens_required.string
$GOLD tokens the user must transfer, formatted to 6 decimal places. This is a token amount, not USD — do not confuse with total_usd.string
Base64-encoded Solana transaction, signed by GRAIL. Co-sign with the user wallet only (no partner signature on redemptions).
Errors
| HTTP | error | When |
|---|---|---|
| 400 | invalid_request | Missing grail_user_id, denomination_id, or city |
| 400 | invalid_denomination | denomination_id not found or inactive |
| 400 | invalid_city | city doesn’t match the denomination’s registered city |
| 400 | kyc_level_insufficient | User’s KYC level is not full |
| 403 | partner_mismatch | User belongs to a different partner |
| 403 | user_suspended | User status is suspended |
| 404 | user_not_found | No user with the given grail_user_id |
| 503 | pricing_unavailable | Gold price oracle unreachable or returned stale data |
curl -X POST https://grail-stack-dev.onrender.com/v1/redemptions \
-H "x-api-key: grail_partner_<hex>" \
-H "Content-Type: application/json" \
-d '{
"grail_user_id": "gu_6b60956e-a8ee-4de2-8128-04c7fdf633c3",
"denomination_id": "pk_tola_1",
"city": "karachi"
}'
{
"redemption_id": "red_a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
"quote": {
"denomination": "1 Tola",
"weight_g": 11.664,
"spot_price_usd": 4872.84,
"gold_value_usd": 1827.34,
"fee_usd": 0,
"total_usd": 1827.34,
"tokens_required": "0.375006"
},
"partially_signed_transaction": "AQAAAAABAAEC...<base64>..."
}