/conversions/quote

POST/v1/agent/conversions/quote

Create a stateful conversion quote

Requires API-key authentication (agentAuth, agentId).

Purpose: create a 60-second, single-use conversion quote.

Auth and scope: header-key auth or OAuth agent:simulate.

Quote creation uses agent:simulate because it prices and stores a short-lived quote without broadcasting. Only POST /v1/agent/conversions requires agent:conversions:write.

Idempotency: required.

Request:

json

example

{
  "from_asset": "USDC",
  "to_asset": "ETH",
  "amount": "1",
  "slippage_percent": 1
}

Use exactly one of amount or amount_usd. amount is a decimal asset-unit string in the from_asset. slippage_percent is a number.

Response:

json

example

{
  "ok": true,
  "quote": {
    "quote_id": "uuid",
    "from_asset": "USDC",
    "to_asset": "ETH",
    "from_amount": "1",
    "expected_out": "0.0003",
    "min_amount_out": "0.000297",
    "slippage_percent": 1,
    "human_rate": "string",
    "route": {
      "legs": [
        {
          "protocol_id": "string",
          "protocol_name": "string",
          "pool_address": "0x...",
          "from_asset": "USDC",
          "to_asset": "ETH",
          "expected_out": "0.0003",
          "fee_bps": 0
        }
      ],
      "intermediate_assets": []
    },
    "expires_at": "2026-05-16T00:00:00.000Z",
    "expires_in_seconds": 60
  }
}

Common errors: validation_failed, asset_not_allowed, protocol_not_allowed, limit_exceeded, price_stale, rate_limited.

Related recipe: Convert with a Quote.