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

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

​
Request Body

​
grail_user_id
string
required
GRAIL user ID (prefixed gu_). User must belong to the authenticated partner, be active, and have kyc_level: "full".
​
denomination_id
string
required
Denomination ID from List Denominations, e.g., "pk_tola_1".
​
city
string
required
City of pickup. Must match the denomination’s registered city (case-insensitive).

​
Response

​
redemption_id
string
Redemption identifier, prefixed red_. Use with Submit Redemption, Get Redemption, and Cancel Redemption.
​
quote
object
​
partially_signed_transaction
string
Base64-encoded Solana transaction, signed by GRAIL. Co-sign with the user wallet only (no partner signature on redemptions).

​
Errors

HTTPerrorWhen
400invalid_requestMissing grail_user_id, denomination_id, or city
400invalid_denominationdenomination_id not found or inactive
400invalid_citycity doesn’t match the denomination’s registered city
400kyc_level_insufficientUser’s KYC level is not full
403partner_mismatchUser belongs to a different partner
403user_suspendedUser status is suspended
404user_not_foundNo user with the given grail_user_id
503pricing_unavailableGold 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>..."
}