> ## Documentation Index
> Fetch the complete documentation index at: https://docs.grail.oro.finance/llms.txt
> Use this file to discover all available pages before exploring further.

# Quote Sell

> Stateless quote for selling $GOLD for USDC. Returns a partially-signed Solana transaction to co-sign and submit.

## 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](/api-reference/trades/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.

<Warning>
  The partial-signed transaction expires in **\~60 seconds** (Solana `recentBlockhash` TTL). Re-quote if you miss the window.
</Warning>

## Headers

<ParamField header="x-api-key" type="string" required>
  A valid `PARTNER` scope key.
</ParamField>

## Request Body

<ParamField body="grail_user_id" type="string" required>
  GRAIL user ID (prefixed `gu_`). User must belong to the authenticated partner, be `active`, and have `kyc_level: "full"`.
</ParamField>

<ParamField body="gold_amount" type="number" required>
  `$GOLD` the user will sell, in human decimal. Must be positive.
</ParamField>

<ParamField body="slippage_bps" type="integer">
  Slippage tolerance in basis points. Default `50` (0.5%). Ignored if `min_usdc_out` is provided.
</ParamField>

<ParamField body="min_usdc_out" type="number">
  Absolute minimum USDC to receive (human decimal). If supplied, overrides `slippage_bps`.
</ParamField>

## Response

<ResponseField name="trade_id" type="string">
  Trade identifier, prefixed `trd_`.
</ResponseField>

<ResponseField name="side" type="string">
  Always `"sell"`.
</ResponseField>

<ResponseField name="quote" type="object">
  <Expandable title="properties">
    <ResponseField name="gold_amount" type="number">
      Input `$GOLD` (echo of request).
    </ResponseField>

    <ResponseField name="usdc_amount" type="number">
      Expected USDC output at quote-time spot price (post-fee, pre-slippage).
    </ResponseField>

    <ResponseField name="price_per_troy_oz" type="number">
      Gold spot price in USD per troy ounce at quote time.
    </ResponseField>

    <ResponseField name="fee_bps" type="integer">
      Fee rate applied in basis points.
    </ResponseField>

    <ResponseField name="fee_usd" type="number">
      Fee in USDC deducted from the output.
    </ResponseField>

    <ResponseField name="min_usdc_out" type="number">
      Minimum USDC the tx will accept — slippage floor.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="partially_signed_transaction" type="string">
  Base64-encoded Solana transaction, signed by GRAIL. Co-sign with partner + user and submit.
</ResponseField>

## Errors

Same error set as [Quote Buy](/api-reference/trades/quote-buy): `invalid_request`, `kyc_level_insufficient`, `onchain_config_missing`, `wallet_missing`, `partner_mismatch`, `user_suspended`, `user_not_found`, `pricing_unavailable`.

<RequestExample>
  ```bash cURL theme={null}
  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
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "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>..."
  }
  ```
</ResponseExample>