Selling Gold

Overview

A sell converts the user’s $GOLD tokens back into USDC on Solana. The flow and signer set are identical to Buying Gold — the only differences are the endpoint (/v1/sell) and the input/output fields (you specify gold_amount instead of usdc_amount; min_usdc_out replaces min_gold_out). Because everything else is the same — three signers, blockhash TTL, stateless quote, indexer-driven row writes — this guide focuses on the differences.

Signers

Same as buy: GRAIL + partner + user. Three signatures required.

Step 1 — Quote

BASE=https://grail-stack-dev.onrender.com

curl -s -X POST "$BASE/v1/sell" \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "grail_user_id": "gu_6b60956e-a8ee-4de2-8128-04c7fdf633c3",
    "gold_amount": 0.01,
    "slippage_bps": 50
  }'

Response:

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

Sell-specific input fields

Field	Required	Notes
`gold_amount`	yes	`$GOLD` tokens to sell (human decimal).
`slippage_bps`	no	Default `50` (0.5%). Ignored if `min_usdc_out` is set.
`min_usdc_out`	no	Absolute USDC floor. Overrides `slippage_bps` when provided.

Sell-specific fee note

The quote’s fee_bps often differs from a buy quote — on-chain inti uses separate market_open_fee_bps and market_close_fee_bps values, with the applicable side depending on market state. A partner’s IntegratorV2 on-chain config can also have a market_fee_override that forces one or the other. You don’t need to manage this — GRAIL reads the effective rate from the partner’s on-chain config when it builds the quote.

Step 2 — Co-sign with partner + user

Identical to buy:

import { Transaction, Keypair } from "@solana/web3.js";
import bs58 from "bs58";

const tx = Transaction.from(Buffer.from(quote.partially_signed_transaction, "base64"));
tx.partialSign(Keypair.fromSecretKey(bs58.decode(PARTNER_SECRET_BASE58)));
tx.partialSign(Keypair.fromSecretKey(bs58.decode(USER_SECRET_BASE58)));
const signedB64 = tx.serialize().toString("base64");

The only difference from a buy tx is the on-chain program’s internal direction — GOLD out of the user’s token account, USDC in. You don’t touch that; it’s baked into the partial-signed transaction.

Step 3 — Submit

curl -s -X POST "$BASE/v1/sell/$TRADE_ID/submit" \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"signed_tx\":\"$SIGNED_B64\"}"

Response:

{
  "trade_id": "trd_8b21d7f3-2a4c-4b5e-9d1f-3e8a7c6b5d4e",
  "tx_hash": "3xJk9Pq2n...base58"
}

Pure passthrough — no DB write. As with buys, you can also broadcast directly to any Solana RPC.

Step 4 — Wait and fetch

sleep 15
curl -s "$BASE/v1/trades/$TRADE_ID" -H "x-api-key: $API_KEY"

The response shape is identical to Get Trade, with side: "sell". usdc_amount is the output, gold_amount is the input.

End-to-end script

Same as the buy reference script in Buying Gold, with two changes:

Quote endpoint → /v1/sell
Quote body → {"grail_user_id":"...", "gold_amount":0.01, "slippage_bps":50}

Everything else — co-sign, submit endpoint (/v1/sell/$TRADE_ID/submit), indexer polling — is identical.

Next steps

Flow complete? Move on to Redeeming Physical Gold for physical fulfillment.

Guides

Integration Guides

Overview

Signers

Step 1 — Quote

Sell-specific input fields

Sell-specific fee note

Step 2 — Co-sign with partner + user

Step 3 — Submit

Step 4 — Wait and fetch

End-to-end script

Next steps

​Overview

​Signers

​Step 1 — Quote

​Sell-specific input fields

​Sell-specific fee note

​Step 2 — Co-sign with partner + user

​Step 3 — Submit

​Step 4 — Wait and fetch

​End-to-end script

​Next steps

Overview

Signers

Step 1 — Quote

Sell-specific input fields

Sell-specific fee note

Step 2 — Co-sign with partner + user

Step 3 — Submit

Step 4 — Wait and fetch

End-to-end script

Next steps