Quote 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>..."
}

POST

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

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>..."
}

Submit Buy Submit Sell

API Reference

General

Authentication

Partner

Users

Denominations

Trades

Redemptions

Overview

Headers

Request Body

Response

Errors

​Overview

​Headers

​Request Body

​Response

​Errors

Overview

Headers

Request Body

Response

Errors