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
Request Body
GRAIL user ID (prefixed
gu_). User must belong to the authenticated partner, be active, and have kyc_level: "full".Denomination ID from List Denominations, e.g.,
"pk_tola_1".Response
Redemption identifier, prefixed
red_. Use with Submit Redemption, Get Redemption, and Cancel Redemption.Show properties
Show properties
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>..."
}