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

​
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".
​
gold_amount
number
required
$GOLD the user will sell, in human decimal. Must be positive.
​
slippage_bps
integer
Slippage tolerance in basis points. Default 50 (0.5%). Ignored if min_usdc_out is provided.
​
min_usdc_out
number
Absolute minimum USDC to receive (human decimal). If supplied, overrides slippage_bps.

​
Response

​
trade_id
string
Trade identifier, prefixed trd_.
​
side
string
Always "sell".
​
quote
object
​
partially_signed_transaction
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>..."
}