curl -X POST https://grail-stack-dev.onrender.com/v1/sell \
-H "x-api-key: grail_partner_<hex>" \
-H "Content-Type: application/json" \
-d '{
"grail_user_id": "gu_6b60956e-a8ee-4de2-8128-04c7fdf633c3",
"gold_amount": 0.01,
"slippage_bps": 50
}'
{
"trade_id": "trd_8b21d7f3-2a4c-4b5e-9d1f-3e8a7c6b5d4e",
"side": "sell",
"quote": {
"gold_amount": 0.01,
"usdc_amount": 48.49,
"price_per_troy_oz": 4872.84,
"fee_bps": 75,
"fee_usd": 0.37,
"min_usdc_out": 48.25
},
"partially_signed_transaction": "AQAAAAABAAEC...<base64>..."
}
Trades
Quote Sell
Stateless quote for selling $GOLD for USDC. Returns a partially-signed Solana transaction to co-sign and submit.
POST
/
v1
/
sell
curl -X POST https://grail-stack-dev.onrender.com/v1/sell \
-H "x-api-key: grail_partner_<hex>" \
-H "Content-Type: application/json" \
-d '{
"grail_user_id": "gu_6b60956e-a8ee-4de2-8128-04c7fdf633c3",
"gold_amount": 0.01,
"slippage_bps": 50
}'
{
"trade_id": "trd_8b21d7f3-2a4c-4b5e-9d1f-3e8a7c6b5d4e",
"side": "sell",
"quote": {
"gold_amount": 0.01,
"usdc_amount": 48.49,
"price_per_troy_oz": 4872.84,
"fee_bps": 75,
"fee_usd": 0.37,
"min_usdc_out": 48.25
},
"partially_signed_transaction": "AQAAAAABAAEC...<base64>..."
}
Overview
Builds a sell transaction ($GOLD → USDC) and returns it partially-signed by GRAIL. The client must co-sign with the partner wallet and the user wallet, then either call Submit Sell or broadcast directly to a Solana RPC.
Stateless — no database row is created at quote time. The Trade row is written by the indexer once the transaction confirms on-chain.
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".number
required
$GOLD the user will sell, in human decimal. Must be positive.integer
Slippage tolerance in basis points. Default
50 (0.5%). Ignored if min_usdc_out is provided.number
Absolute minimum USDC to receive (human decimal). If supplied, overrides
slippage_bps.Response
string
Trade identifier, prefixed
trd_.string
Always
"sell".object
Show properties
Show properties
number
Input
$GOLD (echo of request).number
Expected USDC output at quote-time spot price (post-fee, pre-slippage).
number
Gold spot price in USD per troy ounce at quote time.
integer
Fee rate applied in basis points.
number
Fee in USDC deducted from the output.
number
Minimum USDC the tx will accept — slippage floor.
string
Base64-encoded Solana transaction, signed by GRAIL. Co-sign with partner + user and submit.
Errors
Same error set as Quote Buy:invalid_request, kyc_level_insufficient, onchain_config_missing, wallet_missing, partner_mismatch, user_suspended, user_not_found, pricing_unavailable.
curl -X POST https://grail-stack-dev.onrender.com/v1/sell \
-H "x-api-key: grail_partner_<hex>" \
-H "Content-Type: application/json" \
-d '{
"grail_user_id": "gu_6b60956e-a8ee-4de2-8128-04c7fdf633c3",
"gold_amount": 0.01,
"slippage_bps": 50
}'
{
"trade_id": "trd_8b21d7f3-2a4c-4b5e-9d1f-3e8a7c6b5d4e",
"side": "sell",
"quote": {
"gold_amount": 0.01,
"usdc_amount": 48.49,
"price_per_troy_oz": 4872.84,
"fee_bps": 75,
"fee_usd": 0.37,
"min_usdc_out": 48.25
},
"partially_signed_transaction": "AQAAAAABAAEC...<base64>..."
}