{
  "openapi": "3.1.0",
  "info": {
    "title": "Treasures Finance B2B Public API",
    "version": "v1",
    "description": "Public B2B API for tokenized stock discovery, quoting and trade execution, USDC\nbridging across Solana and Ethereum, and portfolio + trade history reads.\n\n**Wire format.** All token amounts, USDC amounts, shares, prices and bps-derived\ndecimals are JSON **strings** to avoid float drift. Integer fields\n(`expires_at`, `*_bps`, `quote_index`, timestamps in seconds) are JSON numbers.\n\n**Auth.** Only `POST /quote/buy`, `POST /quote/sell`, `POST /bridge/quote` and the four\n`/signals-orders` routes (`POST /signals-orders/exit/plan`, `POST /signals-orders/exit`,\n`POST /signals-orders/rebalance/plan` and `POST /signals-orders/rebalance`) require\n`ownership_proof` (wallet-key signature over a canonical challenge, see `OwnershipProof`).\n`POST /trade/submit` is gated by the per-leg signed payload itself.\n\nThese routes **require** an integrator API key in `X-API-Key` (see `IntegratorApiKey`):\n\n- `GET /settlements`\n- the `/payouts` routes (your integrator fees and their payouts)\n- `POST /quote/preview` (which binds no wallet, so the key is what identifies the caller)\n- `GET /stocks/{ticker}` (whose profile, analyst, earnings and news blocks are served to\n  contracted integrators only)\n- the `/signals` routes (strategy target-weight books, served to contracted integrators)\n- the `/signals-orders` routes (the orders that exit a book from your wallet, or rebalance it\n  to the book)\n- `POST /trade/submit/batch` (many signed submits in one request).\n\nEvery other route may be called anonymously.\n\n**Integrator API keys are optional on every route but those, and never\nignored.** If you send `X-API-Key` on any route, a key beginning `tik_`/`trk_`\nis verified and a bad one is rejected rather than silently downgraded to\nanonymous:\n\n| Condition | Response |\n|---|---|\n| Malformed or unknown key | `401 invalid_api_key` |\n| Revoked key | `403 key_revoked` |\n| Your organisation is suspended | `403 integrator_suspended` |\n| Read-only (`trk_`) key on a non-reporting route | `403 insufficient_scope` |\n\nA **`trk_` reporting key reaches the reporting routes and nothing else.**\nToday that is exactly one route: `GET /settlements`. Everywhere else on this\nAPI it answers `403 insufficient_scope`. That refusal is the point: it is what\nmakes the key safe to hand to a third party for reporting. Use your `tik_` key\nfor API access; it works on the reporting routes too. A credential for a\ndifferent Treasures plane (e.g. a `twk_` wallet key) is not addressed to this\nAPI and is ignored, so those requests are served anonymously.\n\n**Rate limits.** Per-IP and per-(IP, wallet) sliding windows.\nPresenting a valid key adds a per-organisation bucket shared by all of your\nkeys, a cross-IP aggregate bound, additive to the per-IP limits rather than a\nraised ceiling. Upstream 429s propagate as `502 provider_unavailable`.\n"
  },
  "servers": [
    {
      "url": "https://api.treasures.io/public/v1",
      "description": "Production"
    }
  ],
  "security": [],
  "tags": [
    {
      "name": "Stocks",
      "description": "Catalog and live price discovery."
    },
    {
      "name": "Quote",
      "description": "Quote issuance and aggregate status polling."
    },
    {
      "name": "Trade",
      "description": "Atomic submission of signed quote legs."
    },
    {
      "name": "Bridge",
      "description": "Cross-chain USDC bridging."
    },
    {
      "name": "Portfolio",
      "description": "Wallet-scoped holdings, reconciled vs on-chain."
    },
    {
      "name": "Trades",
      "description": "Wallet-scoped trade history."
    },
    {
      "name": "Settlements",
      "description": "Your organisation's own settled trade ledger, for reporting."
    },
    {
      "name": "Payouts",
      "description": "What you are owed in integrator fees, and the payouts that paid them."
    },
    {
      "name": "Signals",
      "description": "Current and historical target-weight books of the copy-trading strategies published to integrators."
    }
  ],
  "paths": {
    "/stocks": {
      "get": {
        "operationId": "listStocks",
        "tags": [
          "Stocks"
        ],
        "summary": "List active tradable stocks (catalog + live enrichment)",
        "description": "Catalog with tradfi snapshot and onchain aggregate.\nCached server-side for 30 s.\n\nWithout query parameters this is the whole catalog in ticker order. `q`, `sort` and\n`order` search and reorder it; `page` splits the result into pages of 25 and adds\n`page`, `next_page` and `total` to the response. Search, sort and paging run over the\nsame cached snapshot, so they add no provider calls.\n",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Case-insensitive substring match on `ticker`, `name` or a venue's `token_ticker` (e.g. `AAPLx`), 1 to 100 characters after trimming.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 100,
              "example": "apple"
            }
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "description": "Sort key. Omitted with `order` also omitted, the catalog's ticker order stands.",
            "schema": {
              "$ref": "#/components/schemas/StockSortKey"
            }
          },
          {
            "name": "order",
            "in": "query",
            "required": false,
            "description": "`asc` or `desc`. Defaults to `asc` for `ticker` and `desc` for every metric. Sent without `sort`, it orders by `ticker`. Ticker order is always the catalog's own (`desc` reverses it), so it matches the unparameterised read row for row.",
            "schema": {
              "type": "string",
              "enum": [
                "asc",
                "desc"
              ]
            }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "1-based page of 25 rows. Omitted, the response carries every matching row and no paging fields.",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StocksListResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/stocks/tickers": {
      "get": {
        "operationId": "listStockTickers",
        "tags": [
          "Stocks"
        ],
        "summary": "List active tickers (no price enrichment)",
        "description": "Catalog rows only. Cached server-side for 5 min, so it is cheap to poll.",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StocksTickersResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/stocks/prices": {
      "get": {
        "operationId": "getStockPrices",
        "tags": [
          "Stocks"
        ],
        "summary": "Live per-protocol prices for requested tickers",
        "parameters": [
          {
            "name": "tickers",
            "in": "query",
            "required": true,
            "description": "Comma-separated list, 1–50 tickers. Each item matches `^[A-Z0-9.-]{1,10}$`\n**case-insensitively**; the server normalizes to uppercase before lookup.\n",
            "schema": {
              "type": "string",
              "example": "AAPL,NVDA"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StockPricesResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "502": {
            "$ref": "#/components/responses/ProviderUnavailable"
          }
        }
      }
    },
    "/stocks/{ticker}": {
      "get": {
        "operationId": "getStockDetail",
        "tags": [
          "Stocks"
        ],
        "summary": "Company / ticker details (integrator key required)",
        "description": "Everything the catalog knows about one ticker: profile (description, sector, industry,\nwebsite, logo), listings per (protocol, chain), the B2B tradfi block, pre/post-market\nprint, market session, analyst consensus and grades, next earnings, and the latest news.\nEvery block is best-effort and degrades to `null` on its own. Requires `X-API-Key`\n(a general `tik_` key; reporting keys are refused). Cached 60 s.\n\nThere is deliberately **no `onchain` block** on this route; for per-protocol on-chain\nprices call `GET /stocks/prices`.\n\nThis route takes no query parameters: any is a 400, as on the three sibling stocks routes.\n",
        "security": [
          {
            "IntegratorApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "ticker",
            "in": "path",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/Ticker"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StockDetailResponse"
                },
                "examples": {
                  "aapl": {
                    "summary": "US large-cap during the regular session",
                    "description": "Illustrative values. `exchange`, `exchange_country` and `data_delay` are present because the venue resolved; `display_ticker` is absent because a US row's bare `ticker` is already the display form. `extended_hours` is null during the regular session.",
                    "value": {
                      "ticker": "AAPL",
                      "name": "Apple Inc.",
                      "description": "Apple designs, manufactures and markets smartphones, personal computers, tablets, wearables and accessories, and sells related services.",
                      "sector": "Technology",
                      "industry": "Consumer Electronics",
                      "website": "https://www.apple.com",
                      "logo_url": "https://assets.treasures.io/logos/AAPL.png",
                      "available_chains": [
                        "sol",
                        "eth",
                        "robinhood",
                        "base"
                      ],
                      "exchange": "NASDAQ",
                      "exchange_country": "US",
                      "data_delay": "realtime",
                      "listings": [
                        {
                          "protocol": "ondo",
                          "chain": "sol",
                          "address": "9wJ6gxvqYc6P3kHhTTMVSaMxfsBGBN47f3T8kdgWvB2d",
                          "share_multiplier": "1",
                          "token_ticker": "AAPLon",
                          "min_trade_size_usd": 21
                        },
                        {
                          "protocol": "xstocks",
                          "chain": "eth",
                          "address": "0x9d275685dc284c8eb1c79f6aba7a63dc75ec890a",
                          "share_multiplier": "1",
                          "token_ticker": "AAPLx"
                        },
                        {
                          "protocol": "robinhood",
                          "chain": "robinhood",
                          "address": "0xaF3D76f1834A1d425780943C99Ea8A608f8a93f9",
                          "share_multiplier": "1",
                          "token_ticker": "AAPL"
                        },
                        {
                          "protocol": "coinbase",
                          "chain": "base",
                          "address": "0xb200000000000000000000c2e324d24d7eecd1fb",
                          "share_multiplier": "1",
                          "token_ticker": "AAPL"
                        }
                      ],
                      "tradfi": {
                        "current_price_usd": "227.63",
                        "currency": "USD",
                        "price_native": "227.63",
                        "change_24h_pct": "1.12",
                        "market_cap_usd": "3461000000000",
                        "pe_ttm": "34.6",
                        "volume_shares": "48213000",
                        "volume_1d_usd": "10974000000",
                        "as_of": 1789056000
                      },
                      "extended_hours": null,
                      "market_session": "regular",
                      "is_holiday": false,
                      "holiday_name": null,
                      "analyst": {
                        "rating": "Buy",
                        "target_price_usd": "250.00"
                      },
                      "analyst_grades": [
                        {
                          "firm": "Morgan Stanley",
                          "grade": "Overweight",
                          "action": "buy",
                          "date": "2026-09-08"
                        },
                        {
                          "firm": "Barclays",
                          "grade": "Equal Weight",
                          "action": "hold",
                          "date": "2026-09-02"
                        }
                      ],
                      "earnings": {
                        "next_date": "2026-10-30",
                        "eps_estimate": "1.62"
                      },
                      "news": [
                        {
                          "title": "Apple unveils new iPhone lineup",
                          "url": "https://example.com/apple-iphone",
                          "publisher": "Reuters",
                          "published_at": "2026-09-09T17:05:00Z",
                          "type": "news",
                          "snippet": "Apple introduced its next iPhone generation at its annual September event."
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "401": {
            "description": "Missing or invalid integrator key"
          },
          "403": {
            "description": "Reporting key presented (insufficient_scope)"
          },
          "404": {
            "description": "Unknown or inactive ticker"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/quote/buy": {
      "post": {
        "operationId": "quoteBuy",
        "tags": [
          "Quote"
        ],
        "summary": "Quote USDC → stock token (one leg per chain the ticker lists, better first)",
        "description": "Requires `ownership_proof` for each wallet provided. Returns one best leg per\nchain the ticker lists (up to six: sol, eth, robinhood, base, arbitrum, bnb): the\nsignable quote legs (one per chain). On `bnb` (BNB Smart Chain, 56) three\nprotocols compete for that one leg, so a pinned bnb request should carry\n`protocol` as well as `chain`. Cache the returned `quote_id`;\nevery signed leg is submitted together at `/trade/submit`.\nSet `quote_only: true` for a non-executable price preview (the wallet need\nnot be funded; `quote_id`, `expires_at`, and `signable_payloads` are omitted).\n\n`502 provider_unavailable` also fires when a `priority:\"speed\"` cross-chain leg's\nsol-origin deposit fails to compile (an RPC blockhash read failure): the whole quote\nis refused, not just that cell; retry.\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/QuoteBuyRequest"
              },
              "examples": {
                "default_routing": {
                  "summary": "Auto-route across every chain the ticker lists",
                  "value": {
                    "ticker": "AAPL",
                    "amount_usdc": "100",
                    "max_slippage_bps": 100,
                    "sol_wallet": "7Np41oeYqPefeNQEHSv1UDhYrehxin3NStELsSKCTFNP",
                    "eth_wallet": "0x1111111111111111111111111111111111111111",
                    "ownership_proof": {
                      "sol_signature": "3sJ7...(base58 signature over the challenge)",
                      "eth_signature": "0x5b2c...(65-byte signature over the challenge)",
                      "issued_at": 1789056000
                    }
                  }
                },
                "speed_transaction": {
                  "summary": "Speed route on base, wallet pays gas (`execution` omitted = `\"transaction\"`)",
                  "description": "Returns one or two complete unsigned transactions (`evm_eip1559_tx` on base, `evm_legacy_tx` on robinhood) to sign whole and return as `evm_signed_tx`. The wallet needs native ETH on that chain. See the `speed_transaction_pair` response example.",
                  "value": {
                    "ticker": "AAPL",
                    "amount_usdc": "100",
                    "chain": "base",
                    "priority": "speed",
                    "max_slippage_bps": 100,
                    "eth_wallet": "0x1111111111111111111111111111111111111111",
                    "ownership_proof": {
                      "eth_signature": "0x5b2c...(65-byte signature over the challenge)",
                      "issued_at": 1789056000
                    }
                  }
                },
                "speed_user_operation": {
                  "summary": "Speed route on base, your paymaster pays gas (`execution:\"user_operation\"`)",
                  "description": "Returns one `evm_calls` payload to pack into a sponsored ERC-4337 v0.7 UserOperation from an EIP-7702-delegated Modular Account v2 wallet and return as `evm_user_operation`. Requires `priority:\"speed\"`. See the `speed_user_operation` response example.",
                  "value": {
                    "ticker": "AAPL",
                    "amount_usdc": "100",
                    "chain": "base",
                    "priority": "speed",
                    "execution": "user_operation",
                    "max_slippage_bps": 100,
                    "eth_wallet": "0x1111111111111111111111111111111111111111",
                    "ownership_proof": {
                      "eth_signature": "0x5b2c...(65-byte signature over the challenge)",
                      "issued_at": 1789056000
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/QuoteBuyResponse"
                },
                "examples": {
                  "speed_transaction_pair": {
                    "summary": "`priority:\"speed\"` on base: wallet not yet approved, so `approve` then `swap`",
                    "description": "`tx_hex` / `tx_base64` are truncated here; each is a complete unsigned transaction with nonce, gas and fees already set. Sign both bytes-as-is and return one `evm_signed_tx` per payload, in this order. An already-approved wallet gets the `swap` payload only. `gasless:false` and `estimated_gas_usd` are the caller's own gas.",
                    "value": {
                      "quote_id": "7Kp3mQxT9vLw2nRb5cYd8FhJ",
                      "side": "buy",
                      "ticker": "AAPL",
                      "expires_at": 1789056042,
                      "tradfi_reference": {
                        "price_usd": "227.63",
                        "market_status": "open",
                        "as_of": 1789055995
                      },
                      "quotes": [
                        {
                          "quote_index": 0,
                          "chain": "base",
                          "protocol": "coinbase",
                          "price_usdc_per_share": "228.11",
                          "estimated_output_shares": "0.438385",
                          "estimated_output_tokens": "0.438385",
                          "base_asset": "usdc",
                          "amount_base": "100",
                          "cost_breakdown_bps": {
                            "treasures_fee_bps": 10,
                            "dex_swap_fee_bps": 5,
                            "estimated_slippage_bps": 0,
                            "price_impact_bps": 0,
                            "slippage_vs_tradfi_bps": 21
                          },
                          "gasless": false,
                          "estimated_gas_usd": "0.0031",
                          "signable_payloads": [
                            {
                              "type": "evm_eip1559_tx",
                              "role": "approve",
                              "from": "0x1111111111111111111111111111111111111111",
                              "tx_hex": "0x02f8b2822105",
                              "tx_base64": "AvisgiEF",
                              "approval_spender": null,
                              "chain_id": 8453,
                              "nonce": 41,
                              "gas": "58000",
                              "max_fee_per_gas": "12000000",
                              "max_priority_fee_per_gas": "1000000"
                            },
                            {
                              "type": "evm_eip1559_tx",
                              "role": "swap",
                              "from": "0x1111111111111111111111111111111111111111",
                              "tx_hex": "0x02f9024c822105",
                              "tx_base64": "AvkCTIIhBQ",
                              "approval_spender": "0x111111125421cA6dc452d289314280a0f8842A65",
                              "chain_id": 8453,
                              "nonce": 42,
                              "gas": "310000",
                              "max_fee_per_gas": "12000000",
                              "max_priority_fee_per_gas": "1000000"
                            }
                          ]
                        }
                      ],
                      "warnings": []
                    }
                  },
                  "speed_user_operation": {
                    "summary": "`priority:\"speed\"` + `execution:\"user_operation\"` on base: one `evm_calls` payload",
                    "description": "`calls[].data` is truncated here. Pack the calls, in order, into ONE ERC-4337 v0.7 UserOperation from `sender` (`execute` for one call, `executeBatch` for two), sponsor it with your paymaster, sign, and return it as `evm_user_operation`. The leg is `gasless:true` with `estimated_gas_usd:\"0\"` because the paymaster pays.",
                    "value": {
                      "quote_id": "7Kp3mQxT9vLw2nRb5cYd8FhJ",
                      "side": "buy",
                      "ticker": "AAPL",
                      "expires_at": 1789056042,
                      "tradfi_reference": {
                        "price_usd": "227.63",
                        "market_status": "open",
                        "as_of": 1789055995
                      },
                      "quotes": [
                        {
                          "quote_index": 0,
                          "chain": "base",
                          "protocol": "coinbase",
                          "price_usdc_per_share": "228.11",
                          "estimated_output_shares": "0.438385",
                          "estimated_output_tokens": "0.438385",
                          "base_asset": "usdc",
                          "amount_base": "100",
                          "cost_breakdown_bps": {
                            "treasures_fee_bps": 10,
                            "dex_swap_fee_bps": 5,
                            "estimated_slippage_bps": 0,
                            "price_impact_bps": 0,
                            "slippage_vs_tradfi_bps": 21
                          },
                          "gasless": true,
                          "estimated_gas_usd": "0",
                          "signable_payloads": [
                            {
                              "type": "evm_calls",
                              "chain_id": 8453,
                              "sender": "0x1111111111111111111111111111111111111111",
                              "entry_point": "0x0000000071727De22E5E9d8BAf0edAc6f37da032",
                              "approval_spender": "0x111111125421cA6dc452d289314280a0f8842A65",
                              "calls": [
                                {
                                  "role": "approve",
                                  "to": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
                                  "data": "0x095ea7b3000000000000000000000000111111125421ca6dc452d289314280a0f8842a65ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff",
                                  "value": "0"
                                },
                                {
                                  "role": "swap",
                                  "to": "0x111111125421cA6dc452d289314280a0f8842A65",
                                  "data": "0x07ed2379",
                                  "value": "0"
                                }
                              ]
                            }
                          ]
                        }
                      ],
                      "warnings": []
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request body, slippage out of range, unknown ticker, zero amount, or (pinned `execution: \"user_operation\"`) a wallet not delegated to Modular Account v2.",
            "content": {
              "application/json": {
                "schema": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/InvalidRequestError"
                    },
                    {
                      "$ref": "#/components/schemas/InvalidSlippageError"
                    },
                    {
                      "$ref": "#/components/schemas/WalletNotDelegatedError"
                    },
                    {
                      "$ref": "#/components/schemas/IntegratorFeeError"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Ownership-proof failure.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OwnershipProofError"
                }
              }
            }
          },
          "403": {
            "$ref": "#/components/responses/AddressBlocked"
          },
          "410": {
            "description": "Quote stale (upstream price moved past expiry mid-build).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SimpleError"
                },
                "example": {
                  "error": "quote_stale"
                }
              }
            }
          },
          "422": {
            "description": "No fillable routes returned by the planner, or a basket listing whose\nissuer-published price is unusable.\n",
            "content": {
              "application/json": {
                "schema": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/NoRoutesError"
                    },
                    {
                      "$ref": "#/components/schemas/BasketPriceUnavailableError"
                    }
                  ]
                },
                "examples": {
                  "no_routes": {
                    "value": {
                      "error": "no_routes"
                    }
                  },
                  "basket_price_unavailable": {
                    "value": {
                      "error": "basket_price_unavailable"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "502": {
            "$ref": "#/components/responses/ProviderUnavailable"
          },
          "503": {
            "$ref": "#/components/responses/QuoteServiceUnavailable"
          }
        }
      }
    },
    "/quote/preview": {
      "post": {
        "operationId": "quotePreview",
        "tags": [
          "Quote"
        ],
        "summary": "Wallet-less price preview (integrator key required)",
        "security": [
          {
            "IntegratorApiKey": []
          }
        ],
        "description": "The `quote_only` shape with **no wallet and no ownership proof**: prices every chain the\nticker lists (or those your `chain` / `protocol` filters allow) and returns the same legs\n`POST /quote/buy` would, minus `quote_id`,\n`expires_at`, every leg's `signable_payloads`, and `warnings_ack_token`. Nothing is\npersisted, so there is no `/quote/{quote_id}/status` to poll and nothing to submit;\nre-quote through `/quote/buy` for anything you intend to sign.\n\n**A key is required here**, unlike every other quote route: this is the one quote that\nbinds no wallet at all. Send your general `tik_` key; a read-only `trk_` reporting key is\nrefused `403 insufficient_scope` like everywhere else off the reporting routes.\n\nIdentical requests inside a 10-second window are answered from one venue fan-out; a\nrefusal is never cached. Budgets are per-IP and per-organisation as elsewhere, **plus a\nglobal ceiling shared by every caller of this route**, so a 429 here can be someone\nelse's traffic. Honour `Retry-After` rather than retrying immediately.\n\n**Read `X-RateLimit-*` on this route as the shared bucket, not as yours.** The headers\nreport the **last** limiter applied, which here is that global ceiling, so\n`X-RateLimit-Remaining: 0` says the route is saturated across all callers, not that\n*you* are out of budget. Back off for `Retry-After` seconds and retry; do not stand down\nfor a whole minute on the assumption you exhausted a per-caller window.\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/QuotePreviewRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Non-executable price preview.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/QuoteBuyResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request body, slippage out of range, unknown ticker, zero amount, or an `amount_usdc` above the 1000000 preview cap.",
            "content": {
              "application/json": {
                "schema": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/InvalidRequestError"
                    },
                    {
                      "$ref": "#/components/schemas/InvalidSlippageError"
                    },
                    {
                      "$ref": "#/components/schemas/IntegratorFeeError"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "No integrator key presented, or an unknown one.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SimpleError"
                },
                "example": {
                  "error": "invalid_api_key"
                }
              }
            }
          },
          "403": {
            "description": "A read-only `trk_` reporting key was presented (`insufficient_scope`), the key was\nretired (`key_revoked`), or your organisation is suspended (`integrator_suspended`).\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SimpleError"
                },
                "example": {
                  "error": "insufficient_scope"
                }
              }
            }
          },
          "422": {
            "description": "No fillable routes returned by the planner, or a basket listing whose\nissuer-published price is unusable.\n",
            "content": {
              "application/json": {
                "schema": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/NoRoutesError"
                    },
                    {
                      "$ref": "#/components/schemas/BasketPriceUnavailableError"
                    }
                  ]
                },
                "examples": {
                  "no_routes": {
                    "value": {
                      "error": "no_routes"
                    }
                  },
                  "basket_price_unavailable": {
                    "value": {
                      "error": "basket_price_unavailable"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "502": {
            "$ref": "#/components/responses/ProviderUnavailable"
          },
          "503": {
            "description": "Your configured fee schedule no longer fits a venue Treasures routes through\n(`integrator_fee_misconfigured`). A Treasures-side configuration issue that retrying soon\nwon't clear; contact Treasures, or send `integrator_fee_bps: 0` to preview without your fee.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SimpleError"
                },
                "example": {
                  "error": "integrator_fee_misconfigured"
                }
              }
            }
          }
        }
      }
    },
    "/quote/sell": {
      "post": {
        "operationId": "quoteSell",
        "tags": [
          "Quote"
        ],
        "summary": "Quote stock holdings → USDC (all legs needed; all-or-nothing submit)",
        "description": "Plans the optimal sequence of swap legs across the user's current holdings.\nEvery returned leg must be signed and submitted together at `/trade/submit`.\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/QuoteSellRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/QuoteSellResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request body, slippage out of range, unknown ticker, zero amount, a `payout_chain` the request cannot reach (its wallet missing, or nothing in scope can pay out there; see `payout_chain`), or (pinned `execution: \"user_operation\"`) a wallet not delegated to Modular Account v2.",
            "content": {
              "application/json": {
                "schema": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/InvalidRequestError"
                    },
                    {
                      "$ref": "#/components/schemas/InvalidSlippageError"
                    },
                    {
                      "$ref": "#/components/schemas/WalletNotDelegatedError"
                    },
                    {
                      "$ref": "#/components/schemas/IntegratorFeeError"
                    }
                  ]
                },
                "examples": {
                  "payout_wallet_missing": {
                    "value": {
                      "error": "invalid_request",
                      "message": "payout_chain: payout_chain \"sol\" requires sol_wallet"
                    }
                  },
                  "payout_unreachable": {
                    "value": {
                      "error": "invalid_request",
                      "message": "payout_chain: no requested chain and protocol can pay out on \"base\""
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Ownership-proof failure.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OwnershipProofError"
                }
              }
            }
          },
          "403": {
            "$ref": "#/components/responses/AddressBlocked"
          },
          "410": {
            "description": "Quote stale (upstream price moved past expiry mid-build).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SimpleError"
                },
                "example": {
                  "error": "quote_stale"
                }
              }
            }
          },
          "422": {
            "description": "No fillable routes returned by the planner, or insufficient holdings\nfor the requested share amount. With `payout_chain`, holdings that\ncover the amount but cannot pay out there are `no_routes` with\n`reason: payout_route_unavailable`, never `holdings_insufficient`.\nA sell refused for its size may carry `min_notional_usdc`, in USDC\nof the shares it could not place (see `NoRoutesError`).\n",
            "content": {
              "application/json": {
                "schema": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/NoRoutesError"
                    },
                    {
                      "$ref": "#/components/schemas/SimpleError"
                    }
                  ]
                },
                "examples": {
                  "no_routes": {
                    "value": {
                      "error": "no_routes"
                    }
                  },
                  "below_minimum": {
                    "value": {
                      "error": "no_routes",
                      "reason": "no_market_maker_fill",
                      "min_notional_usdc": "11.00"
                    }
                  },
                  "payout_route_unavailable": {
                    "value": {
                      "error": "no_routes",
                      "reason": "payout_route_unavailable"
                    }
                  },
                  "holdings_insufficient": {
                    "value": {
                      "error": "holdings_insufficient"
                    }
                  },
                  "holdings_unknown": {
                    "value": {
                      "error": "holdings_unknown"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "502": {
            "$ref": "#/components/responses/ProviderUnavailable"
          },
          "503": {
            "$ref": "#/components/responses/QuoteServiceUnavailable"
          }
        }
      }
    },
    "/quote/{quote_id}/status": {
      "get": {
        "operationId": "getQuoteStatus",
        "tags": [
          "Quote"
        ],
        "summary": "Aggregate + per-leg status for a previously issued quote",
        "description": "Public read-only; no `ownership_proof`. Ethereum in-flight rows are\nlazy-flipped against the upstream venue on read; Solana `broadcast_unknown` rows stay\nin-flight until operator action. In-progress aggregates are cached per venue class: 1 s while\na speed-route leg submitted in the last 5 min is still in flight, 3 s otherwise;\n`poll_after_ms` sits just above that window and is `null` once the aggregate is terminal\n(stop polling).\n",
        "parameters": [
          {
            "name": "quote_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/QuoteStatusResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "404": {
            "description": "Unknown `quote_id` (expired cache, never issued, or no rows persisted).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SimpleError"
                },
                "example": {
                  "error": "quote_not_found"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/trade/submit": {
      "post": {
        "operationId": "submitTrade",
        "tags": [
          "Trade"
        ],
        "summary": "Submit signed quote legs atomically",
        "description": "Idempotent on `(quote_id, quote_index)`. The per-leg signed payload IS the\nauthorization proof; no `ownership_proof` is required here. Re-quote (`410\nquote_stale`) if the cached snapshot expired between issue and submit.\n\nA quote that carries your integrator fee (`integrator_fee_bps > 0` on any leg) can\nonly be submitted with the same `X-API-Key` that quoted it; anything else is `403\nquote_integrator_mismatch` and nothing is broadcast. Zero-fee quotes are unaffected.\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TradeSubmitRequest"
              },
              "examples": {
                "speed_signed_pair": {
                  "summary": "Speed-route leg (`execution:\"transaction\"`): both transactions signed whole",
                  "description": "One `evm_signed_tx` per `SignableEvmTx` payload the quote issued, in the order issued (`approve` at nonce n, `swap` at n+1). Sign each `tx_hex` unchanged (never re-nonce, re-estimate or re-serialize) and do not broadcast; Treasures does. `signed_tx_hex` is truncated here.",
                  "value": {
                    "quote_id": "7Kp3mQxT9vLw2nRb5cYd8FhJ",
                    "signed": [
                      {
                        "quote_index": 0,
                        "signed_payloads": [
                          {
                            "type": "evm_signed_tx",
                            "signed_tx_hex": "0x02f8f5822105"
                          },
                          {
                            "type": "evm_signed_tx",
                            "signed_tx_hex": "0x02f9028f822105"
                          }
                        ]
                      }
                    ]
                  }
                },
                "user_operation": {
                  "summary": "Speed-route leg (`execution:\"user_operation\"`): one sponsored, signed UserOperation",
                  "description": "The v0.7 UserOperation you built from the quote's `evm_calls` payload, sponsored by your paymaster and signed by the delegated wallet. Do not send it to a bundler yourself; Treasures simulates, submits and returns `user_op_hash`. `callData`, `paymasterData` and `signature` are truncated here. Numerics may be decimal or 0x-hex strings.",
                  "value": {
                    "quote_id": "7Kp3mQxT9vLw2nRb5cYd8FhJ",
                    "signed": [
                      {
                        "quote_index": 0,
                        "signed_payloads": [
                          {
                            "type": "evm_user_operation",
                            "user_operation": {
                              "sender": "0x1111111111111111111111111111111111111111",
                              "nonce": "0x1a",
                              "callData": "0x34fcd5be",
                              "callGasLimit": "0x5b8d8",
                              "verificationGasLimit": "0x1d4c0",
                              "preVerificationGas": "0x11170",
                              "maxFeePerGas": "0xb71b00",
                              "maxPriorityFeePerGas": "0xf4240",
                              "paymaster": "0x2cc0c7981D846b9F2a16276556f6e8cb52BfB633",
                              "paymasterVerificationGasLimit": "0x186a0",
                              "paymasterPostOpGasLimit": "0xc350",
                              "paymasterData": "0x000000000000",
                              "signature": "0xff0000"
                            }
                          }
                        ]
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Partial-broadcast tolerated: legs that landed appear under `results`,\nlegs that hit an invariant break appear under `failed_legs` with a\ngeneric `internal_error` code so the agent can reconcile on-chain.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TradeSubmitResponse"
                },
                "examples": {
                  "speed_broadcast": {
                    "summary": "Speed-route leg accepted; `tx_hash` is the swap's from the start",
                    "description": "On a pair the swap hash is known immediately (it is `keccak256` of the signed swap) but appears on chain only after the bundled `approve` mines. Poll `/quote/{quote_id}/status` until `completed`.",
                    "value": {
                      "results": [
                        {
                          "quote_index": 0,
                          "trade_id": "trd_9vLw2nRb5cYd8FhJ7Kp3mQxT",
                          "status": "broadcast",
                          "tx_hash": "0x6d1c9d3b1f9a1c1c0f7e2d4a5b6c7d8e9f0a1b2c3d4e5f60718293a4b5c6d7e8",
                          "order_hash": null,
                          "user_op_hash": null,
                          "error_code": null
                        }
                      ],
                      "failed_legs": []
                    }
                  },
                  "user_operation_broadcast": {
                    "summary": "UserOperation accepted by the bundler; `user_op_hash` set, `tx_hash` still null",
                    "description": "`tx_hash` becomes the bundle transaction once mined; poll `/quote/{quote_id}/status`. A paymaster refusal would instead be `status: broadcast_failed` with `error_code: sponsorship_rejected`.",
                    "value": {
                      "results": [
                        {
                          "quote_index": 0,
                          "trade_id": "trd_9vLw2nRb5cYd8FhJ7Kp3mQxT",
                          "status": "broadcast",
                          "tx_hash": null,
                          "order_hash": null,
                          "user_op_hash": "0x2b7e151628aed2a6abf7158809cf4f3c762e7160f38b4da56a784d9045190cfe",
                          "error_code": null
                        }
                      ],
                      "failed_legs": []
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Malformed body, incomplete submit, or `quote_index` not in snapshot.",
            "content": {
              "application/json": {
                "schema": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/InvalidRequestError"
                    },
                    {
                      "$ref": "#/components/schemas/SimpleErrorWithMessage"
                    }
                  ]
                },
                "examples": {
                  "incomplete_submit": {
                    "value": {
                      "error": "incomplete_submit",
                      "message": "missing leg(s) for quote_id ..."
                    }
                  },
                  "quote_index_mismatch": {
                    "value": {
                      "error": "quote_index_mismatch",
                      "message": "unknown quote_index ..."
                    }
                  }
                }
              }
            }
          },
          "403": {
            "$ref": "#/components/responses/AddressBlocked"
          },
          "404": {
            "description": "Unknown or expired `quote_id`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SimpleError"
                },
                "example": {
                  "error": "quote_not_found"
                }
              }
            }
          },
          "409": {
            "description": "A leg under `(quote_id, quote_index)` was already submitted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LegAlreadySubmittedError"
                }
              }
            }
          },
          "410": {
            "description": "Snapshot expired between issue and submit; re-quote.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SimpleError"
                },
                "example": {
                  "error": "quote_stale"
                }
              }
            }
          },
          "422": {
            "description": "You sent `acknowledged_warnings` and it does not match the warnings served with this\n`quote_id`. Only reachable when the field is present; omitting it always proceeds.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SimpleErrorWithMessage"
                },
                "example": {
                  "error": "warnings_not_acknowledged",
                  "message": "echo warnings_ack_token from the quote as acknowledged_warnings to proceed"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/ScreeningUnavailable"
          }
        }
      }
    },
    "/trade/submit/batch": {
      "post": {
        "operationId": "submitTradeBatch",
        "tags": [
          "Trade"
        ],
        "summary": "Submit up to 25 signed quotes in one request",
        "security": [
          {
            "IntegratorApiKey": []
          }
        ],
        "description": "Runs each submission exactly as `POST /trade/submit` would and answers every one, in\nrequest order. `http_status` is the status that submit would have answered and `response`\nits body; headers (`Retry-After`, the rate-limit counts) belong to the batch response\nonly. One submission's outcome never affects another's, so the batch's `200` says nothing\nabout any item: read each `http_status`.\n\nRequires your general (`tik_`) key; a reporting key is refused.\n\nRefused as a whole, with nothing read or broadcast:\n\n- The same `quote_id` in more than one submission: `400 invalid_request`. A buy's legs\n  are alternatives, so splitting one quote across submissions would buy twice. Send each\n  quote once, with all of the legs you sign for it in one submission.\n- No submissions, more than 25, an unknown field, or any submission `POST /trade/submit`\n  would refuse as malformed: `400 invalid_request`.\n- A body over 100 KB (100,000 bytes): `413 { error: \"Payload too large\" }`, answered before\n  the request reaches this operation. The limit of 25 assumes about one signed Solana leg\n  per submission; submissions that sign several legs (a sell quoted with several legs)\n  leave room for fewer, so size such batches smaller.\n- The rate limit: `429`. Every submission counts once against a per-organisation budget\n  (600 a minute) and a per-IP budget (300 a minute), on top of the per-request limits of\n  every trade route. The batch is charged before any submission runs, and a batch refused\n  with `429` still counts in full against the per-organisation budget, and against the\n  per-IP budget too when that is the one that refused. A batch refused with `400` costs\n  nothing against these two budgets.\n\n  Size each batch to the budget you have left, and after a `429` wait for `Retry-After`.\n  On a `200` the `X-RateLimit-*` headers describe the last of the two budgets charged (the\n  per-IP one in production), counted in submissions.\n\nPer submission, beside every answer `POST /trade/submit` can give:\n\n- `422 batch_leg_unsupported` with that `quote_index`: a batch carries same-chain Solana\n  legs only (`chain: sol`, quoted without `origin_chain` or `payout_chain`). Submit any\n  other leg through `POST /trade/submit`. Nothing was sent. This check runs before the\n  checks `POST /trade/submit` makes, so such a submission answers `422` even when it is\n  also stale, bound to another organisation's fee or refused by screening; submitting it\n  alone gives those answers.\n- `503 batch_deadline_exceeded`: the batch ran long enough that this submission was not\n  started, so nothing was sent and the batch could answer in time. Submit it again, alone\n  or in a new batch, while its quote is live.\n- `500 internal_error`: the submission failed unexpectedly. It may have been sent before\n  it failed, so read `GET /quote/{quote_id}/status` before re-quoting. The single route's\n  500 body reads `Internal server error`; inside a batch it is `internal_error`.\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TradeSubmitBatchRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "One result per submission, in request order.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TradeSubmitBatchResponse"
                },
                "example": {
                  "results": [
                    {
                      "quote_id": "7Kp3mQxT9vLw2nRb5cYd8FhJ",
                      "http_status": 200,
                      "response": {
                        "results": [
                          {
                            "quote_index": 0,
                            "trade_id": "trd_9vLw2nRb5cYd8FhJ7Kp3mQxT",
                            "status": "completed",
                            "tx_hash": "5VERv8NMvzbJMEkV8xnrLkEaWRtSz9CosKDYjCJjBRnbJLgp8uirBgmQpjKhoR4tjF3ZpRzrFmBV6UjKdiSZkQUW",
                            "order_hash": null,
                            "user_op_hash": null,
                            "error_code": null
                          }
                        ],
                        "failed_legs": []
                      }
                    },
                    {
                      "quote_id": "3nRb5cYd8FhJ7Kp3mQxT9vLw",
                      "http_status": 410,
                      "response": {
                        "error": "quote_stale"
                      }
                    },
                    {
                      "quote_id": "9vLw2nRb5cYd8FhJ7Kp3mQxT",
                      "http_status": 422,
                      "response": {
                        "error": "batch_leg_unsupported",
                        "quote_index": 0
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "401": {
            "description": "Missing, malformed or unknown `X-API-Key`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SimpleError"
                }
              }
            }
          },
          "403": {
            "description": "`insufficient_scope`, `key_revoked` or `integrator_suspended`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SimpleError"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/bridge/quote": {
      "post": {
        "operationId": "quoteBridge",
        "tags": [
          "Bridge"
        ],
        "summary": "Quote a cross-chain USDC bridge",
        "description": "Returns a Treasures-issued `bridge_quote_id` plus a signable payload.\n\n- By default (`delivery: self_broadcast`) you sign it and broadcast it yourself.\n- With `delivery: submit` you sign it and hand it to `POST /bridge/{bridge_quote_id}/submit`\n  instead; it can be executed no other way.\n\nFrom an EVM origin that payload is typed data (`evm_permit_typed_data`): no transaction, no\nnonce and no native gas on the origin.\n\nAny two distinct chains in `BridgeChain` (with `delivery: submit`, the origin must be\n`sol`, `eth`, `base` or `arbitrum` for now). `eth_wallet` and its proof are always\nrequired; `sol_wallet` and its proof only when either side is `sol`.\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BridgeQuoteRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BridgeQuoteResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request, same-chain bridge, unsupported route, or slippage out of range.\n",
            "content": {
              "application/json": {
                "schema": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/InvalidRequestError"
                    },
                    {
                      "$ref": "#/components/schemas/InvalidSlippageError"
                    },
                    {
                      "$ref": "#/components/schemas/SimpleError"
                    }
                  ]
                },
                "examples": {
                  "same_chain_bridge": {
                    "value": {
                      "error": "same_chain_bridge"
                    }
                  },
                  "unsupported_route": {
                    "value": {
                      "error": "unsupported_route"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Ownership-proof failure.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OwnershipProofError"
                }
              }
            }
          },
          "403": {
            "$ref": "#/components/responses/AddressBlocked"
          },
          "422": {
            "description": "Upstream reported insufficient liquidity for the route.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SimpleError"
                },
                "example": {
                  "error": "insufficient_liquidity"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "502": {
            "$ref": "#/components/responses/ProviderUnavailable"
          },
          "503": {
            "$ref": "#/components/responses/ScreeningUnavailable"
          }
        }
      }
    },
    "/bridge/{bridge_quote_id}/status": {
      "get": {
        "operationId": "getBridgeStatus",
        "tags": [
          "Bridge"
        ],
        "summary": "Status of a previously issued bridge quote",
        "description": "Required because the agent has no other way to discover the destination\ntx hash; the upstream bridge's source tx hash alone cannot be used to\nlook up fill status.\n",
        "parameters": [
          {
            "name": "bridge_quote_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^brq_[A-Za-z0-9_-]{21}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BridgeStatusResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "404": {
            "description": "Unknown `bridge_quote_id`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SimpleError"
                },
                "example": {
                  "error": "bridge_quote_not_found"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "502": {
            "$ref": "#/components/responses/ProviderUnavailable"
          }
        }
      }
    },
    "/bridge/{bridge_quote_id}/submit": {
      "post": {
        "operationId": "submitBridge",
        "tags": [
          "Bridge"
        ],
        "summary": "Submit a signed bridge for execution",
        "description": "For a `delivery: submit` quote only (a `self_broadcast` quote answers\n`400 quote_not_submittable`). Treasures checks the signatures recover to your wallet over\nexactly the payload `/bridge/quote` issued, then runs it: an EVM origin's typed data is\nexecuted by the upstream bridge (its gas taken from the amount); a Solana origin's signed\ntransaction is broadcast by Treasures.\n\nOne submission per quote: the same body may be resubmitted (idempotent) for up to an hour.\nAfter a `502` it may have gone through, so resubmit the SAME body, never a new one; a\nresubmission that still cannot tell answers `502` again, so poll status rather than\nre-quote. Track the fill with `GET /bridge/{bridge_quote_id}/status`.\n",
        "parameters": [
          {
            "name": "bridge_quote_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^brq_[A-Za-z0-9_-]{21}$"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BridgeSubmitRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Broadcast.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BridgeSubmitResponse"
                }
              }
            }
          },
          "400": {
            "description": "Malformed body; signatures or a signed transaction that do not match the quote\n(`signed_tx_mismatch`, `field` names the part); or a `self_broadcast` quote\n(`quote_not_submittable`).\n",
            "content": {
              "application/json": {
                "schema": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/InvalidRequestError"
                    },
                    {
                      "type": "object",
                      "required": [
                        "error",
                        "field"
                      ],
                      "properties": {
                        "error": {
                          "type": "string",
                          "enum": [
                            "signed_tx_mismatch"
                          ]
                        },
                        "field": {
                          "type": "string"
                        }
                      }
                    },
                    {
                      "$ref": "#/components/schemas/SimpleError"
                    }
                  ]
                },
                "examples": {
                  "signed_tx_mismatch": {
                    "value": {
                      "error": "signed_tx_mismatch",
                      "field": "signatures[0]"
                    }
                  },
                  "quote_not_submittable": {
                    "value": {
                      "error": "quote_not_submittable"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "$ref": "#/components/responses/AddressBlocked"
          },
          "404": {
            "description": "Unknown `bridge_quote_id`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SimpleError"
                },
                "example": {
                  "error": "bridge_quote_not_found"
                }
              }
            }
          },
          "409": {
            "description": "`bridge_already_submitted`: this quote already holds a submission, or its retry\nwindow has passed. Poll status; never sign a second deposit.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SimpleError"
                },
                "example": {
                  "error": "bridge_already_submitted"
                }
              }
            }
          },
          "410": {
            "description": "The quote expired (or its Solana blockhash did), or the bridge refused an EVM permit that can no longer run. Re-quote.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SimpleError"
                },
                "example": {
                  "error": "bridge_quote_expired"
                }
              }
            }
          },
          "422": {
            "description": "Refused before anything moved (for example, too little balance). Fix it, then re-quote. Solana origins only; a refused EVM permit answers 410.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SimpleError"
                },
                "example": {
                  "error": "broadcast_rejected"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "502": {
            "description": "The outcome is unknown. Resubmit the same body.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "source_tx_hash"
                  ],
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "broadcast_unavailable"
                      ]
                    },
                    "source_tx_hash": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The Solana signature; null from an EVM origin."
                    }
                  }
                }
              }
            }
          },
          "503": {
            "$ref": "#/components/responses/ScreeningUnavailable"
          }
        }
      }
    },
    "/portfolio": {
      "get": {
        "operationId": "getPortfolio",
        "tags": [
          "Portfolio"
        ],
        "summary": "Reconciled holdings + USDC / USDG balances for the given wallets",
        "description": "At least one of `sol_wallet` / `eth_wallet` is required.",
        "parameters": [
          {
            "$ref": "#/components/parameters/SolWalletQuery"
          },
          {
            "$ref": "#/components/parameters/EvmWalletQuery"
          },
          {
            "$ref": "#/components/parameters/SourceQuery"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PortfolioResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/PortfolioBusy"
          }
        }
      }
    },
    "/trades": {
      "get": {
        "operationId": "listTrades",
        "tags": [
          "Trades"
        ],
        "summary": "Swap-only trade history for the given wallets",
        "description": "Returns trades plus a `next_offset` cursor when more pages exist.\nSynthesizes external rows on detected drift (source = `external`).\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/SolWalletQuery"
          },
          {
            "$ref": "#/components/parameters/EvmWalletQuery"
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 5000,
              "default": 0
            }
          },
          {
            "$ref": "#/components/parameters/SourceQuery"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TradesResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/settlements": {
      "get": {
        "operationId": "listSettlements",
        "tags": [
          "Settlements"
        ],
        "summary": "Your organisation's settled trades, paginated",
        "security": [
          {
            "IntegratorApiKey": []
          }
        ],
        "description": "Every trade submitted through `POST /trade/submit` **with your API key\npresented**, newest first. This is the one route a read-only `trk_` reporting\nkey may call; your `tik_` key works here too and returns the same rows.\n\n**Settled fills only.** A trade appears once it reaches `completed`; on\nEthereum and Robinhood Chain that is when the resolver fills the order, which\ncan be minutes after you submitted it. Until then the amounts on record are\nquote-time expectations, not what happened, so they are withheld rather than\nreported as fact. Poll `GET /quote/{quote_id}/status` for in-flight legs.\n\n**Attribution requires the header.** A submit sent without `X-API-Key` is not\nattributed to anyone and will never appear here; there is no way to recover\nit afterwards. Trades predating this endpoint are likewise absent.\n\nOrdering and pagination key on settlement time. Pass the previous response's\n`next_cursor` back as `cursor` to page; `has_more` tells you whether another\npage exists. `data` may be shorter than `limit` while `has_more` is `true`.\n\n**Re-scan a trailing window if you reconcile exactly.** A small number of Solana\ntrades are settled by a recovery job that records the on-chain block time, which\nis earlier than when the record appeared, typically by minutes. Such a row lands\n*behind* a cursor you have already paged past. If your totals must be exact,\nre-scan roughly the last 2 hours on each pass rather than relying on the cursor\nalone; `trade_id` is stable, so re-scanned rows deduplicate cleanly.\n\nNote that 2 hours is a normal-operations figure, not a guaranteed bound: if that\nrecovery job is itself delayed, a row can be backdated by as long as the delay.\nTreat a periodic wider re-scan as the backstop for balances that must tie out\nexactly.\n\nEach entry carries a LI.FI-style `sending` / `receiving` leg pair, each with its\nown transaction hash, chain and explorer link. On a single-chain swap both legs\nshare one transaction hash, chain and timestamp; only the token and amount\ndiffer.\n\nA sell quoted with `payout_chain` is the exception: the stock leg (`sending`) is\nthe sale on the entry's `chain`, and the USDC leg (`receiving`) is the payout, its\nown transaction on the chain the USDC landed on. That is `payout_chain`, or the\nsale's own `chain` when the USDC was returned there instead, in which case the\nentry is one chain with two transactions. Both legs carry the settlement time.\n\nThe top-level `token_out_address` and `amount` mirror the `receiving` leg; the\ntop-level `chain` and `tx_hash` are the trade's own, the same `tx_hash`\n`GET /trades` reports, so on a cross-chain sell `tx_hash` is the sale\n(`sending.tx_hash`) while `receiving.tx_hash` is the payout.\n\n**Every amount is truncated, never rounded up.** Amounts, prices and fees are\nreported at or below their true value, never above it, so a figure here is\nalways safe to reconcile, re-spend, or pay out against without a buffer. Treat\nthe last decimal place as a floor rather than a rounded value.\n\n**Filtering.** All filter parameters are optional and combine with AND; omitting\none means \"any\". `chain`, `protocol` and `ticker` accept a comma-separated list\nwhich is an OR *within* that parameter; `?chain=sol,eth&ticker=AAPL` means AAPL\non Solana or Ethereum. Repeating a parameter is **not** additive:\n`?chain=sol&chain=eth` is read as `sol` alone, so use the comma form. A filter\nthat matches nothing returns an empty `data` with `200`, never an error.\n\n**Casing follows the response.** Every filter value is matched in the casing this\nendpoint reports it in: `chain`, `protocol` and `side` are lowercase and are\nmatched exactly (`?side=BUY` is rejected), while `ticker` is reported uppercase\nand is the one filter accepted in any case. EVM `token_out_address` values are\ncase-insensitive; Solana addresses are base58 and case-sensitive.\n\n**A cursor is bound to the filters that produced it.** Paging is a keyset over one\nresult set, so changing any filter mid-chain invalidates the cursor and returns\n`400 cursor: filters_changed`; start that new query from the first page. Changing\n`limit` is fine and does not invalidate the cursor.\n",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "Opaque cursor from a prior response's `next_cursor`. Treat it as a blob, its encoding is not part of this contract and may change.",
            "schema": {
              "type": "string",
              "maxLength": 256
            }
          },
          {
            "name": "chain",
            "in": "query",
            "style": "form",
            "explode": false,
            "description": "Chains to include; omit for all. Values are lowercase, matched exactly. Matches each entry's `chain`, the chain of the stock traded: a sell paid out on another chain matches its stock's chain, not the payout's. To select sells by where their USDC landed, filter `token_out_address` on that chain's USDC.",
            "schema": {
              "type": "array",
              "maxItems": 6,
              "items": {
                "type": "string",
                "enum": [
                  "sol",
                  "eth",
                  "robinhood",
                  "base",
                  "arbitrum",
                  "bnb"
                ]
              }
            },
            "example": [
              "sol",
              "eth"
            ]
          },
          {
            "name": "protocol",
            "in": "query",
            "style": "form",
            "explode": false,
            "description": "Protocols to include; omit for all. Values are lowercase, matched exactly.",
            "schema": {
              "type": "array",
              "maxItems": 7,
              "items": {
                "type": "string",
                "enum": [
                  "ondo",
                  "xstocks",
                  "robinhood",
                  "coinbase",
                  "reality",
                  "backpack",
                  "bstocks"
                ]
              }
            },
            "example": [
              "ondo",
              "xstocks"
            ]
          },
          {
            "name": "ticker",
            "in": "query",
            "style": "form",
            "explode": false,
            "description": "Tickers to include, case-insensitive. Matches the response's `ticker` field, not the venue-suffixed token symbol.",
            "schema": {
              "type": "array",
              "maxItems": 50,
              "items": {
                "type": "string",
                "maxLength": 10
              }
            },
            "example": [
              "AAPL",
              "MSFT"
            ]
          },
          {
            "name": "side",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "buy",
                "sell"
              ]
            }
          },
          {
            "name": "token_out_address",
            "in": "query",
            "description": "The contract address of the token **received**, matching the response's `token_out_address`. Because that field is side-dependent, so is this filter: a stock token address returns *buys* of that token, while a base-currency address (USDC, or USDG on Robinhood Chain) returns *sells* whose proceeds were received on that chain, including sells paid out there from a stock on another chain. An address we do not carry returns an empty page rather than an error.",
            "schema": {
              "type": "string",
              "example": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
            }
          },
          {
            "name": "settled_from",
            "in": "query",
            "description": "Earliest settlement time, inclusive, as a Unix timestamp in seconds. Compares against the same `timestamp` each entry reports.",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 253402300798
            }
          },
          {
            "name": "settled_to",
            "in": "query",
            "description": "Latest settlement time, **inclusive of the whole second**: an entry reporting `timestamp` equal to this value is always included. Must be greater than or equal to `settled_from`.",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 253402300798
            }
          },
          {
            "name": "payout_id",
            "in": "query",
            "description": "Only the trades whose integrator fee went out in this payout, the entries a payout's `amount_usd` is summed from. Another organisation's payout id matches nothing.",
            "schema": {
              "type": "string",
              "pattern": "^ipo_[A-Za-z0-9_-]{1,64}$"
            }
          },
          {
            "name": "payout_status",
            "in": "query",
            "description": "Where each trade's integrator fee stands. `unpaid`: no payout has claimed it yet; these entries sum exactly to `GET /payouts/accrued`. `processing` / `paid`: the status of the payout that claimed it. Only trades that carried an integrator fee match any value.",
            "schema": {
              "type": "string",
              "enum": [
                "unpaid",
                "processing",
                "paid"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SettlementsResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid query. `cursor: malformed` means the cursor did not decode; restart from the first page rather than retrying it. `cursor: filters_changed` means the cursor came from a different set of filters; restart that query from the first page. `settled_from: must be <= settled_to` means the time range is inverted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InvalidRequestError"
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed or unknown `X-API-Key`. These are deliberately indistinguishable; the API never reveals whether a key exists.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SimpleError"
                },
                "example": {
                  "error": "invalid_api_key"
                }
              }
            }
          },
          "403": {
            "description": "A key you genuinely hold, but which may not be used here. `key_revoked`: the key was retired. `integrator_suspended`: your organisation is suspended, so every one of your keys is affected.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SimpleError"
                },
                "example": {
                  "error": "key_revoked"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/payouts/accrued": {
      "get": {
        "operationId": "getAccruedIntegratorFees",
        "tags": [
          "Payouts"
        ],
        "summary": "What you are owed right now, and where it will be paid",
        "security": [
          {
            "IntegratorApiKey": []
          }
        ],
        "description": "The sum of the `integrator_fee` entries on your settled trades that no payout has\nclaimed yet: exactly the entries `GET /settlements?payout_status=unpaid` lists, with\nthe same truncation. Fees earned on every chain are pooled into one USD figure\n(USDC and USDG count 1:1).\n\n`payout_address` / `payout_chain` are where payouts go. Only Treasures can set or\nchange them; ask your contact. `previous_payout_address` and\n`payout_address_updated_at` show the last change, so an unexpected one is visible\nto you.\n\nRequires your general (`tik_`) key; a reporting key is refused.\n",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AccruedIntegratorFees"
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed or unknown `X-API-Key`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SimpleError"
                },
                "example": {
                  "error": "invalid_api_key"
                }
              }
            }
          },
          "403": {
            "description": "`insufficient_scope`: a reporting key. `key_revoked` / `integrator_suspended` as on every route.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SimpleError"
                },
                "example": {
                  "error": "insufficient_scope"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/payouts": {
      "post": {
        "operationId": "requestPayout",
        "tags": [
          "Payouts"
        ],
        "summary": "Pay out everything you are owed, to your registered address",
        "security": [
          {
            "IntegratorApiKey": []
          }
        ],
        "description": "Sends **all** of your accrued integrator fees (`GET /payouts/accrued`) to your registered\npayout address, from Treasures' payout treasury. You choose nothing: the amount is what you are\nowed, the destination is the address Treasures registered, and the body must be empty (or `{}`).\n\n**`Idempotency-Key` is required.** A key is yours forever: repeating it returns the payout it\nfirst created, whatever its status, including `failed`. To try again after a failure, send a\nnew key. Only one payout can be in progress at a time.\n\nLimits: at least `minimum_usd`, at most `maximum_usd` (larger balances are paid out by\nTreasures on request), one payout per cooldown window, and none for a while after your payout\naddress changes. `GET /payouts/accrued` reports all of them, including `next_eligible_at`.\n\n`202` means the transfer was sent or is being sent. Poll `GET /payouts/{payoutId}` until\n`status` is `paid` (or `failed`, in which case the fees are owed to you again).\n\nRequires your general (`tik_`) key; a reporting key is refused.\n",
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "maxLength": 128,
              "pattern": "^[A-Za-z0-9_-]+$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The original payout, replayed for an `Idempotency-Key` you already used.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Payout"
                }
              }
            }
          },
          "202": {
            "description": "Payout created and sent (or being sent).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Payout"
                }
              }
            }
          },
          "400": {
            "description": "`missing_idempotency_key`, `invalid_idempotency_key`, or a non-empty body.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SimpleError"
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed or unknown `X-API-Key`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SimpleError"
                }
              }
            }
          },
          "403": {
            "description": "`insufficient_scope`, `key_revoked` or `integrator_suspended`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SimpleError"
                }
              }
            }
          },
          "409": {
            "description": "- `payout_in_progress` (with `payout_id`)\n- `payout_cooldown` / `address_hold` (with `retry_after`, Unix seconds, and a\n  `Retry-After` header)\n- `payout_address_missing` (ask Treasures to register one)\n- `nothing_to_pay`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SimpleError"
                }
              }
            }
          },
          "422": {
            "description": "`below_minimum` (with `amount_usd`, `minimum_usd`) or `requires_review` (with `amount_usd`, `maximum_usd`; Treasures pays balances this large on request).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SimpleError"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "description": "`payouts_unavailable`: payouts are paused or cannot be made right now. Retry later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SimpleError"
                }
              }
            }
          }
        }
      },
      "get": {
        "operationId": "listPayouts",
        "tags": [
          "Payouts"
        ],
        "summary": "Your payout history, newest first",
        "security": [
          {
            "IntegratorApiKey": []
          }
        ],
        "description": "Every payout of your integrator fees, newest first. Pass the previous response's\n`next_cursor` back as `cursor` to page. To see the trades a payout covered, call\n`GET /settlements?payout_id=…`.\n\nRequires your general (`tik_`) key; a reporting key is refused.\n",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "Opaque cursor from a prior response's `next_cursor`.",
            "schema": {
              "type": "string",
              "maxLength": 256
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PayoutsResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid query. `cursor: malformed` means restart from the first page.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InvalidRequestError"
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed or unknown `X-API-Key`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SimpleError"
                }
              }
            }
          },
          "403": {
            "description": "`insufficient_scope`, `key_revoked` or `integrator_suspended`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SimpleError"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/payouts/{payoutId}": {
      "get": {
        "operationId": "getPayout",
        "tags": [
          "Payouts"
        ],
        "summary": "One of your payouts",
        "security": [
          {
            "IntegratorApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "payoutId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Payout"
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed or unknown `X-API-Key`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SimpleError"
                }
              }
            }
          },
          "403": {
            "description": "`insufficient_scope`, `key_revoked` or `integrator_suspended`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SimpleError"
                }
              }
            }
          },
          "404": {
            "description": "No such payout of yours. Another organisation's payout id answers the same, so the response never reveals whether an id exists.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SimpleError"
                },
                "example": {
                  "error": "payout_not_found"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/signals/strategies": {
      "get": {
        "operationId": "listSignalStrategies",
        "tags": [
          "Signals"
        ],
        "summary": "The strategies whose target-weight books you may read",
        "security": [
          {
            "IntegratorApiKey": []
          }
        ],
        "description": "One page, newest first; `truncated` says whether the page cap of 100 cut it short (today\nthe catalog is a handful of rows). Only strategies published to integrators appear, so a\nstrategy visible in the Treasures app may be absent here. The catalog lists `active` and\n`paused` strategies only; a `halted` strategy leaves the catalog but stays readable by id\nor slug on the detail and history routes, with its last book.\n\n`replication` is the honesty block for each book: a book is the source portfolio cut down\nto the names Treasures can trade on chain and renormalised, so `names_replicated` of\n`names_total` are in it and `skipped_source_weight` of the source's weight is not.\n\n`strategy_id` is the stable key. `slug` is a convenience that may be renamed; the detail\nand history routes accept either.\n\nEach row carries its latest book's `book_hash`, `book_as_of` and `signal_id` (all `null`\nwhen the strategy has no book yet), the same values `GET /signals/strategies/{id}` serves,\nso one catalog read tells you which books changed since you last looked.\n\nRequires your general (`tik_`) key; a reporting key is refused.\n",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SignalStrategiesResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "401": {
            "description": "Missing, malformed or unknown `X-API-Key`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SimpleError"
                }
              }
            }
          },
          "403": {
            "description": "`insufficient_scope`, `key_revoked` or `integrator_suspended`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SimpleError"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/SignalReadsRateLimited"
          }
        }
      }
    },
    "/signals/strategies/{id}": {
      "get": {
        "operationId": "getSignalStrategy",
        "tags": [
          "Signals"
        ],
        "summary": "One strategy and its current target-weight book",
        "security": [
          {
            "IntegratorApiKey": []
          }
        ],
        "description": "`book` is the newest book the source produced that Treasures has finished acting on, or\n`null` when there is none yet (or the newest one cannot be read; an older book is never\nsubstituted). `as_of` is when Treasures ingested the book, not the date of the underlying\nfiling or disclosure.\n\n`book_hash` identifies the book's contents (the set of `ticker: weight` pairs). Sources\nthat restate an unchanged portfolio daily produce a new `signal_id` with the same\n`book_hash`, so compare hashes to know whether the weights moved.\n\nWeights are decimal strings that sum to at most one; `cash_weight` is the remainder.\n\nRequires your general (`tik_`) key; a reporting key is refused.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/SignalStrategyIdPath"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SignalStrategyDetail"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "401": {
            "description": "Missing, malformed or unknown `X-API-Key`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SimpleError"
                }
              }
            }
          },
          "403": {
            "description": "`insufficient_scope`, `key_revoked` or `integrator_suspended`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SimpleError"
                }
              }
            }
          },
          "404": {
            "description": "No such strategy for you. A strategy that exists but is not published to integrators answers the same, so the response never reveals whether an id exists.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SimpleError"
                },
                "example": {
                  "error": "strategy_not_found"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/signals/strategies/{id}/history": {
      "get": {
        "operationId": "listSignalStrategyHistory",
        "tags": [
          "Signals"
        ],
        "summary": "The strategy's past books, newest first",
        "security": [
          {
            "IntegratorApiKey": []
          }
        ],
        "description": "Every book the source produced that Treasures finished acting on, as full weight vectors,\nnewest first. Treasures' own weekly restatements of an unchanged book are not rows here;\na source that re-publishes an unchanged portfolio daily is, so consecutive rows often share\na `book_hash`.\n\nPass `next_cursor` back as `cursor` to page; `has_more` tells you whether another page\nexists. `data` may be shorter than `limit` while `has_more` is `true`.\n\nRequires your general (`tik_`) key; a reporting key is refused.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/SignalStrategyIdPath"
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "Opaque; from a previous page's `next_cursor`.",
            "schema": {
              "type": "string",
              "maxLength": 256
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SignalBookHistoryResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "401": {
            "description": "Missing, malformed or unknown `X-API-Key`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SimpleError"
                }
              }
            }
          },
          "403": {
            "description": "`insufficient_scope`, `key_revoked` or `integrator_suspended`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SimpleError"
                }
              }
            }
          },
          "404": {
            "description": "No such strategy for you (see the detail route).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SimpleError"
                },
                "example": {
                  "error": "strategy_not_found"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/signals-orders/exit/plan": {
      "post": {
        "operationId": "planSignalOrdersExit",
        "tags": [
          "Signals"
        ],
        "summary": "The sells that exit a strategy book from your wallet, with no quotes",
        "security": [
          {
            "IntegratorApiKey": []
          }
        ],
        "description": "Returns one full-share sell per name your wallet holds in the strategy's current book (the\nSolana wallet, or `eth_wallet` on BNB Smart Chain with `chain: \"bnb\"`), plus any `tickers`\nyou add. Nothing is quoted and nothing expires, so this is the default flow: show the\norders, then call `POST /quote/sell` per order when the signer is ready, and submit each\nquote through `POST /trade/submit` unchanged. Human and hardware-wallet flows should use\nthis route; `POST /signals-orders/exit` is for programmatic signers.\n\nWith `chain: \"bnb\"` the plan reads `eth_wallet` on BNB Smart Chain; quote each order with\n`\"chain\": \"bnb\"`, `\"protocol\"` (see **Quoting each order**), `eth_wallet` and a fresh\n`eth_signature`, and submit each on its own `POST /trade/submit`, never as a batch. Without `chain: \"bnb\"`, a body carrying `eth_wallet`\nis refused with `400 invalid_request`.\n`strategy_id` accepts the id or the slug; the response always carries the canonical id.\n`as_of` is when Treasures ingested the book (unix seconds), not the filing date.\n\n`nav_usdc` counts the priced names you hold in scope only. On Solana an unpriced holding is\nstill an order, with `notional_usdc: null`, ranked after the priced ones; with\n`chain: \"bnb\"` it is skipped as `price_unavailable`, since its venue floor cannot be\nchecked. Shares are floored to 18 decimal places, never rounded up. A holding worth under\n$0.01 reads as not held. A holding that could not be read is skipped as\n`holdings_unknown`, never assumed absent, with one exception on Solana: a token account\nfound but not decodable into a balance reads as zero, so that name is `not_held`.\n\nAt most 25 orders are returned and, on Solana, their upstream quote calls are capped at 30\n(see `POST /signals-orders/exit`; `chain: \"bnb\"` has no quote-call cap). The overflow (the\nsmallest by notional, unpriced first) is skipped as `leg_cap`, so\n`POST /signals-orders/exit` answers the same split. With `protocol` sent, only the pinned\nvenues are read and sold: a name also held on another venue gets no `skipped` entry, so\nrepeat the call per venue.\n\n**Quoting each order.** Send one `POST /quote/sell` per order, with the same wallet and a\nfresh proof:\n`{ \"ticker\": <ticker>, \"amount_shares\": <shares>, \"chain\": \"sol\", \"protocol\": <the protocol you sent here, if any>, \"sol_wallet\": <sol_wallet>, \"ownership_proof\": <proof>, \"max_slippage_bps\": <bps> }`.\nTo submit several Solana quotes in one request, send them together through\n`POST /trade/submit/batch`.\n\nWith `chain: \"bnb\"`, send `\"chain\": \"bnb\"` and `eth_wallet` instead, and always a\n`\"protocol\"`: the pin you sent here, or `[\"ondo\",\"xstocks\"]` when you sent none. An unpinned\nbnb quote can route to bStocks, which the plan never read.\n\n**One wallet per strategy.** Your holdings are not tracked per strategy: every name of the\nbook you hold in this wallet counts, whichever strategy (or none) you bought it for. Two\nstrategies sharing a name in one wallet will sell or resize each other's position, so give\neach strategy its own wallet.\n\n`expected_book_hash`, when sent, must equal the served book's `book_hash`, or the call is\nrefused with `409 book_changed` before the wallet is read or anything is quoted: re-read the\nbook and decide again.\n\n`max_slippage_bps` is optional here (nothing is quoted) and range-checked when sent.\nRequires your general (`tik_`) key; a reporting key is refused.\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SignalOrdersRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SignalOrderPlan"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request body (including `eth_wallet`, or a `protocol` with no Solana protocol), or slippage out of range.",
            "content": {
              "application/json": {
                "schema": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/InvalidRequestError"
                    },
                    {
                      "$ref": "#/components/schemas/InvalidSlippageError"
                    }
                  ]
                },
                "example": {
                  "error": "invalid_request",
                  "message": "eth_wallet is not supported on this route yet"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/SignalOrdersUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/SignalOrdersForbidden"
          },
          "404": {
            "$ref": "#/components/responses/SignalOrdersStrategyNotFound"
          },
          "409": {
            "$ref": "#/components/responses/SignalOrdersBookChanged"
          },
          "422": {
            "description": "`book_unavailable`: the strategy has no book yet.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SimpleError"
                },
                "examples": {
                  "book_unavailable": {
                    "value": {
                      "error": "book_unavailable"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/SignalOrdersUnavailable"
          }
        }
      }
    },
    "/signals-orders/exit": {
      "post": {
        "operationId": "quoteSignalOrdersExit",
        "tags": [
          "Signals"
        ],
        "summary": "The sells that exit a strategy book, each with its signable quote",
        "security": [
          {
            "IntegratorApiKey": []
          }
        ],
        "description": "The same orders as `POST /signals-orders/exit/plan`, each carrying `quote`: exactly the\n`POST /quote/sell` answer for that order, signable payloads included. Sign and submit each\nquote through `POST /trade/submit` unchanged.\n\n**For programmatic signers only.** A Solana leg is signable for about 45 s after this\nresponse. Each quote's own `expires_at` binds; the top-level `expires_at` is the earliest\nof them and `signing_window_sec` is the seconds left until it. Human and hardware-wallet\nflows should call `POST /signals-orders/exit/plan`, then `POST /quote/sell` per order when\nready.\n\nA partial result is normal: an order whose quote is refused is moved to `skipped` with\nthe error code `POST /quote/sell` would have answered (for example `no_routes`, which on\na sub-minimum leg carries no minimum, or `holdings_insufficient`), and the response is\nstill `200`. An order whose quote expired before the response was sent is skipped as\n`quote_stale`.\n\n`max_slippage_bps` is required here and applies to every leg. To submit several quotes in\none request, send them together through `POST /trade/submit/batch`.\n\n**One call at a time per wallet and strategy.** While a quote from an earlier `/exit` for\nthe same wallet and strategy is neither final (`GET /quote/{quote_id}/status`) nor five\nminutes past its `expires_at`, a new call is refused with `409 orders_in_flight` naming\nthose `quote_ids` (an empty list while the earlier call is still quoting), with\n`Retry-After` in seconds. A submitted quote counts as final once its status has been read\nas final, so poll every quote you submit. The plan route is never refused this way.\n\nLimits on this route count upstream quote calls, not requests: an order held on one\nSolana venue costs 1 point, on two venues 3, on three 6 (each pass re-quotes the venues\nnot yet filled). Points come from a per-integrator bucket (30 a minute) and from a bucket\nshared by every caller (90 a minute), charged only after the wallet is admitted and only\nwhen there is something to quote.\n\nThe plan never costs more than 30 points: orders past that are skipped as `leg_cap`, so an\nexit of more than ten names held on two venues each exits the rest on the next call. A\nplan costing more than the points left is refused whole with `429` before any order is\nquoted. A `429` from the shared bucket can be another integrator's traffic and does not\nspend your own points. The `X-RateLimit-*` headers describe the shared bucket.\n\n**One wallet per strategy.** Your holdings are not tracked per strategy: every name of the\nbook you hold in this wallet counts, whichever strategy (or none) you bought it for. Two\nstrategies sharing a name in one wallet will sell or resize each other's position, so give\neach strategy its own wallet.\n\nRequires your general (`tik_`) key; a reporting key is refused.\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/SignalOrdersRequest"
                  },
                  {
                    "required": [
                      "max_slippage_bps"
                    ]
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SignalOrdersResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request body (including `eth_wallet`, a missing `max_slippage_bps` or a `protocol` with no Solana protocol), or slippage out of range.",
            "content": {
              "application/json": {
                "schema": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/InvalidRequestError"
                    },
                    {
                      "$ref": "#/components/schemas/InvalidSlippageError"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/SignalOrdersUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/SignalOrdersForbidden"
          },
          "404": {
            "$ref": "#/components/responses/SignalOrdersStrategyNotFound"
          },
          "409": {
            "$ref": "#/components/responses/SignalOrdersConflict"
          },
          "422": {
            "description": "`book_unavailable`: the strategy has no book yet.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SimpleError"
                },
                "examples": {
                  "book_unavailable": {
                    "value": {
                      "error": "book_unavailable"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/SignalOrdersUnavailable"
          }
        }
      }
    },
    "/signals-orders/rebalance/plan": {
      "post": {
        "operationId": "planSignalOrdersRebalance",
        "tags": [
          "Signals"
        ],
        "summary": "The sells and buys that bring your strategy positions to its book, with no quotes",
        "security": [
          {
            "IntegratorApiKey": []
          }
        ],
        "description": "Returns the orders that move your wallet's positions in the strategy's names to the\nstrategy's current book: the Solana wallet, or `eth_wallet` on BNB Smart Chain with\n`chain: \"bnb\"`. Nothing is quoted and nothing expires, so this is the default\nflow: show the orders, then call `POST /quote/sell` (send `shares` as `amount_shares`) or\n`POST /quote/buy` (send `notional_usdc` as `amount_usdc`) per order when the signer is\nready, and submit each quote through `POST /trade/submit` unchanged.\n\n**Quoting each order.** With the same wallet and a fresh proof,\n\n- a sell is `POST /quote/sell` with\n  `{ \"ticker\": <ticker>, \"amount_shares\": <shares>, \"chain\": \"sol\", \"sol_wallet\": <sol_wallet>, \"ownership_proof\": <proof>, \"max_slippage_bps\": <bps> }`\n- a buy is `POST /quote/buy` with\n  `{ \"ticker\": <ticker>, \"amount_usdc\": <notional_usdc>, \"chain\": \"sol\", \"sol_wallet\": <sol_wallet>, \"ownership_proof\": <proof>, \"max_slippage_bps\": <bps> }`.\n\nSend no `protocol`: the plan reads every Solana venue. To submit several Solana quotes in\none request, send them together through `POST /trade/submit/batch`.\n\n**With `chain: \"bnb\"`.** Quote each order with `\"chain\": \"bnb\"`,\n`\"protocol\": [\"ondo\",\"xstocks\"]`, `eth_wallet` in place of `sol_wallet`, and a fresh proof\ncarrying its `eth_signature`; the plan reads ondo and xStocks only, and an unpinned bnb quote\ncan route to bStocks. Submit each quote on its own `POST /trade/submit`, never as a batch. One call\norders at most 25 names, with no quote-call cap.\n\n**Without `amount_usdc` the book's cash weight is sold on every call.** nav is then only\nwhat you hold in scope, and the targets sum to the book's deployed weight of it, so a book\nthat is 10% cash sells about 10% of your held value each time it is called without\n`amount_usdc`. Carry `funding.next_amount_usdc` into the next call to keep that cash in nav.\n\n**Buy-in.** To buy into a strategy from cash, call with `amount_usdc` on a wallet that\nholds none of its names: every order is a buy, sized by its book weight of `amount_usdc`.\nOne call orders at most 25 names and, on Solana, 30 upstream quote calls (a buy costs one\nper Solana venue it can buy on), so a book of 20 names on two venues each takes more than one round:\nsubmit the buys, wait for them to settle, and call again with `funding.next_amount_usdc`.\n\n**Scoped nav.** The plan sizes every name against `nav_usdc`: the value of what you hold in\nthe book's names (plus any `tickers` you add), plus `amount_usdc`. Each name's target is its\nbook weight times that nav; the book's unweighted remainder stays as USDC and is never\nordered. A `tickers` name outside the book has weight zero and is sold in full. Holdings\noutside the scope and the rest of your USDC are never touched. Every sol venue counts, so\n`protocol` is not accepted here.\n\n**Funding.** Buys spend only `amount_usdc`, never the rest of the wallet's USDC, and are\nnever larger than it: when the buys need more, each is scaled down pro rata and rounded\ndown (`funding.buys_scaled`). Scaling is pro rata and a scaled buy under $1 is skipped, so\na small `amount_usdc` spread over many buys (for example under $1 per buy when they are\nequal) can deploy nothing that round; the whole shortfall stays in\n`funding.buys_deferred_usdc`.\n\nA buy that cannot be funded is skipped as `awaiting_sell_proceeds` when the plan also\nsells, or `insufficient_balance` when it does not. A rebalance that only reshuffles what\nyou hold is therefore two rounds:\n\n1. Call with `amount_usdc` omitted. Submit the sells.\n2. Once they settle, call again with `amount_usdc` set to the smaller of\n   `funding.next_amount_usdc` and `usdc_available` (proceeds land net of fees and\n   slippage). Omit `amount_usdc` when that is zero: `\"0\"` is refused with `400`. Submit the\n   buys.\n\nUse `funding.next_amount_usdc`, not `funding.buys_deferred_usdc`: it is the strategy's cash\nafter this round (`amount_usdc` plus the sells, less the buys), so it keeps the book's\nunweighted remainder and the weight of any `not_tradable` name in nav. Calling round 2\nwithout `amount_usdc`, or with only the deferred buys, shrinks nav, and the plan sells\nagain.\n\n**Wait for every order to finish before calling again.** Each order from the previous\nround must have reached a final status (`GET /quote/{quote_id}/status`) before any new call.\nThe plan reads your holdings as they stand and this route never refuses an early or retried\ncall, so it returns the same sells again and both sets can execute.\n(`POST /signals-orders/rebalance` refuses such a call with `409 orders_in_flight`.)\n\n**One wallet per strategy.** Your holdings are not tracked per strategy: every name of the\nbook you hold in this wallet counts, whichever strategy (or none) you bought it for. Two\nstrategies sharing a name in one wallet will sell or resize each other's position, so give\neach strategy its own wallet.\n\n`expected_book_hash`, when sent, must equal the served book's `book_hash`, or the call is\nrefused with `409 book_changed` before the wallet is read or anything is quoted.\n\nSells are floored to 18 decimal places and buys to 6, never rounded up. A gap under $1 is\nskipped as `below_min_notional`. A book name Treasures cannot buy on Solana is skipped as\n`not_tradable` and its weight stays in USDC. At most 25 orders are returned and their\nupstream quote calls are capped at 30 (see `POST /signals-orders/rebalance`): sells are\nadmitted first, then buys, each side largest first; the first order that does not fit and\nevery one after it is skipped as `leg_cap`.\n\nUnlike `/exit`, which skips a name it cannot read, a rebalance refuses the whole request\nwhen any name in scope cannot be read (`holdings_unknown`) or a held one cannot be priced\n(`price_unavailable`), because one mis-sized name would mis-size every other order. The\nrefusal lists the `tickers` to retry or remove.\n\n`max_slippage_bps` is optional here (nothing is quoted) and range-checked when sent.\nRequires your general (`tik_`) key; a reporting key is refused.\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SignalRebalanceRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SignalRebalancePlan"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request body (including `eth_wallet`, `protocol` or `amount_usdc: \"0\"`), or slippage out of range.",
            "content": {
              "application/json": {
                "schema": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/InvalidRequestError"
                    },
                    {
                      "$ref": "#/components/schemas/InvalidSlippageError"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/SignalOrdersUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/SignalOrdersForbidden"
          },
          "404": {
            "$ref": "#/components/responses/SignalOrdersStrategyNotFound"
          },
          "409": {
            "$ref": "#/components/responses/SignalOrdersBookChanged"
          },
          "422": {
            "description": "- `book_unavailable`: the strategy has no book yet.\n- `holdings_unknown` or `price_unavailable` with `tickers`: those names could not be\n  read or priced, so no plan is offered. A read or price failure is usually transient\n  and can be retried, but a book name that is no longer tradable (an inactive listing)\n  refuses every rebalance on this strategy until its next book, so do not retry\n  blindly; `POST /signals-orders/exit` skips that name and serves the rest.\n- `insufficient_balance`: `amount_usdc` is more than the wallet's Solana USDC.\n- `strategy_halted`: the strategy is halted, so no rebalance is offered and nothing is\n  read; `POST /signals-orders/exit/plan` still serves it.\n",
            "content": {
              "application/json": {
                "schema": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/SignalOrderRefusal"
                    },
                    {
                      "$ref": "#/components/schemas/SimpleError"
                    }
                  ]
                },
                "examples": {
                  "book_unavailable": {
                    "value": {
                      "error": "book_unavailable"
                    }
                  },
                  "price_unavailable": {
                    "value": {
                      "error": "price_unavailable",
                      "tickers": [
                        "AAPL"
                      ]
                    }
                  },
                  "insufficient_balance": {
                    "value": {
                      "error": "insufficient_balance"
                    }
                  },
                  "strategy_halted": {
                    "value": {
                      "error": "strategy_halted"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/SignalOrdersUnavailable"
          }
        }
      }
    },
    "/signals-orders/rebalance": {
      "post": {
        "operationId": "quoteSignalOrdersRebalance",
        "tags": [
          "Signals"
        ],
        "summary": "The sells and buys that bring your strategy positions to its book, each with its signable quote",
        "security": [
          {
            "IntegratorApiKey": []
          }
        ],
        "description": "The same orders as `POST /signals-orders/rebalance/plan`, each carrying `quote`: exactly the\n`POST /quote/sell` or `POST /quote/buy` answer for that order, signable payloads included.\nSign and submit each quote through `POST /trade/submit` unchanged. The two-round funding\nflow is the plan route's: in round 1, submit the sells; once they settle, call again with\n`amount_usdc` set to the smaller of `funding.next_amount_usdc` and `usdc_available`\n(omitted when that is zero) for the buys.\n\nWithout `amount_usdc` the book's cash weight is sold on every call, and a buy-in from cash\nis `amount_usdc` on a wallet holding none of the names; see\n`POST /signals-orders/rebalance/plan`. To submit several quotes in one request, send them\ntogether through `POST /trade/submit/batch`.\n\n**One call at a time per wallet and strategy.** While a quote from an earlier `/rebalance`\nfor the same wallet and strategy is neither final (`GET /quote/{quote_id}/status`) nor\nfive minutes past its `expires_at`, a new call is refused with `409 orders_in_flight`\nnaming those `quote_ids` (an empty list while the earlier call is still quoting), with\n`Retry-After` in seconds, so a retry never mints the same sells twice.\n\nA submitted quote counts as final once its status has been read as final, so poll every\nquote you submit. The plan route is never refused this way: wait for every order there\nyourself.\n\n**One wallet per strategy.** Your holdings are not tracked per strategy: every name of the\nbook you hold in this wallet counts, whichever strategy (or none) you bought it for. Two\nstrategies sharing a name in one wallet will sell or resize each other's position, so give\neach strategy its own wallet.\n\n**For programmatic signers only.** A Solana leg is signable for about 45 s after this\nresponse. Each quote's own `expires_at` binds; the top-level `expires_at` is the earliest\nof them and `signing_window_sec` is the seconds left until it. Human and hardware-wallet\nflows should call `POST /signals-orders/rebalance/plan`, then quote each order when ready.\n\nA partial result is normal: an order whose quote is refused is moved to `skipped` with the\nerror code its quote route would have answered (for example `no_routes`, also what a buy\nthe wallet cannot fund at quote time answers), and the response is still `200`. A buy\nskipped here is counted in `funding.buys_deferred_usdc` and spends nothing from\n`funding.next_amount_usdc`; a sell skipped here adds nothing to it, so the next call never\nspends USDC that no sell freed.\n\nWhen no sell is quoted, a buy the plan held as `awaiting_sell_proceeds` is skipped as\n`insufficient_balance` instead, since no proceeds are coming. An order whose quote expired\nbefore the response was sent is skipped as `quote_stale`.\n\n`max_slippage_bps` is required here and applies to every leg.\n\nLimits count upstream quote calls, from the same buckets as `POST /signals-orders/exit`: a\nsell held on one Solana venue costs 1 point, on two 3, on three 6; a buy costs at most 1\npoint per Solana venue it can buy on. The plan never costs more than 30 points (orders past\nthat are skipped as `leg_cap`), so it always fits an empty per-integrator bucket; a plan\ncosting more than the points left this minute is refused whole with `429` before any order\nis quoted. A `429` from the shared bucket does not spend your own points.\n\nRequires your general (`tik_`) key; a reporting key is refused.\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/SignalRebalanceRequest"
                  },
                  {
                    "required": [
                      "max_slippage_bps"
                    ]
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SignalRebalanceResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request body (including `eth_wallet`, `protocol`, `amount_usdc: \"0\"` or a missing `max_slippage_bps`), or slippage out of range.",
            "content": {
              "application/json": {
                "schema": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/InvalidRequestError"
                    },
                    {
                      "$ref": "#/components/schemas/InvalidSlippageError"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/SignalOrdersUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/SignalOrdersForbidden"
          },
          "404": {
            "$ref": "#/components/responses/SignalOrdersStrategyNotFound"
          },
          "409": {
            "$ref": "#/components/responses/SignalOrdersConflict"
          },
          "422": {
            "description": "As on `POST /signals-orders/rebalance/plan`, including `strategy_halted`; nothing is quoted.",
            "content": {
              "application/json": {
                "schema": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/SignalOrderRefusal"
                    },
                    {
                      "$ref": "#/components/schemas/SimpleError"
                    }
                  ]
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/SignalOrdersUnavailable"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "IntegratorApiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "Per-organisation key issued out of band. Two kinds:\n\n- `tik_…` (general: API access)\n- `trk_…` (reporting: read-only, intended to be handed to a third party, and accepted\n  **only** on the reporting routes: today just `GET /settlements`. Every other route in\n  this spec answers `insufficient_scope`).\n\nRequired by `GET /settlements`, by the `/payouts` routes, by `POST /quote/preview`, by\n`GET /stocks/{ticker}`, by the `/signals` routes, by the `/signals-orders` routes and by\n`POST /trade/submit/batch` (all but `/settlements` take a general `tik_` key only, being\nnon-reporting routes); accepted on every other route for attribution and a\nper-organisation rate bucket. Send it on `POST /trade/submit` too; that is what makes a\ntrade appear in your `GET /settlements` reporting.\n\nA missing or unknown key is `401 invalid_api_key`; a real but retired key is\n`403 key_revoked`.\n"
      }
    },
    "parameters": {
      "SolWalletQuery": {
        "name": "sol_wallet",
        "in": "query",
        "required": false,
        "schema": {
          "$ref": "#/components/schemas/SolAddress"
        }
      },
      "SourceQuery": {
        "name": "source",
        "in": "query",
        "required": false,
        "description": "Column toggle (not a row filter). `all` (default) leaves the internal-lot P&L columns null; `internal` populates them from a replay of completed internal trades only. Realized P&L follows Hyperliquid `closedPnl` semantics.",
        "schema": {
          "type": "string",
          "enum": [
            "all",
            "internal"
          ],
          "default": "all"
        }
      },
      "EvmWalletQuery": {
        "name": "eth_wallet",
        "in": "query",
        "required": false,
        "schema": {
          "$ref": "#/components/schemas/EvmAddress"
        }
      },
      "SignalStrategyIdPath": {
        "name": "id",
        "in": "path",
        "required": true,
        "description": "The strategy's `strategy_id` (stable) or its `slug` (may be renamed).",
        "schema": {
          "type": "string",
          "minLength": 1,
          "maxLength": 64
        }
      }
    },
    "responses": {
      "InvalidRequest": {
        "description": "Malformed query, body, or path parameter.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/InvalidRequestError"
            }
          }
        }
      },
      "RateLimited": {
        "description": "Sliding window exceeded: per-IP or per-(IP, wallet), plus a per-organisation bucket (shared across all of your keys) whenever a valid `X-API-Key` is presented. `Retry-After` header carries delta-seconds.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/SimpleError"
            },
            "example": {
              "error": "Too many requests"
            }
          }
        }
      },
      "ProviderUnavailable": {
        "description": "Upstream provider failed or rate-limited us.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/SimpleError"
            },
            "example": {
              "error": "provider_unavailable"
            }
          }
        }
      },
      "AddressBlocked": {
        "description": "A wallet on the request was flagged by sanctions screening. Permanent;\ndo not retry with the same wallet.\n",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/SimpleError"
            },
            "example": {
              "error": "address_blocked"
            }
          }
        }
      },
      "ScreeningUnavailable": {
        "description": "Sanctions screening could not be completed and the request was rejected\n(fail-closed). Transient; back off and retry.\n",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/SimpleError"
            },
            "example": {
              "error": "screening_unavailable"
            }
          }
        }
      },
      "SignalOrdersUnauthorized": {
        "description": "Missing, malformed or unknown `X-API-Key`, or an ownership-proof failure.",
        "content": {
          "application/json": {
            "schema": {
              "anyOf": [
                {
                  "$ref": "#/components/schemas/OwnershipProofError"
                },
                {
                  "$ref": "#/components/schemas/SimpleError"
                }
              ]
            }
          }
        }
      },
      "SignalOrdersForbidden": {
        "description": "`address_blocked` (sanctions screening flagged the wallet), or `insufficient_scope`, `key_revoked` or `integrator_suspended`.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/SimpleError"
            }
          }
        }
      },
      "SignalOrdersStrategyNotFound": {
        "description": "No such strategy for you (see `GET /signals/strategies/{id}`).",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/SimpleError"
            },
            "example": {
              "error": "strategy_not_found"
            }
          }
        }
      },
      "SignalOrdersUnavailable": {
        "description": "Transient; retry.\n\n- `screening_unavailable` or `integrator_fee_misconfigured` (see `POST /quote/sell`)\n- `balance_unavailable`: the wallet's Solana USDC could not be read, and is never reported\n  as zero\n- `holdings_unavailable`: the wallet's holdings could not be read.\n\nWhen the reads behind the plan (screening, the strategy and its book, holdings, prices and\nUSDC) did not answer within 15 seconds, the call answers `holdings_unavailable`, or\n`screening_unavailable` when screening was the read still pending, with `Retry-After: 15`.",
        "headers": {
          "Retry-After": {
            "description": "Delta-seconds, 15, sent when the reads passed their deadline. Wait that long before retrying.",
            "schema": {
              "type": "integer"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/SimpleError"
            },
            "examples": {
              "holdings_unavailable": {
                "value": {
                  "error": "holdings_unavailable"
                }
              },
              "balance_unavailable": {
                "value": {
                  "error": "balance_unavailable"
                }
              },
              "screening_unavailable": {
                "value": {
                  "error": "screening_unavailable"
                }
              }
            }
          }
        }
      },
      "SignalOrdersBookChanged": {
        "description": "`book_changed`: `expected_book_hash` is not the book served now. The wallet was not read and nothing was quoted; re-read the book (`book_hash` is the served one) and decide again.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/SignalOrdersBookChangedError"
            }
          }
        }
      },
      "SignalOrdersConflict": {
        "description": "- `book_changed`: `expected_book_hash` is not the book served now; the wallet was not read\n  and nothing was quoted.\n- `orders_in_flight`: a quote from an earlier call for the same wallet and strategy is\n  neither final nor five minutes past its `expires_at` (`quote_ids`; empty while that call\n  is still quoting). Nothing was quoted; poll `GET /quote/{quote_id}/status` for the quotes\n  you submitted, and call again after `Retry-After` seconds or once each is final.\n\n  A quote you never submitted has no status to poll: `Retry-After` is how long until the\n  earliest listed quote is five minutes past its `expires_at` (60 while the earlier call is\n  still quoting). If an earlier call's response was lost, its quotes hold the wallet and\n  strategy until the latest one's `expires_at` plus five minutes: wait out `Retry-After`,\n  or submit the quotes you do hold.\n",
        "headers": {
          "Retry-After": {
            "description": "Delta-seconds, sent with `orders_in_flight` only: until the earliest listed quote is five minutes past its `expires_at` (at least 1), or 60 while the earlier call is still quoting. Other listed quotes may still hold after it, and the next call says so.",
            "schema": {
              "type": "integer"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "anyOf": [
                {
                  "$ref": "#/components/schemas/SignalOrdersBookChangedError"
                },
                {
                  "$ref": "#/components/schemas/SignalOrdersInFlightError"
                }
              ]
            }
          }
        }
      },
      "SignalReadsRateLimited": {
        "description": "A bucket of the `/signals` reads is spent: 1200 calls a minute per organisation (shared by all of your keys) and 600 a minute per key. There is no per-IP bucket on these routes. `Retry-After` carries delta-seconds.",
        "headers": {
          "Retry-After": {
            "description": "Delta-seconds to wait before retrying.",
            "schema": {
              "type": "integer"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/SimpleError"
            },
            "example": {
              "error": "Too many requests"
            }
          }
        }
      },
      "PortfolioBusy": {
        "description": "The server is already computing as many fresh snapshots as it safely can\nand yours was not cached. Retry after `Retry-After` seconds; cached\nsnapshots are never refused.\n",
        "headers": {
          "Retry-After": {
            "description": "Delta-seconds to wait before retrying the same request.",
            "schema": {
              "type": "integer"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/SimpleError"
            },
            "example": {
              "error": "portfolio_busy"
            }
          }
        }
      },
      "QuoteServiceUnavailable": {
        "description": "`screening_unavailable`: sanctions screening could not be completed and the request was\nrejected (fail-closed). Transient; back off and retry.\n`integrator_fee_misconfigured` (with an `X-API-Key`): your configured fee schedule no longer\nfits a venue Treasures routes through. A Treasures-side configuration issue that retrying\nsoon won't clear; contact Treasures, or send `integrator_fee_bps: 0` to quote without your fee.\n",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/SimpleError"
            },
            "examples": {
              "screening_unavailable": {
                "value": {
                  "error": "screening_unavailable"
                }
              },
              "integrator_fee_misconfigured": {
                "value": {
                  "error": "integrator_fee_misconfigured"
                }
              }
            }
          }
        }
      }
    },
    "schemas": {
      "Tradability": {
        "type": "string",
        "enum": [
          "thin",
          "untradable"
        ],
        "description": "Probe warning for one cell. `thin`: the cell fills, but not at every size below its measured minimum. `untradable`: nothing filled at any size across a full measurement window, and no minimum accompanies it. **Neither value disables the cell**; quotes are still accepted for both. Absent means unmeasured or unwarned, never healthy-with-value-null.\n"
      },
      "WarnReason": {
        "type": "string",
        "enum": [
          "settlement_failure",
          "no_price_feed",
          "no_fill_window",
          "no_settlements",
          "low_volume"
        ],
        "description": "Why the cell is warned, strongest evidence first:\n\n1. `settlement_failure` (a real order died)\n2. `no_price_feed` (the venue holds no price for the pair)\n3. `no_fill_window` (a full window of quiet auctions)\n4. `no_settlements` (no value-bearing on-chain settlement in the census window)\n5. `low_volume` (a volume proxy).\n\nAbsent when unwarned, or when the warn predates reason recording. Not stable over a cell's\nlifetime: a `low_volume` warn that later kills a real order flips to `settlement_failure`.\n"
      },
      "SideNeutralWarnReason": {
        "type": "string",
        "enum": [
          "low_volume",
          "no_price_feed",
          "no_settlements"
        ],
        "description": "The subset of `WarnReason` that bears on an exit as much as an entry, and the only values a sell surface publishes. The buy-sided reasons (`no_fill_window`, `settlement_failure`) are measured against buys, so a sell leg carrying one would warn about someone else's trade; a cell warned only for those publishes nothing here.\n"
      },
      "ThinSince": {
        "type": "string",
        "format": "date-time",
        "description": "When the warning above was first raised. Present exactly when `tradability` is."
      },
      "SolAddress": {
        "type": "string",
        "description": "Solana base58 address.",
        "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$",
        "example": "9aJ6jUyG7zG3yfPbsi5tFFqA1cnp7zCfL6pYfqyZP4qE"
      },
      "EvmAddress": {
        "type": "string",
        "description": "Lowercased EVM address (server normalizes on parse).",
        "pattern": "^0x[a-fA-F0-9]{40}$",
        "example": "0x742d35cc6634c0532925a3b844bc454e4438f44e"
      },
      "DecimalString": {
        "type": "string",
        "description": "Decimal number as a string to preserve full precision."
      },
      "UsdcHumanAmount": {
        "type": "string",
        "description": "USDC amount in human units, > 0, up to 6 fractional digits.",
        "pattern": "^(?:[1-9]\\d*|0)(?:\\.\\d{1,6})?$",
        "example": "100.50"
      },
      "SharesHumanAmount": {
        "type": "string",
        "description": "Share amount, > 0, up to 18 fractional digits.",
        "pattern": "^(?:[1-9]\\d*|0)(?:\\.\\d{1,18})?$",
        "example": "1.5"
      },
      "Ticker": {
        "type": "string",
        "pattern": "^[A-Z0-9][A-Z0-9.]{0,9}$",
        "example": "AAPL"
      },
      "Chain": {
        "type": "string",
        "description": "Settlement chain.\n\n- `robinhood` = Robinhood Chain (4663, base currency USDG)\n- `base` = Base (8453)\n- `arbitrum` = Arbitrum One (42161)\n- `bnb` = BNB Smart Chain (56).\n\n`bnb` carries several protocols (`ondo`, `xstocks`, `bstocks`), as `sol` and `eth` do, so\n`chain` alone does NOT identify a cell there: pin `protocol` too. `bnb` is always ACCEPTED\nas an input (a quote `chain` pin, a `/settlements` filter), because historical rows must\nstay queryable and a pin must not become a `400`; it appears on `/stocks*` RESPONSES only\nwhile the venue is open.\n\nWith the venue closed, a `chain: \"bnb\"` buy answers `422 no_routes`, exactly as it would\nfor a ticker that never listed on 56, and a position you already hold on `bnb` still sells.\n",
        "enum": [
          "sol",
          "eth",
          "robinhood",
          "base",
          "arbitrum",
          "bnb"
        ]
      },
      "Protocol": {
        "type": "string",
        "description": "Issuer/venue. `backpack` pairs only with `chain: sol` (Solana-only mints) and `bstocks` only with `chain: bnb`. `ondo` and `xstocks` list on `sol`, `eth` and `bnb`.",
        "enum": [
          "ondo",
          "xstocks",
          "robinhood",
          "coinbase",
          "reality",
          "backpack",
          "bstocks"
        ]
      },
      "PayoutChain": {
        "type": "string",
        "enum": [
          "sol",
          "eth",
          "base"
        ],
        "description": "A chain a sell can pay out on: USDC on that chain, paid to your own wallet there (`sol_wallet` on `sol`, `eth_wallet` on `eth` and `base`). `robinhood`, `arbitrum` and `bnb` are not payout chains."
      },
      "SlippageBps": {
        "type": "integer",
        "minimum": 0,
        "maximum": 10000,
        "description": "Maximum tolerated slippage in basis points. Each route validates against\nits own `[MIN, MAX]` window; out-of-range returns `400 invalid_slippage`\nwith the active bounds.\n"
      },
      "Execution": {
        "type": [
          "string",
          "null"
        ],
        "enum": [
          "transaction",
          "user_operation",
          null
        ],
        "description": "How a **speed-route** leg is handed back.\n\n- `\"transaction\"` (the default; absent and `null` mean the same) is the raw-transaction\n  shape: one `SignableEvmTx` per transaction, signed whole, gas paid by the wallet.\n- `\"user_operation\"` returns the same calls as ONE `evm_calls` payload (`SignableEvmCalls`)\n  for you to pack into an ERC-4337 v0.7 UserOperation from the wallet (which must be\n  **EIP-7702-delegated to Alchemy Modular Account v2** on that chain, or not delegated at\n  all: a wallet with no code delegates in that first operation through `eip7702Auth`),\n  sponsor with your own paymaster, sign, and return as `evm_user_operation`; Treasures\n  submits it to a bundler and tracks it. The leg is then `gasless: true` with\n  `estimated_gas_usd: \"0\"`.\n\nOnly meaningful with `priority: \"speed\"`; sending `\"user_operation\"` without it is\n`400 invalid_request`.\n\nServed on `base` and `robinhood` (a chain whose bundler is not configured answers\n`422 no_routes` pinned, or drops that chain with `speed_route_unavailable` / `disabled`\nunpinned). Not served on `bnb`: a bStocks leg there is always a `SignableEvmTx`, so under\n`\"user_operation\"` it is dropped the same way. A wallet delegated to code other than\nModular Account v2 is `400 wallet_not_delegated` when pinned, or a `wallet_not_delegated`\ndrop reason.\n"
      },
      "Priority": {
        "type": [
          "string",
          "null"
        ],
        "enum": [
          "speed",
          null
        ],
        "description": "How to route, when there is a choice. `\"speed\"` asks for the **speed route** on the two L2\nvenues that have one (`robinhood`, `base`): a single on-chain swap that settles in one block\ninstead of a relayed order, quoted as a complete unsigned transaction you sign and Treasures\nbroadcasts. It costs you native gas on that chain; no pre-approval is needed: a wallet that\nhas not approved the router gets an `approve` payload bundled before the `swap` (see\n`SignableEvmTx` `role`). Absent/`null` = today's routing, unchanged.\n\nA **filter, not a preference**: under `\"speed\"` the same-chain candidates are\n\n- `sol` (unchanged; its route is already fast)\n- the `robinhood`/`base` speed routes\n- the `bnb` + `bstocks` cell (a bStocks leg is a speed-route transaction at every priority,\n  so `\"speed\"` changes nothing for it; `bnb` + `ondo` and `bnb` + `xstocks` have no speed\n  route and are absent under `\"speed\"`).\n\nA `robinhood`/`base` leg the speed route cannot serve is **absent** from the response, with\na `speed_route_unavailable` warning naming the chain and the reason.\n\nThe one exception, a `/quote/sell` leg returned on its relayed route, is disclosed by the\n`speed_route_fallback` warning.\n\n`eth` is never quoted on its own route under `\"speed\"`. On `/quote/buy` and `/quote/preview`\nit can still come back as a cross-chain leg (`origin_chain` present) when you are not funded\non eth and another chain covers the amount, so a `chain: \"eth\"` pin yields that leg or\n`422 no_routes`.\n\nOn `/quote/sell`, `chain: \"eth\"` (or `[\"eth\"]`) together with `\"speed\"` is refused as\n`400 invalid_request` (`priority: \"speed\" is not available on eth`), and a set that also\nnames other chains simply loses `eth`, unless the sell pays out on another chain\n(`payout_chain`), where an `eth/ondo` position sells cross-chain whatever the `priority`. A\npin on any other chain with no speed route (for example `arbitrum`) is refused the same way\non every endpoint.\n\nA `bnb` pin whose `protocol` names only `ondo` / `xstocks` is refused the same way on\n`/quote/sell` (unless it pays out on another chain); on `/quote/buy` and `/quote/preview` it\npasses the check, as an `eth` pin does, and answers `422 no_routes` because neither cell has\na speed or cross-chain route. The `bnb` + `bstocks` cell can also come back as a cross-chain\nleg (`origin_chain` present) when you are not funded on `bnb` and another chain covers the\namount.\n"
      },
      "SimpleError": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string"
          }
        },
        "additionalProperties": false
      },
      "SimpleErrorWithMessage": {
        "type": "object",
        "required": [
          "error",
          "message"
        ],
        "properties": {
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        },
        "additionalProperties": false
      },
      "InvalidRequestError": {
        "type": "object",
        "required": [
          "error",
          "message"
        ],
        "properties": {
          "error": {
            "type": "string",
            "enum": [
              "invalid_request"
            ]
          },
          "message": {
            "type": "string"
          }
        },
        "additionalProperties": false
      },
      "InvalidSlippageError": {
        "type": "object",
        "required": [
          "error",
          "allowed_min_bps",
          "allowed_max_bps"
        ],
        "properties": {
          "error": {
            "type": "string",
            "enum": [
              "invalid_slippage"
            ]
          },
          "allowed_min_bps": {
            "type": "integer"
          },
          "allowed_max_bps": {
            "type": "integer"
          }
        },
        "additionalProperties": false
      },
      "OwnershipProofError": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string",
            "enum": [
              "ownership_proof_invalid",
              "ownership_proof_sol_invalid",
              "ownership_proof_eth_invalid",
              "ownership_proof_skewed"
            ]
          }
        },
        "additionalProperties": false
      },
      "NoRoutesError": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string",
            "enum": [
              "no_routes"
            ]
          },
          "min_notional_usdc": {
            "type": "string",
            "description": "Present only when your order was below a known minimum for this\nlisting: the actionable answer to a refusal that would otherwise\ncarry no reason at all. Retry at or above this size. The number is\nthe venue's own floor when it states one or it is known in advance\n(then `reason` is `amount_too_small`), a size a market maker quoted\nyour own wallet when asked again at refusal time, or otherwise a\nminimum we measured for the listing.\n\nWhenever `reason` is `amount_too_small`, it is present if any venue\nthat refused for size has a known floor above your order, even when\nother venues refused for another reason. It then describes only the\nvenues that refused for size: a venue refused for another reason\n(for example `insufficient_gas` on a Solana leg) still needs its own\nremedy.\n\nOn `/quote/sell` it is a USDC value, not a share count: the shares\nthe quote could not place (the whole order, unless other legs could\ntake part of it), valued at the reference price, fell short of it.\nRe-quote a share amount worth at least this much at the current\nprice. A position worth less may not be sellable on that chain until\nit is topped up.\n\nRead AFTER the venue refused, never before: this never causes a\nrefusal, it only explains one.\n"
          },
          "reason": {
            "type": "string",
            "enum": [
              "slippage_exceeded",
              "amount_too_small",
              "price_off_reference",
              "price_implausible",
              "reference_unavailable",
              "no_price_feed",
              "market_closed",
              "insufficient_balance",
              "cross_chain_wallet_missing",
              "payout_route_unavailable",
              "no_market_maker_fill",
              "insufficient_gas",
              "cross_chain_route_unavailable"
            ],
            "description": "Present only when a strict majority of dropped cells share the same actionable reason;\notherwise omitted.\n\n**This enum is deliberately smaller than the set of internal refusals.** A refusal with\nno published counterpart yields a bare `no_routes` with no `reason` at all: notably an\nunlisted cell, whether its venue is switched off or it is a supply-gated token (a\nCoinbase B20 or bStocks token) that is deployed but not yet minted. The read side\nalready carries the remedy, since such a cell reports `address: null` (or no key at\nall), omits its chain from `available_chains`, and publishes no `min_trade_size_usd`.\nRe-read `/stocks/tickers` rather than retrying at another size.\n\n- `price_off_reference` covers both non-caller-tunable price refusals: an outright\n  refusal against the asset's reference market price (a route existed but priced too far\n  from it to be safe to fill), and a dropped cell whose route price impact exceeded the\n  absolute backstop. Unlike `slippage_exceeded`, neither cap is caller-tunable, so\n  raising `max_slippage_bps` will not clear them; do not prompt for that.\n\n  The cap tracks how live the reference is rather than the clock: outside the regular\n  session the check may measure against a live market price instead of the previous\n  close. The reference it used is internal and is NOT the `tradfi_reference` on a\n  successful quote; do not reconstruct the check from that field. Treat the refusal as\n  transient: neither a smaller size nor a higher `max_slippage_bps` clears it, but a\n  re-quote 30–60s later may.\n\n- `market_closed`: the listing's trading session is shut (weekend, overnight for a\n  regular-hours-only listing, or a US market holiday). Refused **before** signing, so\n  nothing was committed. Not size- or slippage-tunable: resubmit when the session\n  reopens. Sessions are per-listing, and some listings close **per chain** rather than\n  as a whole, so a `chain`-pinned request can be refused while another chain still\n  serves the ticker. Retry unpinned, or on another chain from `available_chains`, before\n  waiting out the session.\n\n- `price_implausible`: the quote sits so far from the reference that we do not trust our\n  own arithmetic, so we will not execute on it. No size, no `max_slippage_bps` and no\n  acknowledgement clears it; a re-quote may.\n\n- `reference_unavailable` is a **retained wire word with no current producer**. A\n  missing reference used to refuse the quote; it is now served, with\n  `tradfi_reference: null` and a `no_reference` entry in `warnings[]`. Keep parsing the\n  value: it is still published, so a client that models it does not break, but do not\n  build a flow around receiving it.\n\n- `insufficient_balance` describes **your own wallet**, not the venue: it is short the\n  spent token on that chain, so fund it and re-quote. On a Solana leg, the venue refused\n  your wallet for the spent token (a buy whose wallet is short of USDC or has no USDC\n  account, or a sell short of the shares it asks to sell; a Solana leg the venue still\n  quotes is not checked against your balance again at submit, so a wallet short at\n  submit fails that leg as `not_landed`).\n\n  Under `priority: \"speed\"` a buy's Solana leg is refused before any venue is asked when\n  your `sol_wallet` reads short the amount and none of your other wallets covers it\n  either (when one does, see `cross_chain_route_unavailable`).\n\n  A speed leg on any other chain refuses on the same condition: `chain`-pinned, the one\n  shape where that leg is the only candidate, its refusal becomes the whole answer;\n  unpinned, it drops that leg from the response (never a relayed fallback) and the\n  response carries a `speed_route_unavailable` warning. (A missing router allowance is\n  never a refusal on either shape; the quote bundles the approve.)\n\n- `no_market_maker_fill`: no market maker or route answered for this size at this\n  moment. Not slippage-tunable. A larger order may clear it (see `min_notional_usdc`\n  when present), or a re-quote later.\n\n- `insufficient_gas`: a Solana leg was refused and your `sol_wallet` holds under 0.002\n  SOL, or under 0.01 SOL when the trade must create its output token account. Fund the\n  wallet with SOL and re-quote; a larger order will not clear it.\n\n  Never returned for `quote_only` or for `/quote/preview`, which spend none of your SOL,\n  nor on a request carrying `sol_fee_payer`, which skips the SOL check. That request\n  still sends a market-maker order bound to your `sol_wallet`, which can be refused when\n  the wallet cannot cover the rent of a token account the trade opens; that refusal\n  reads `no_market_maker_fill`.\n\n- `cross_chain_wallet_missing`: under `priority: \"speed\"`, a buy could only be served\n  cross-chain from a chain whose wallet the request did not include. Send both\n  `sol_wallet` and `eth_wallet`.\n\n- `payout_route_unavailable`: `/quote/sell` with `payout_chain` only. You hold enough in\n  your `chain`/`protocol` scope, but not enough of it can pay out on `payout_chain` (see\n  that field for which positions can), or the cross-chain route for a position that\n  could pay out was refused or could not land. Not a holdings problem: pay out on\n  another chain, send no `payout_chain` to sell each position on its own chain, or\n  re-quote later.\n\n- `cross_chain_route_unavailable`: a `priority: \"speed\"` buy only. Another of your\n  wallets holds enough to fund the order (on `/quote/preview`, which reads no balance,\n  the whole amount is assumed to sit on `origin_chain`, `sol` when absent), but no\n  cross-chain route reached the leg: the route was refused or could not be completed, or\n  the listing has none on that chain (on Solana, a leg your `sol_wallet` cannot fund is\n  never served on its own chain instead; an `eth` leg never is under `\"speed\"`).\n\n  `warnings[]` names each such leg with its own `reason`. Fund the named leg's own chain\n  and re-quote; a refused route may also clear on a later re-quote.\n"
          },
          "warnings": {
            "type": "array",
            "description": "Present only on a `priority: \"speed\"` buy or preview refusal that dropped legs it would\notherwise have disclosed, or left out listings it never quotes. Two codes appear today,\neach once per `chain`/`protocol`:\n\n- `cross_chain_route_unavailable` (the same entry a served quote's `warnings[]` carries\n  for that leg)\n- `speed_route_unavailable` with `reason: no_speed_venue`, naming a listing whose\n  own-chain venue `\"speed\"` never tries (an `eth` or `bnb` gasless order, or Reality on\n  `arbitrum`).\n\nAn `eth` listing can carry both codes: its cross-chain route was tried and failed, and\nits own-chain venue was not tried. A `no_speed_venue` entry means the same request\nwithout `priority` would ask that venue: retry without it if a fill that can take\nminutes is acceptable.\n\nA listing whose session is closed is not named. Handle an unrecognised `code` as\ndescribed under `TradeWarning`. A refusal carries no `warnings_ack_token`: there is\nnothing to submit.\n",
            "items": {
              "$ref": "#/components/schemas/TradeWarning"
            }
          }
        },
        "additionalProperties": false
      },
      "BasketPriceUnavailableError": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string",
            "enum": [
              "basket_price_unavailable"
            ]
          }
        },
        "description": "Only reachable on **`/quote/buy`**, and only for a **basket** listing\n(`MAG7X`, the Ondo Intelligent Portfolio). A basket has no single\nunderlying, so no reference market price exists for it and the usual\nreference check cannot run; the one sanity check left is the issuer's\nown published price. This refusal means that price was missing,\nnon-positive, or older than an hour.\n\n`/quote/sell` never returns this: an exit is never gated on the issuer's\nprice feed, so a holder can always get out.\n\nDistinct from `no_routes`: a route existed and the venue was fine, and\nthe refusal lands before any venue is asked for a price. Treat it as\ntransient and retry in a few minutes; no size or slippage change clears\nit, and no other ticker is affected.\n",
        "additionalProperties": false
      },
      "LegAlreadySubmittedError": {
        "type": "object",
        "required": [
          "error",
          "tx_hash",
          "order_hash"
        ],
        "properties": {
          "error": {
            "type": "string",
            "enum": [
              "leg_already_submitted"
            ]
          },
          "message": {
            "type": "string"
          },
          "tx_hash": {
            "type": [
              "string",
              "null"
            ]
          },
          "order_hash": {
            "type": [
              "string",
              "null"
            ]
          },
          "user_op_hash": {
            "type": "string",
            "description": "Present only when the conflict is on a `user_operation` leg: the ERC-4337 op hash the earlier submit owns (its `tx_hash` is null until the bundle mines)."
          }
        },
        "additionalProperties": false
      },
      "WalletNotDelegatedError": {
        "type": "object",
        "required": [
          "error",
          "chain",
          "message"
        ],
        "properties": {
          "error": {
            "type": "string",
            "enum": [
              "wallet_not_delegated"
            ]
          },
          "chain": {
            "$ref": "#/components/schemas/Chain"
          },
          "message": {
            "type": "string"
          }
        },
        "additionalProperties": false,
        "description": "A `chain`-pinned `priority: \"speed\"` + `execution: \"user_operation\"` request whose `eth_wallet` carries code on that chain other than an EIP-7702 delegation to Alchemy Modular Account v2 (a wallet with no code is quoted: it delegates in its first operation through `eip7702Auth`). Only the caller can clear it (re-delegate to Modular Account v2, then re-quote), or re-quote with `execution: \"transaction\"` for the raw-transaction shape."
      },
      "OwnershipProof": {
        "type": "object",
        "required": [
          "issued_at"
        ],
        "properties": {
          "sol_signature": {
            "type": "string",
            "description": "Base64 raw Ed25519 signature over the canonical challenge. Required\nwhen `sol_wallet` is present in the same request.\n",
            "minLength": 1,
            "maxLength": 150
          },
          "eth_signature": {
            "type": "string",
            "description": "`0x`-prefixed 65-byte EIP-191 `personal_sign` signature. Required when\n`eth_wallet` is present in the same request.\n",
            "minLength": 1,
            "maxLength": 150
          },
          "issued_at": {
            "type": "integer",
            "description": "Unix seconds. Server accepts up to **300 s past / 30 s future**;\noutside that window → `401 ownership_proof_skewed`.\n"
          }
        },
        "additionalProperties": false
      },
      "StockProtocolListing": {
        "type": "object",
        "required": [
          "sol_address",
          "eth_address",
          "share_multiplier",
          "token_ticker"
        ],
        "properties": {
          "sol_address": {
            "type": [
              "string",
              "null"
            ]
          },
          "eth_address": {
            "type": [
              "string",
              "null"
            ]
          },
          "bnb_address": {
            "type": [
              "string",
              "null"
            ],
            "description": "Token address on BNB Smart Chain (56), Ondo's and xStocks' third deployment. **Optional, and absent (not null) while the bnb venue is closed**: the key itself is withheld, so the block is byte-identical to its pre-bnb shape. `null` while the key IS present means the usual thing: this protocol does not list this ticker on 56. Treat \"absent\" and \"null\" identically; do not branch on the difference. Never present on the `backpack` block.\n"
          },
          "share_multiplier": {
            "type": [
              "string",
              "null"
            ]
          },
          "sol_min_trade_size_usd": {
            "type": "integer",
            "description": "Per-cell measured minimum for this protocol on Solana, in whole USDC.\nSame semantics as the ticker-level `min_trade_size_usd`: **absent means\nno minimum is known**, never zero, and it is advisory rather than a gate.\nPresent only when the probe has measured this specific cell recently.\n\n**Firm, taker-bound:** on a cell a market maker fills, each size is\nasked as a quote bound to a funded wallet, so the minimum is a size a\nmarket maker quoted to fill for a funded taker, not a price-only\npreview (a pool-priced cell's quote is binding already). Until a cell\nhas been measured this way it may keep its earlier figure for a\ntransition period.\n\nMarket makers' own minimums move by day, so a smaller order may still be\nrefused; the refusal then names a size in `min_notional_usdc`. A position\nworth less than this may not be sellable on Solana until it is topped up,\nso avoid partial sells that leave less than it behind.\n"
          },
          "eth_min_trade_size_usd": {
            "type": "integer",
            "description": "Per-cell measured minimum for this protocol on Ethereum. Same presence and advisory semantics as `sol_min_trade_size_usd`, but measured from price quotes for an unfunded wallet, so it is an estimate rather than a firm one.\n"
          },
          "bnb_min_trade_size_usd": {
            "type": "integer",
            "description": "Per-cell minimum for this protocol on BNB Smart Chain (56): measured, or the venue's own floor where it is known before measurement, whichever is higher. Measured like `eth_min_trade_size_usd`. Rides the same conditional as `bnb_address`: always absent while the bnb venue is closed, and while this protocol has no 56 deployment for the ticker.\n"
          },
          "sol_tradability": {
            "$ref": "#/components/schemas/Tradability",
            "description": "Per-cell probe warning for this protocol on Solana. `thin`: the cell fills, but not at every size below `sol_min_trade_size_usd`. `untradable`: nothing filled at any size across a full measurement window, and no minimum accompanies it. **Neither value disables the cell**; quotes are still accepted for both. Absent means unmeasured or unwarned, never healthy-with-value-null. Chain-suffixed because this block spans a Solana and an Ethereum cell.\n"
          },
          "sol_warn_reason": {
            "$ref": "#/components/schemas/WarnReason",
            "description": "Why the Solana cell is warned, strongest evidence first. Absent when unwarned, or when the warn predates reason recording. Not stable over a cell's lifetime: a `low_volume` warn that later kills a real order flips to `settlement_failure`.\n"
          },
          "sol_thin_since": {
            "$ref": "#/components/schemas/ThinSince",
            "description": "When the Solana warning was first raised. Present exactly when `sol_tradability` is."
          },
          "eth_tradability": {
            "$ref": "#/components/schemas/Tradability",
            "description": "Per-cell probe warning for this protocol on Ethereum. See `sol_tradability`."
          },
          "eth_warn_reason": {
            "$ref": "#/components/schemas/WarnReason",
            "description": "Why the Ethereum cell is warned, strongest evidence first. See `sol_warn_reason`."
          },
          "eth_thin_since": {
            "$ref": "#/components/schemas/ThinSince",
            "description": "When the Ethereum warning was first raised. Present exactly when `eth_tradability` is."
          },
          "token_ticker": {
            "type": [
              "string",
              "null"
            ],
            "description": "Issuer's wrapped-token symbol (`<TICKER>on` Ondo, `<TICKER>x` xStocks). Null when not listed."
          }
        }
      },
      "RobinhoodListing": {
        "type": "object",
        "description": "Robinhood Chain (4663) venue listing. Single-chain, so one `address` instead of the sol/eth pair; token decimals stay internal.\n",
        "required": [
          "address",
          "share_multiplier",
          "token_ticker"
        ],
        "properties": {
          "address": {
            "type": [
              "string",
              "null"
            ]
          },
          "share_multiplier": {
            "type": [
              "string",
              "null"
            ]
          },
          "min_trade_size_usd": {
            "type": "integer",
            "description": "Measured minimum for this single-cell venue, in whole USDC. **Absent means no minimum is known**, never zero, and it is advisory rather than a gate.\n"
          },
          "tradability": {
            "$ref": "#/components/schemas/Tradability",
            "description": "Probe warning for this single-cell venue. `thin`: the cell fills, but not at every size below `min_trade_size_usd`. `untradable`: nothing filled at any size across a full measurement window, and no minimum accompanies it. **Neither value disables the cell**; quotes are still accepted for both. Absent means unmeasured or unwarned, never healthy-with-value-null. Bare rather than chain-suffixed: this block names exactly one cell.\n"
          },
          "warn_reason": {
            "$ref": "#/components/schemas/WarnReason",
            "description": "Why the cell is warned, strongest evidence first. Absent when unwarned, or when the warn predates reason recording. Not stable over a cell's lifetime: a `low_volume` warn that later kills a real order flips to `settlement_failure`.\n"
          },
          "thin_since": {
            "$ref": "#/components/schemas/ThinSince"
          },
          "token_ticker": {
            "type": [
              "string",
              "null"
            ],
            "description": "Bare stock symbol (Robinhood Stock Tokens carry no on/x suffix). Null when not listed."
          }
        }
      },
      "TradfiBlock": {
        "type": "object",
        "required": [
          "current_price_usd",
          "currency",
          "price_native",
          "change_24h_pct",
          "market_cap_usd",
          "pe_ttm",
          "volume_shares",
          "volume_1d_usd",
          "as_of"
        ],
        "properties": {
          "current_price_usd": {
            "$ref": "#/components/schemas/DecimalString"
          },
          "currency": {
            "type": "string",
            "description": "ISO-4217 quote currency of the underlying listing, \"USD\" for every US row. Every other price on this block is already converted to USD."
          },
          "price_native": {
            "allOf": [
              {
                "$ref": "#/components/schemas/DecimalString"
              }
            ],
            "description": "The price as the exchange quotes it, before conversion, so a client can render e.g. HK$446.20 without re-deriving it. Equal to current_price_usd when currency is \"USD\"."
          },
          "change_24h_pct": {
            "allOf": [
              {
                "$ref": "#/components/schemas/DecimalString"
              }
            ],
            "description": "Percent change in the LISTING's own currency, not converted; a ratio does not convert, and doing it correctly would need yesterday's FX rate."
          },
          "market_cap_usd": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/DecimalString"
              },
              {
                "type": "null"
              }
            ],
            "description": "Null when the feed serves the line without a market cap (funds, newly listed board codes). Converted to USD like every other price here."
          },
          "pe_ttm": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/DecimalString"
              },
              {
                "type": "null"
              }
            ]
          },
          "volume_shares": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/DecimalString"
              },
              {
                "type": "null"
              }
            ],
            "description": "Shares traded in the current session, not a trailing average and not USD (contrast onchain volume_24h_usd). Null when the feed omits it."
          },
          "volume_1d_usd": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/DecimalString"
              },
              {
                "type": "null"
              }
            ],
            "description": "Session dollar volume, volume_shares × current_price_usd, rounded to whole dollars, so it is directly comparable to the onchain volume_24h_usd. Null exactly when volume_shares is null."
          },
          "as_of": {
            "type": "integer",
            "description": "Exchange-side last-tick timestamp (unix seconds)."
          }
        }
      },
      "AnchorSource": {
        "description": "Which reference a premium_vs_anchor_pct was measured against, the live regular-session print, the aftermarket print while it is still printing, or the frozen regular-session close. Never the on-chain mark - the premium measures an on-chain price, so anchoring it there would measure that price against itself.",
        "type": "string",
        "enum": [
          "tradfi_live",
          "tradfi_extended",
          "tradfi_frozen"
        ]
      },
      "StockOnchainAggregate": {
        "type": "object",
        "required": [
          "avg_share_price_usd",
          "premium_vs_tradfi_pct",
          "premium_vs_anchor_pct",
          "volume_24h_usd"
        ],
        "properties": {
          "avg_share_price_usd": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/DecimalString"
              },
              {
                "type": "null"
              }
            ]
          },
          "premium_vs_tradfi_pct": {
            "deprecated": true,
            "description": "DEPRECATED - measured against tradfi.current_price_usd, which freezes at the regular-session close, so it overstates the premium overnight and at weekends. Use premium_vs_anchor_pct, which names the reference it used.",
            "oneOf": [
              {
                "$ref": "#/components/schemas/DecimalString"
              },
              {
                "type": "null"
              }
            ]
          },
          "premium_vs_anchor_pct": {
            "description": "Signed percent of avg_share_price_usd against the anchor named by anchor_source. Null when no tradfi reference resolves at all, in which case anchor_source is absent.",
            "oneOf": [
              {
                "$ref": "#/components/schemas/DecimalString"
              },
              {
                "type": "null"
              }
            ]
          },
          "anchor_source": {
            "$ref": "#/components/schemas/AnchorSource"
          },
          "volume_24h_usd": {
            "$ref": "#/components/schemas/DecimalString"
          }
        }
      },
      "StockOnchainProtocolLeg": {
        "type": "object",
        "required": [
          "share_price_usd",
          "premium_vs_tradfi_pct",
          "premium_vs_anchor_pct",
          "volume_24h_usd"
        ],
        "properties": {
          "share_price_usd": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/DecimalString"
              },
              {
                "type": "null"
              }
            ]
          },
          "premium_vs_tradfi_pct": {
            "deprecated": true,
            "description": "DEPRECATED - see StockOnchainAggregate.premium_vs_tradfi_pct.",
            "oneOf": [
              {
                "$ref": "#/components/schemas/DecimalString"
              },
              {
                "type": "null"
              }
            ]
          },
          "premium_vs_anchor_pct": {
            "description": "Signed percent of share_price_usd against the anchor named by anchor_source. Null when no tradfi reference resolves at all, in which case anchor_source is absent.",
            "oneOf": [
              {
                "$ref": "#/components/schemas/DecimalString"
              },
              {
                "type": "null"
              }
            ]
          },
          "anchor_source": {
            "$ref": "#/components/schemas/AnchorSource"
          },
          "volume_24h_usd": {
            "$ref": "#/components/schemas/DecimalString"
          }
        }
      },
      "StockOnchainPerProtocol": {
        "type": "object",
        "required": [
          "ondo",
          "xstocks",
          "robinhood",
          "coinbase"
        ],
        "properties": {
          "ondo": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/StockOnchainProtocolLeg"
              },
              {
                "type": "null"
              }
            ]
          },
          "xstocks": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/StockOnchainProtocolLeg"
              },
              {
                "type": "null"
              }
            ]
          },
          "robinhood": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/StockOnchainProtocolLeg"
              },
              {
                "type": "null"
              }
            ]
          },
          "coinbase": {
            "description": "Coinbase B20 on Base (8453). Carries the same supply gate as the listing: an unminted cell prices `null`.",
            "oneOf": [
              {
                "$ref": "#/components/schemas/StockOnchainProtocolLeg"
              },
              {
                "type": "null"
              }
            ]
          },
          "bstocks": {
            "description": "bStocks on BNB Smart Chain (56). Carries the same supply gate as the listing: an unminted cell prices `null`.\n**Optional, and absent (not null) while bStocks is not offered** (the bnb venue or bStocks switched off): the same key-dark contract as `bnb_address` on the listing blocks. When present it is emitted last.",
            "oneOf": [
              {
                "$ref": "#/components/schemas/StockOnchainProtocolLeg"
              },
              {
                "type": "null"
              }
            ]
          }
        }
      },
      "StockTickerItem": {
        "type": "object",
        "required": [
          "ticker",
          "name",
          "available_chains",
          "ondo",
          "xstocks",
          "robinhood",
          "coinbase",
          "reality"
        ],
        "properties": {
          "ticker": {
            "$ref": "#/components/schemas/Ticker"
          },
          "name": {
            "type": "string"
          },
          "available_chains": {
            "description": "Chains with at least one listed cell. A ticker no venue lists a cell for (every token unminted, say) is not served at all, by this endpoint or any other stocks read.",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Chain"
            }
          },
          "min_trade_size_usd": {
            "type": "integer",
            "description": "Smallest order size, in whole USDC, we have measured filling for this\nticker on any venue (the cheapest across cells, since a buy routes to\nwhichever cell can serve it).\n\n**Absent means no minimum is known**, not that there is none: the\nlisting has not been measured recently enough to say. Fall back to the\n$3 product floor. Never treat an absent field as `0`.\n\nAdvisory. A quote below this is still accepted and still goes to the\nvenue; it is simply likely to be refused. Measured in-session, and\npublished unchanged outside it as a valid lower bound; off-session\nminimums are higher, never lower.\n"
          },
          "tradability": {
            "$ref": "#/components/schemas/Tradability",
            "description": "Ticker-level roll-up of the per-cell warnings below. Present only when\n**every** measured cell for this ticker is warned, not when any one is.\nA ticker with one healthy measured cell is healthy somewhere and carries\nnothing, so a single dead venue can never label a live listing.\n\nThe word follows the cheapest floor, exactly as it does per cell. `thin`:\nevery measured cell is warned and `min_trade_size_usd` is published\nalongside. `untradable`: every measured cell is warned and none filled\nat any size, so no minimum accompanies it. Cells the probe has not\nmeasured are not counted either way, so `untradable` is a statement about\nthe measured surface, not proof that no venue can fill.\n\n**Neither value means the listing is disabled.** Quotes are still\naccepted for both; this is guidance to show a user before they try,\nnot a gate.\n"
          },
          "warn_reason": {
            "$ref": "#/components/schemas/WarnReason",
            "description": "Why the ticker is warned, strongest evidence first: a real order that\nterminally expired, then the venue stating it holds no price for the\npair, then a full window of quiet auctions with no fill, then no\nvalue-bearing on-chain settlement in the census window, then a\nlow-volume proxy.\n\nPresent only alongside `tradability`; absent when the warn predates\nreason recording; that is \"reason not recorded\", never \"no reason\".\nRolled up as the **strongest** reason across the warned cells, not the\ncheapest cell's, and not stable over a listing's lifetime: the value\nchanges when stronger evidence arrives. Read the per-cell\n`sol_warn_reason` / `eth_warn_reason` / `warn_reason` on the venue\nblocks below before committing to a cell.\n\nThere is no ticker-level `thin_since`: one stamp cannot date several\ncells' warnings; take it per cell.\n"
          },
          "ondo": {
            "$ref": "#/components/schemas/StockProtocolListing"
          },
          "xstocks": {
            "$ref": "#/components/schemas/StockProtocolListing"
          },
          "robinhood": {
            "$ref": "#/components/schemas/RobinhoodListing"
          },
          "coinbase": {
            "$ref": "#/components/schemas/CoinbaseListing"
          },
          "reality": {
            "$ref": "#/components/schemas/RealityListing"
          },
          "backpack": {
            "$ref": "#/components/schemas/BackpackListing"
          },
          "bstocks": {
            "$ref": "#/components/schemas/BstocksListing"
          }
        }
      },
      "BstocksListing": {
        "type": "object",
        "description": "bStocks venue listing on BNB Smart Chain (56). Single-chain, so one `address` instead of\nthe sol/eth pair; token decimals stay internal.\n\n**The whole block is OPTIONAL and is ABSENT while bStocks is not offered** (the bnb venue\nor bStocks switched off), not present-with-nulls. bStocks lists on no other chain, so a\ndark venue leaves nothing for the block to describe. This is the same key-dark rule as\n`bnb_address` on the ondo/xstocks blocks and `onchain.bstocks` on `/stocks/prices`.\n\n**Supply-gated**, exactly like `CoinbaseListing`: a cell stays hidden until real supply\nexists. `address` and `token_ticker` are `null`, `bnb` is not added to `available_chains`\non its account, and a quote returns `422 no_routes`. `min_trade_size_usd` and the warn trio\n(`tradability`, `warn_reason`, `thin_since`) are gated with them, so a hidden cell never\npublishes a minimum or a warning for a venue the same response says does not exist.\n\n**Listing is not tradeability here.** Many minted, priced bStocks cells carry no price\nfeed at the execution venue and refuse permanently (`422 no_routes`,\n`reason: \"no_price_feed\"`). Read `tradability` / `min_trade_size_usd` before quoting.\n",
        "required": [
          "address",
          "share_multiplier",
          "token_ticker"
        ],
        "properties": {
          "address": {
            "type": [
              "string",
              "null"
            ]
          },
          "share_multiplier": {
            "type": [
              "string",
              "null"
            ],
            "description": "Shares per token, read live on chain each catalog refresh from the token's own scaled-UI-amount multiplier (ERC-8056 as adopted for BEP-20 by BEP-677). Not a static 1:1: it moves on splits and dividends.\n"
          },
          "min_trade_size_usd": {
            "type": "integer",
            "description": "Measured minimum for this single-cell venue, in whole USDC. **Absent means no minimum is known**, never zero, and it is advisory rather than a gate.\n"
          },
          "tradability": {
            "$ref": "#/components/schemas/Tradability",
            "description": "Probe warning for this cell. See `CoinbaseListing.tradability`."
          },
          "warn_reason": {
            "$ref": "#/components/schemas/WarnReason",
            "description": "Why the cell is warned. See `CoinbaseListing.warn_reason`."
          },
          "thin_since": {
            "$ref": "#/components/schemas/ThinSince"
          },
          "token_ticker": {
            "type": [
              "string",
              "null"
            ],
            "description": "Issuer's token symbol (`<TICKER>B`, e.g. `TSLAB`; a share class drops its dot, so `BRK.B` is `BRKBB`). Null when not listed."
          }
        }
      },
      "BackpackListing": {
        "description": "Backpack Securities venue listing on Solana. Same shape as the `ondo` and `xstocks` blocks;\nBackpack deploys on Solana only, so `eth_address` is always `null` and the `eth_*` fields\nnever appear.\n\n**Optional, and absent while the venue is not offered.** When the key is present, a cell is\nlisted only once its token has real supply: until then `sol_address` and `token_ticker` are\n`null`, `sol` is not added to `available_chains` on its account, and\n`sol_min_trade_size_usd` and the `sol_` warn trio are gated with them. A ticker only this\nvenue carries is not served at all while its cell is unlisted. `token_ticker` is the bare\nstock symbol (Backpack tokens carry no on/x suffix).\n",
        "allOf": [
          {
            "$ref": "#/components/schemas/StockProtocolListing"
          }
        ]
      },
      "CoinbaseListing": {
        "type": "object",
        "description": "Coinbase B20 venue listing on Base (8453). Single-chain, so one `address`\ninstead of the sol/eth pair; token decimals stay internal.\n\n**Supply-gated.** Coinbase deployed its B20 tokens unminted, and a cell stays\nhidden until real supply exists: `address` and `token_ticker` are `null`, `base`\nis omitted from `available_chains`, and a quote returns `422 no_routes`. The\nlisted set therefore grows over time; read this endpoint rather than hardcoding.\n`min_trade_size_usd` and the warn trio (`tradability`, `warn_reason`,\n`thin_since`) are gated with them, so a hidden cell never publishes a minimum\nor a warning for a venue the same response says does not exist.\n",
        "required": [
          "address",
          "share_multiplier",
          "token_ticker"
        ],
        "properties": {
          "address": {
            "type": [
              "string",
              "null"
            ]
          },
          "share_multiplier": {
            "type": [
              "string",
              "null"
            ]
          },
          "min_trade_size_usd": {
            "type": "integer",
            "description": "Measured minimum for this single-cell venue, in whole USDC. **Absent means no minimum is known**, never zero, and it is advisory rather than a gate.\n"
          },
          "tradability": {
            "$ref": "#/components/schemas/Tradability",
            "description": "Probe warning for this single-cell venue. `thin`: the cell fills, but not at every size below `min_trade_size_usd`. `untradable`: nothing filled at any size across a full measurement window, and no minimum accompanies it. **Neither value disables the cell**; quotes are still accepted for both. Absent means unmeasured or unwarned, never healthy-with-value-null. Bare rather than chain-suffixed: this block names exactly one cell.\n"
          },
          "warn_reason": {
            "$ref": "#/components/schemas/WarnReason",
            "description": "Why the cell is warned, strongest evidence first. Absent when unwarned, or when the warn predates reason recording. Not stable over a cell's lifetime: a `low_volume` warn that later kills a real order flips to `settlement_failure`.\n"
          },
          "thin_since": {
            "$ref": "#/components/schemas/ThinSince"
          },
          "token_ticker": {
            "type": [
              "string",
              "null"
            ],
            "description": "Bare stock symbol (B20 tokens carry no on/x suffix). Null when not listed."
          }
        }
      },
      "RealityListing": {
        "type": "object",
        "description": "Reality rToken venue listing on Arbitrum One (42161). Single-chain, so one `address`\ninstead of the sol/eth pair; token decimals stay internal.\n\n**Supply-gated, like `coinbase`, PLUS the venue kill switch.** A cell stays hidden while\neither gate is closed: `address` and `token_ticker` are `null`, `arbitrum` is omitted from\n`available_chains`, and a quote returns `422 no_routes`. The listed set therefore grows\nover time; read this endpoint rather than hardcoding. `min_trade_size_usd` and the warn\ntrio (`tradability`, `warn_reason`, `thin_since`) are gated with them, so a hidden cell\nnever publishes a minimum or a warning for a venue the same response says does not exist.\n",
        "required": [
          "address",
          "share_multiplier",
          "token_ticker"
        ],
        "properties": {
          "address": {
            "type": [
              "string",
              "null"
            ]
          },
          "share_multiplier": {
            "type": [
              "string",
              "null"
            ]
          },
          "min_trade_size_usd": {
            "type": "integer",
            "description": "Measured minimum for this single-cell venue, in whole USDC. **Absent means no minimum is known**, never zero, and it is advisory rather than a gate.\n"
          },
          "tradability": {
            "$ref": "#/components/schemas/Tradability",
            "description": "Probe warning for this single-cell venue. `thin`: the cell fills, but not at every size below `min_trade_size_usd`. `untradable`: nothing filled at any size across a full measurement window, and no minimum accompanies it. **Neither value disables the cell**; quotes are still accepted for both. Absent means unmeasured or unwarned, never healthy-with-value-null. Bare rather than chain-suffixed: this block names exactly one cell.\n"
          },
          "warn_reason": {
            "$ref": "#/components/schemas/WarnReason",
            "description": "Why the cell is warned, strongest evidence first. Absent when unwarned, or when the warn predates reason recording. Not stable over a cell's lifetime: a `low_volume` warn that later kills a real order flips to `settlement_failure`.\n"
          },
          "thin_since": {
            "$ref": "#/components/schemas/ThinSince"
          },
          "token_ticker": {
            "type": [
              "string",
              "null"
            ],
            "description": "Bare stock symbol (rTokens carry no on/x suffix). Null when not listed."
          }
        }
      },
      "StockListItem": {
        "allOf": [
          {
            "$ref": "#/components/schemas/StockTickerItem"
          },
          {
            "type": "object",
            "required": [
              "tradfi",
              "onchain"
            ],
            "properties": {
              "tradfi": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/TradfiBlock"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "onchain": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/StockOnchainAggregate"
                  },
                  {
                    "type": "null"
                  }
                ]
              }
            }
          }
        ]
      },
      "StockPriceItem": {
        "type": "object",
        "required": [
          "ticker",
          "tradfi",
          "onchain"
        ],
        "properties": {
          "ticker": {
            "$ref": "#/components/schemas/Ticker"
          },
          "tradfi": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/TradfiBlock"
              },
              {
                "type": "null"
              }
            ]
          },
          "onchain": {
            "$ref": "#/components/schemas/StockOnchainPerProtocol"
          }
        }
      },
      "StockExchange": {
        "type": "string",
        "description": "The listing venue a stock trades on, and the source of `exchange_country` and `data_delay`. Deliberately not the full exchange universe: it enumerates the venues this catalog serves, and grows without a breaking change; treat an unlisted value as a new venue, not an error.",
        "enum": [
          "NASDAQ",
          "NYSE",
          "AMEX",
          "CBOE",
          "HKSE"
        ]
      },
      "StockDataDelay": {
        "type": "string",
        "description": "How fresh the TradFi tape for this venue is. `realtime` is the live quote; `delayed_15m` means every price on the item, including `tradfi`, trails the market by about 15 minutes and must be labelled as delayed wherever it is shown.",
        "enum": [
          "realtime",
          "delayed_15m"
        ]
      },
      "StockDetailListing": {
        "type": "object",
        "description": "One real (protocol, chain, address) token deployment for this ticker: the tuple you forward to the quote routes as `protocol` + `chain`. Combos the ticker does not list are simply absent, and a supply-gated `coinbase`, `reality` or `backpack` cell publishes no entry at all until its token is minted (`backpack` additionally stays absent while that venue is switched off). Token decimals stay internal; read them on-chain.\n",
        "required": [
          "protocol",
          "chain",
          "address",
          "share_multiplier",
          "token_ticker"
        ],
        "properties": {
          "protocol": {
            "$ref": "#/components/schemas/Protocol"
          },
          "chain": {
            "$ref": "#/components/schemas/Chain"
          },
          "address": {
            "type": "string"
          },
          "share_multiplier": {
            "type": [
              "string",
              "null"
            ]
          },
          "token_ticker": {
            "type": "string"
          },
          "min_trade_size_usd": {
            "type": "integer",
            "description": "Smallest order size, in whole USDC, measured filling on THIS cell, or the venue's own floor where it is known before measurement, whichever is higher. **Absent means no minimum is known**, never zero, and it is advisory rather than a gate.\n"
          },
          "tradability": {
            "$ref": "#/components/schemas/Tradability",
            "description": "Probe warning for this one cell. `thin`: the cell fills, but not at every size below `min_trade_size_usd`. `untradable`: nothing filled at any size across a full measurement window, and no minimum accompanies it. **Neither value disables the cell**; quotes are still accepted for both. Absent means unmeasured or unwarned, never healthy-with-value-null.\n"
          },
          "warn_reason": {
            "$ref": "#/components/schemas/WarnReason",
            "description": "Why the cell is warned, strongest evidence first. Absent when unwarned, or when the warn predates reason recording. Not stable over a cell's lifetime: a `low_volume` warn that later kills a real order flips to `settlement_failure`.\n"
          },
          "thin_since": {
            "$ref": "#/components/schemas/ThinSince"
          }
        }
      },
      "ExtendedHoursBlock": {
        "type": "object",
        "description": "Last pre/post-market print: a sibling of `tradfi`, never a substitute for it, whose fields all stay anchored to the regular session. Null whenever no honest value exists: during the regular session (the feed is stale then), when the ticker has no extended print, when `tradfi` is null (no anchor for the change), or when the print is not newer than `tradfi.as_of`. The feed prints only inside 04:00–20:00 ET and then holds its last value, so overnight and at weekends this stays populated with the final post-market print; label staleness off `as_of` rather than assuming it is live.",
        "required": [
          "price_usd",
          "change_usd",
          "change_pct",
          "session",
          "as_of"
        ],
        "properties": {
          "price_usd": {
            "$ref": "#/components/schemas/DecimalString"
          },
          "change_usd": {
            "type": "string",
            "description": "price_usd − tradfi.current_price_usd. May be negative."
          },
          "change_pct": {
            "type": "string",
            "description": "The same difference in percent, against the regular-session close. May be negative."
          },
          "session": {
            "type": "string",
            "description": "Which extended window this print came from, independent of `market_session`. Overnight `market_session` is `closed` while this stays `post`.",
            "enum": [
              "pre",
              "post"
            ]
          },
          "as_of": {
            "type": "integer",
            "description": "Timestamp of the extended print (unix seconds)."
          }
        }
      },
      "AnalystRating": {
        "type": "object",
        "required": [
          "rating",
          "target_price_usd"
        ],
        "properties": {
          "rating": {
            "type": [
              "string",
              "null"
            ],
            "description": "Consensus label (e.g. \"Buy\")."
          },
          "target_price_usd": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "AnalystGrade": {
        "type": "object",
        "required": [
          "firm",
          "grade",
          "action",
          "date"
        ],
        "properties": {
          "firm": {
            "type": "string"
          },
          "grade": {
            "type": "string",
            "description": "Raw grade text (e.g. \"Overweight\")."
          },
          "action": {
            "type": "string",
            "enum": [
              "buy",
              "hold",
              "sell"
            ]
          },
          "date": {
            "type": "string",
            "description": "ISO `YYYY-MM-DD`."
          }
        }
      },
      "NextEarnings": {
        "type": "object",
        "description": "The ticker's nearest scheduled report inside a 30-day horizon. The block is null when no report falls in that window (or when the calendar read faulted), never a farther date.",
        "required": [
          "next_date",
          "eps_estimate"
        ],
        "properties": {
          "next_date": {
            "type": "string",
            "description": "ISO `YYYY-MM-DD`."
          },
          "eps_estimate": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/DecimalString"
              },
              {
                "type": "null"
              }
            ],
            "description": "Consensus EPS estimate. Null when none is published for the report."
          }
        }
      },
      "NewsItem": {
        "type": "object",
        "description": "One stored headline for this ticker, newest first, at most 10 per response. There is no image field: the vendor's image host is not part of this plane's shape.",
        "required": [
          "title",
          "url",
          "publisher",
          "published_at",
          "type",
          "snippet"
        ],
        "properties": {
          "title": {
            "type": "string"
          },
          "url": {
            "type": [
              "string",
              "null"
            ]
          },
          "publisher": {
            "type": [
              "string",
              "null"
            ],
            "description": "The news outlet that published the story."
          },
          "published_at": {
            "type": "string",
            "format": "date-time",
            "description": "ISO-8601 UTC."
          },
          "type": {
            "type": "string",
            "description": "Story class; `stock` for a symbol-scoped story, `press_release` for an issuer release. Open vocabulary: a value you do not recognise is a new class, not a schema violation."
          },
          "snippet": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "StockDetailResponse": {
        "type": "object",
        "description": "Everything the catalog knows about one ticker.\n\nEvery block backed by I/O is fault-isolated and degrades to `null` on its own, so any block\ncan be null because its fetch failed. For `tradfi`, `extended_hours`, `analyst`,\n`analyst_grades` and `earnings`, null **also** means \"no such value exists for this ticker\nright now\", no coverage, no scheduled report, no extended print, no priced reference, and\nthe two causes are not distinguishable from the response; read each field's own\ndescription for what its null covers.\n\n`news` is the one block that separates them: `[]` means we hold no headlines, `null` means\nthe read failed, so it is the only one worth re-reading on an empty answer.\n\nThere is deliberately no `onchain` block: per-protocol on-chain prices live on\n`GET /stocks/prices`.\n",
        "required": [
          "ticker",
          "name",
          "description",
          "sector",
          "industry",
          "website",
          "logo_url",
          "available_chains",
          "listings",
          "tradfi",
          "extended_hours",
          "market_session",
          "is_holiday",
          "holiday_name",
          "analyst",
          "analyst_grades",
          "earnings",
          "news"
        ],
        "properties": {
          "ticker": {
            "$ref": "#/components/schemas/Ticker"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": [
              "string",
              "null"
            ],
            "description": "Company/asset description. Null when none is stored for this ticker; it is refreshed on the catalog's own recheck cadence, not on your read."
          },
          "sector": {
            "type": [
              "string",
              "null"
            ]
          },
          "industry": {
            "type": [
              "string",
              "null"
            ]
          },
          "website": {
            "type": [
              "string",
              "null"
            ]
          },
          "logo_url": {
            "type": [
              "string",
              "null"
            ],
            "description": "Absolute `https` URL of the company logo, served from Treasures' own object store rather than the upstream source. Null when no logo has been mirrored for this ticker."
          },
          "available_chains": {
            "description": "Chains with at least one listed cell. A ticker no venue lists a cell for (every token unminted, say) is not served at all, by this endpoint or any other stocks read.",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Chain"
            }
          },
          "exchange": {
            "$ref": "#/components/schemas/StockExchange",
            "description": "The venue this stock lists on. **Absent** (never null) when we have not resolved one, so treat \"no key\" as unknown rather than as a US listing. Present together with `exchange_country` and `data_delay` or not at all."
          },
          "exchange_country": {
            "type": "string",
            "description": "ISO-3166 alpha-2 country of the **exchange**, not of the issuer. Tencent lists in `HK` while its issuer country is CN; do not read this as domicile. Derived from `exchange`, so it is absent whenever `exchange` is."
          },
          "data_delay": {
            "$ref": "#/components/schemas/StockDataDelay",
            "description": "Freshness class of this row's TradFi prices, derived from `exchange`. Absent whenever `exchange` is; absent does **not** mean realtime."
          },
          "display_ticker": {
            "type": "string",
            "description": "The ticker as it should be rendered; `0700.HK` for the row keyed `700`. **Absent for a US row**, whose bare `ticker` is already the display form. Render `display_ticker ?? ticker`. Identity stays on `ticker`: every path segment and every other endpoint uses that, never this."
          },
          "listings": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/StockDetailListing"
            }
          },
          "tradfi": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/TradfiBlock"
              },
              {
                "type": "null"
              }
            ],
            "description": "Null when no reference price resolves for the ticker, a basket, or any row the tape does not cover, as well as on a fault."
          },
          "extended_hours": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/ExtendedHoursBlock"
              },
              {
                "type": "null"
              }
            ],
            "description": "Null for the ordinary reasons listed on `ExtendedHoursBlock` (the regular session, no extended print, no `tradfi` anchor, a print no newer than `tradfi.as_of`), as well as on a fault."
          },
          "market_session": {
            "type": [
              "string",
              "null"
            ],
            "description": "Current US-equity session: global, not per-ticker, and holiday/half-day aware. Picks which of `tradfi` / `extended_hours` to render. Null when the session read faulted.",
            "enum": [
              "regular",
              "pre",
              "post",
              "closed",
              null
            ]
          },
          "is_holiday": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "True on a NASDAQ holiday **and on its eve** (an early-close day reports this too, not just the holiday's own date). Null when the session read faulted."
          },
          "holiday_name": {
            "type": [
              "string",
              "null"
            ],
            "description": "Name of the holiday when `is_holiday` is true; null otherwise, and null when the session read faulted."
          },
          "analyst": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/AnalystRating"
              },
              {
                "type": "null"
              }
            ],
            "description": "Consensus rating and price target. Null when no analyst covers the ticker, and null on a fault; the two are not distinguishable here."
          },
          "analyst_grades": {
            "oneOf": [
              {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/AnalystGrade"
                }
              },
              {
                "type": "null"
              }
            ],
            "description": "Latest grade per firm, most recent first, at most 15 firms. Null when no firm covers the ticker, and null on a fault."
          },
          "earnings": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/NextEarnings"
              },
              {
                "type": "null"
              }
            ],
            "description": "Null when no report falls inside the 30-day horizon, and null on a fault."
          },
          "news": {
            "oneOf": [
              {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/NewsItem"
                }
              },
              {
                "type": "null"
              }
            ],
            "description": "Up to 10 stored headlines, newest first. `[]` means we hold none for this ticker; `null` means the read faulted."
          }
        }
      },
      "StocksListResponse": {
        "type": "object",
        "required": [
          "stocks"
        ],
        "properties": {
          "stocks": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/StockListItem"
            }
          },
          "page": {
            "type": "integer",
            "description": "The page served. Present only when the request sent `page`."
          },
          "next_page": {
            "type": [
              "integer",
              "null"
            ],
            "description": "The next page, or null on the last. Present only when the request sent `page`."
          },
          "total": {
            "type": "integer",
            "description": "Rows matching `q` across all pages. Present only when the request sent `page`."
          }
        }
      },
      "StockSortKey": {
        "type": "string",
        "description": "List sort key. All but `ticker` read the `tradfi` block; a stock missing the metric sorts last in both directions, and ties break by ticker.",
        "enum": [
          "market_cap",
          "volume_1d",
          "change_24h",
          "price",
          "pe",
          "ticker"
        ]
      },
      "StocksTickersResponse": {
        "type": "object",
        "required": [
          "tickers"
        ],
        "properties": {
          "tickers": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/StockTickerItem"
            }
          }
        }
      },
      "StockPricesResponse": {
        "type": "object",
        "required": [
          "prices"
        ],
        "properties": {
          "prices": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/StockPriceItem"
            }
          }
        }
      },
      "SignablePayload": {
        "type": "object",
        "required": [
          "type"
        ],
        "discriminator": {
          "propertyName": "type",
          "mapping": {
            "solana_versioned_tx": "#/components/schemas/SignableSolanaTx",
            "evm_eip712_typed_data": "#/components/schemas/SignableEvmTypedData",
            "evm_eip1559_tx": "#/components/schemas/SignableEvmTx",
            "evm_legacy_tx": "#/components/schemas/SignableEvmTx",
            "evm_calls": "#/components/schemas/SignableEvmCalls"
          }
        },
        "oneOf": [
          {
            "$ref": "#/components/schemas/SignableSolanaTx"
          },
          {
            "$ref": "#/components/schemas/SignableEvmTypedData"
          },
          {
            "$ref": "#/components/schemas/SignableEvmTx"
          },
          {
            "$ref": "#/components/schemas/SignableEvmCalls"
          }
        ]
      },
      "SignableSolanaTx": {
        "type": "object",
        "description": "On a `priority:\"speed\"` cross-chain leg whose origin is sol (`origin_chain: \"sol\"`), this\ntransaction's fee payer is your own sol wallet, which is also the deposit's signer: sign it\nas issued, with one signature, and your wallet pays the network fee. To have a sponsor pay\ninstead, recompile the message with the sponsor's key as payer and have it co-sign; your\nsignature is still required. Every account key is static (no address-lookup tables), and\nthe submit-time bind accepts only the quoted deposit plus compute-budget,\ntoken-account-creation and sponsor-paid rent-transfer instructions.\n\nA cross-chain sell leg on `sol` (`payout_chain` present) is signed the same way, with your\nsol wallet as fee payer, but its message uses address-lookup tables, and a sponsor's\nrecompile may reference only those quoted tables. The bind accepts every quoted instruction\nunchanged and in its quoted order, plus at most four extra compute-budget,\ntoken-account-creation and sponsor-paid rent-transfer instructions, and the signed\ntransaction must fit Solana's 1232-byte limit.\n\nOn a same-chain `sol` leg that carries `sol_fee_payer`, the transaction has two required\nsigners, the `sol_fee_payer` (the fee payer) and your sol wallet: both sign it **as\nissued**, and it must never be recompiled.\n\nAny other same-chain `sol` leg is signed by your sol wallet alone.\n",
        "required": [
          "type",
          "tx_base64"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "solana_versioned_tx"
            ]
          },
          "tx_base64": {
            "type": "string",
            "description": "Base64 unsigned Solana `VersionedTransaction`."
          }
        },
        "additionalProperties": false
      },
      "SignableEvmTypedData": {
        "type": "object",
        "description": "EIP-712 typed data for a gasless EVM order: the **default** payload on every EVM leg. eth\n(Ethereum mainnet), robinhood (Robinhood Chain / 4663), base (Base / 8453), arbitrum\n(Arbitrum One / 42161) and bnb (BNB Smart Chain / 56), which all share the same sign-only\nmodel.\n\nExactly one payload per leg; sign it with `eth_signTypedData_v4` and return the signature\nto `/trade/submit`. A resolver settles the signed order on-chain, so the caller broadcasts\nnothing and pays no native gas for the trade. The one on-chain step is the wallet's own\none-time ERC-20 allowance of the spent token to that chain's settlement contract, sent with\nthat chain's native gas.\n\nTwo exceptions carry `SignableEvmTx` instead (a complete transaction, and not gasless):\n\n- a robinhood or base leg under `priority: \"speed\"`\n- a `bnb` + `bstocks` leg at **every** priority (bStocks has no gasless route; you pay BNB\n  gas and Treasures broadcasts).\n\neth, arbitrum and the other bnb cells always carry this shape: eth is never quoted under\n`priority: \"speed\"` at all, and arbitrum (Reality), bnb + `ondo` and bnb + `xstocks` have\nno speed-route alternative to carry instead.\n\n**On a gasless `bnb` leg the signing deadline is much shorter: about 17 seconds**, against\nabout 60 s on eth (the venue's auction starts sooner). The leg's own `expires_at` is that\ndeadline: read it per leg, not off the response's top-level value. Sign a bnb leg\nimmediately; do not batch it behind a human confirmation or a hardware-wallet round trip.\nPast the deadline the order is not dead: the auction is live and still fillable along its\ndecay curve, at a worse price.\n",
        "required": [
          "type",
          "typed_data"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "evm_eip712_typed_data"
            ]
          },
          "typed_data": {
            "type": "object",
            "description": "EIP-712 typed-data object for the gasless EVM order; sign with `eth_signTypedData_v4`.",
            "additionalProperties": true
          },
          "extension": {
            "type": "string",
            "description": "Never sent on `/public/v1`; on `/api/v1/swap` only. The order's extension bytes\n(hex; `0x` when the order has none), relayed with your signature from the server's stored\ncopy, never from you. Read it before signing: when non-empty, the lowest 160 bits of\n`keccak256(extension)` equal the lowest 160 bits of the order's `salt`, and a decoded\n`customReceiver`, if present, is your own wallet.\n",
            "example": "0x"
          }
        },
        "additionalProperties": false
      },
      "SignableEvmTx": {
        "type": "object",
        "description": "A **complete unsigned EVM transaction**. Three producers share this shape.\n\n- **(1)** The speed-route payload, returned on a `priority: \"speed\"` leg (robinhood / base)\n  and on every `bnb` + `bstocks` leg whatever the `priority` (`evm_legacy_tx`, BNB gas):\n  `role` is `\"approve\"` then `\"swap\"`.\n- **(2)** A `priority:\"speed\"` **cross-chain** leg's EVM origin under\n  `execution:\"transaction\"` (`origin_chain` present on the leg): `role` is `\"approve\"` then\n  `\"deposit\"`: the swap happens off-chain via the destination fill, this transaction only\n  moves your stable off the origin chain, and the `approve` is **exact-amount**, not\n  max-uint256 (a deliberate departure from the same-chain speed route's unlimited\n  approval, since this arm targets a bridge depository, not a swap router).\n- **(3)** A **cross-chain sell** leg on `eth`, `base` or `bnb` (`payout_chain` present on\n  the leg): always both payloads, on the leg's own `chain`: an **exact-amount** `approve`\n  of the tokens sold, served every time whatever allowance the wallet already has, then\n  the `deposit`, which sells them on that chain and sends the USDC to `payout_chain`.\n\nEvery field the transaction needs is already in the bytes: `nonce`, `gas` and the fee pair\nare server-completed, so sign `tx_hex` **as-is** with `signTransaction` and return\n`{ type: \"evm_signed_tx\", signed_tx_hex }`; do not re-estimate, re-nonce or re-serialize\nit, and do not broadcast it yourself. Treasures broadcasts the signed bytes; any edited\nfield fails the submit-time bind as `invalid_signature`.\n\n`type` is `evm_eip1559_tx` when the chain reports EIP-1559 fees and `evm_legacy_tx` when it\nreports a flat `gas_price`; the two carry the same fields apart from that pair. The fee\nfields are **mirrors of what is already in `tx_hex`**, present only when the bytes carry\nthem: read them for display, never to rebuild the transaction, and treat an absent one as\n\"this transaction does not set it\" rather than as zero. The wallet must hold native gas on\nthe leg's chain.\n\n**No pre-approval is needed:** when the wallet has not approved the spender yet (and on\nevery cross-chain sell leg), the leg carries **two** payloads: `role: \"approve\"` (nonce n)\nfollowed by `role: \"swap\"` or `role: \"deposit\"` (nonce n+1). Sign and return **both**, in\nthat order. An approved wallet gets the single second payload.\n\nTreasures sends the approve, waits for its receipt, then sends the swap/deposit; the leg's\n`tx_hash` is that second payload's from the start, but it becomes visible on chain only\nafter the approve mines (seconds). Sign each payload as-is: the nonces are consecutive and\na resigned or reordered one fails the bind as `invalid_signature`.\n",
        "required": [
          "type",
          "role",
          "from",
          "tx_hex",
          "tx_base64",
          "approval_spender",
          "chain_id",
          "nonce",
          "gas"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "evm_eip1559_tx",
              "evm_legacy_tx"
            ]
          },
          "role": {
            "type": "string",
            "enum": [
              "approve",
              "swap",
              "deposit"
            ],
            "description": "Which transaction this is.\n\n- `swap` is a same-chain speed-route trade.\n- On a cross-chain buy leg (`origin_chain` present) `deposit` is the off-ramp to the\n  bridge depository, never a swap in itself: the exchange happens on the destination\n  chain.\n- On a cross-chain sell leg (`payout_chain` present) `deposit` sells the stock on the\n  leg's `chain` and sends the USDC to `payout_chain`.\n- `approve` precedes a buy's `deposit` or a `swap` only on a wallet with no allowance to\n  the relevant spender at quote time, and precedes a sell's `deposit` every time:\n  **exact-amount** ahead of a `deposit`, max-uint256 ahead of a `swap`.\n\nBranch on `role`, never on array position, and never sign only `signable_payloads[0]`\nwhen there are two.\n"
          },
          "from": {
            "type": "string",
            "description": "The signing wallet, i.e. the same EVM EOA the quote was bound to."
          },
          "tx_hex": {
            "type": "string",
            "description": "Unsigned RLP transaction, 0x-prefixed. Sign exactly these bytes."
          },
          "tx_base64": {
            "type": "string",
            "description": "The same unsigned transaction as base64, for callers whose signer takes bytes."
          },
          "approval_spender": {
            "type": [
              "string",
              "null"
            ],
            "description": "On the `swap` payload: the on-chain router the swap pulls the spent token through, **on this leg's chain**, informational; the bundled `approve` payload (when present) already targets it. On a `deposit` payload: the contract the `approve` payload grants, informational. `null` on the `approve` payload, which needs no allowance itself."
          },
          "chain_id": {
            "type": "integer",
            "description": "EVM chain id these bytes are signed for."
          },
          "nonce": {
            "type": "integer",
            "description": "Server-read pending nonce, already encoded in `tx_hex` (n on an `approve`, n+1 on the `swap` or `deposit` that follows it). One in-flight speed trade per wallet per chain; a second signed at the same nonce fails as `nonce_conflict`."
          },
          "gas": {
            "allOf": [
              {
                "$ref": "#/components/schemas/DecimalString"
              }
            ],
            "description": "Gas limit, already encoded in the bytes."
          },
          "max_fee_per_gas": {
            "allOf": [
              {
                "$ref": "#/components/schemas/DecimalString"
              }
            ],
            "description": "EIP-1559 only, never with `gas_price`. Optional: present exactly when `tx_hex` sets it."
          },
          "max_priority_fee_per_gas": {
            "allOf": [
              {
                "$ref": "#/components/schemas/DecimalString"
              }
            ],
            "description": "EIP-1559 only. Optional and independent of `max_fee_per_gas`: present exactly when `tx_hex` sets it, absent when the transaction carries no priority fee."
          },
          "gas_price": {
            "allOf": [
              {
                "$ref": "#/components/schemas/DecimalString"
              }
            ],
            "description": "Legacy only: sent instead of the 1559 pair, never alongside it. Present exactly when `tx_hex` sets it."
          }
        },
        "additionalProperties": false
      },
      "SignableEvmCalls": {
        "type": "object",
        "description": "The `execution: \"user_operation\"` speed-route leg (base or robinhood): the calls to pack\ninto ONE ERC-4337 v0.7 UserOperation from `sender` (your EIP-7702-delegated Modular\nAccount v2 wallet). Build it yourself (e.g. `@account-kit`):\n\n- `execute(target, value, data)` for a single call, `executeBatch([...])` **in this order**\n  for two\n- sponsor it with your own paymaster (an unsponsored op is refused; the leg is ranked at\n  $0 gas)\n- sign it under `chain_id` and the v0.7 EntryPoint (`entry_point`; informational, the\n  server pins it)\n- return `{ type: \"evm_user_operation\", user_operation }`.\n\nThe server decodes `callData` and binds every call byte-for-byte to these, plus `sender` =\nthe quoted wallet, no `factory` / `factoryData`, zero `value` on every call, and a\nnon-empty `paymaster`; any mismatch is `invalid_signature`. A wallet with no code on the\nchain delegates in this operation: send its signed EIP-7702 authorization as `eip7702Auth`\nbeside the op (see `SignedEvmUserOperation`). Exactly one per leg.\n\n`approval_spender` is the router the `swap` call pulls through: what the `approve` call,\nwhen present, grants (max-uint256).\n\n**Cross-chain variant** (`priority:\"speed\"` with `origin_chain` present on the leg): the\nSAME wire shape carries a `role:\"deposit\"` call in place of `role:\"swap\"`, `sender` is your\n**origin**-chain wallet (not the destination-leg wallet), and `chain_id` may additionally\nbe `1` (Ethereum mainnet) for an eth-origin leg, a value the same-chain speed route never\nreturns.\n\n**Cross-chain sell variant** (`payout_chain` present on a `/quote/sell` leg): the calls are\nan `role:\"approve\"` of the stock for exactly the amount sold, then a `role:\"deposit\"`;\n`sender` is your `eth_wallet`, `chain_id` the leg's own `chain` (`8453` or `1`), and\n`approval_spender` what the deposit pulls the stock through.\n",
        "required": [
          "type",
          "chain_id",
          "sender",
          "entry_point",
          "approval_spender",
          "calls"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "evm_calls"
            ]
          },
          "chain_id": {
            "type": "integer",
            "enum": [
              1,
              4663,
              8453
            ],
            "description": "The chain to sign and submit the op on:\n\n- `8453` (base) or `4663` (robinhood) on a same-chain `priority:\"speed\"` leg\n- on a cross-chain leg, the chain the deposit is made on, which may also be `1`\n  (Ethereum): an eth-origin buy, or an `eth` sell paying out elsewhere."
          },
          "sender": {
            "$ref": "#/components/schemas/EvmAddress"
          },
          "entry_point": {
            "$ref": "#/components/schemas/EvmAddress"
          },
          "approval_spender": {
            "$ref": "#/components/schemas/EvmAddress"
          },
          "calls": {
            "type": "array",
            "minItems": 1,
            "maxItems": 2,
            "items": {
              "type": "object",
              "required": [
                "role",
                "to",
                "data",
                "value"
              ],
              "properties": {
                "role": {
                  "type": "string",
                  "enum": [
                    "approve",
                    "swap",
                    "deposit"
                  ]
                },
                "to": {
                  "$ref": "#/components/schemas/EvmAddress"
                },
                "data": {
                  "type": "string",
                  "pattern": "^0x[0-9a-fA-F]*$"
                },
                "value": {
                  "type": "string",
                  "enum": [
                    "0"
                  ]
                }
              },
              "additionalProperties": false
            }
          }
        },
        "additionalProperties": false
      },
      "TradfiReference": {
        "type": "object",
        "required": [
          "price_usd",
          "market_status",
          "as_of"
        ],
        "properties": {
          "price_usd": {
            "$ref": "#/components/schemas/DecimalString"
          },
          "market_status": {
            "type": "string",
            "enum": [
              "open",
              "closed"
            ]
          },
          "as_of": {
            "type": "integer",
            "description": "Unix seconds."
          }
        }
      },
      "CostBreakdownBps": {
        "type": "object",
        "description": "Fee + slippage breakdown in basis points, informational. These fees are already deducted from `estimated_output_*` (the net deliverable) and reflected in `price_usdc_per_share`. The deduction is provider-dependent; do NOT reconstruct a gross amount as `estimated_output / (1 − fees)`; use `estimated_output_*` as-is.",
        "required": [
          "treasures_fee_bps",
          "dex_swap_fee_bps",
          "estimated_slippage_bps"
        ],
        "properties": {
          "treasures_fee_bps": {
            "type": "integer",
            "description": "Treasures' own fee, net."
          },
          "dex_swap_fee_bps": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Provider protocol + swap/execution fee. **Null on a cross-chain leg** (`origin_chain` present): the hop's cost is disclosed instead in `cross_chain_cost_bps`/`cross_chain_cost_usdc` on the leg, and a recorded `0` here would claim the venue charged nothing. Always a number on a same-chain leg."
          },
          "integrator_fee_bps": {
            "type": "integer",
            "description": "Your own fee on this leg, net: your configured default, or the `integrator_fee_bps` you sent, stacked into the same on-wire fee as Treasures' and paid out to you. Always emitted; `0` on an anonymous quote or a leg whose venue could not collect it. Not yet in `required`, like `price_impact_bps`, so a strict validator built against an older copy of this spec keeps working."
          },
          "estimated_slippage_bps": {
            "type": "integer",
            "description": "Execution tolerance: how far below the quote a fill may land. This is what `max_slippage_bps` bounds. On Solana it is 0 on a guaranteed-price or exact-orderbook fill; on EVM there is no separate tolerance signal, so it equals `price_impact_bps`."
          },
          "price_impact_bps": {
            "type": "integer",
            "description": "Adverse route price impact: what this size costs against available depth; 0 when favorable or unreported. Informational: it is NOT charged against `max_slippage_bps` on Solana, so a quote may be returned with `price_impact_bps` above your cap. Display it alongside the price. A structurally broken market is still refused, by a separate non-tunable ceiling, as 422 `no_routes` with reason `price_off_reference`, never `slippage_exceeded`, since raising your cap cannot clear it."
          },
          "slippage_vs_tradfi_bps": {
            "type": "integer",
            "description": "Signed; positive = unfavorable to you. Omitted when `tradfi_reference` is null; there was nothing to measure against."
          }
        },
        "additionalProperties": false
      },
      "LegGasless": {
        "type": "boolean",
        "description": "Who pays this leg's gas.\n\n- `true`: a relayed order; you sign, a settlement network broadcasts, you spend no native\n  gas.\n- `false`: a speed-route leg (`priority: \"speed\"`), returned as a complete unsigned\n  transaction you sign and Treasures broadcasts against **your** native balance on that\n  chain. On a cross-chain leg (`origin_chain` present) that is the **origin** chain, not\n  `chain`; a sol-origin cross-chain leg is `false` because your sol wallet pays the SOL\n  network fee. A cross-chain sell leg (`payout_chain` present) is `false` whatever the\n  `priority`: you pay the gas on the leg's own `chain`, where the sale is sent.\n\n  The exception to both is the `execution: \"user_operation\"` lane, where your paymaster\n  pays and any cross-chain leg is `true`. A same-chain `sol` leg carrying `sol_fee_payer`\n  is `false`: no native gas leaves your user's wallet, but your `sol_fee_payer` pays it, so\n  read `false` as \"you or your `sol_fee_payer` pay\".\n\nRides **every** kind of leg, not only speed ones; **absent** where the upstream never\nreported it (some Solana legs), which is not the same claim as `false`; read the payload\n`type` when it matters.\n"
      },
      "LegEstimatedGasUsd": {
        "type": [
          "string",
          "null"
        ],
        "description": "**Speed-route and cross-chain sell legs only** (absent on every relayed leg): the estimated\nUSD cost of the broadcast this leg asks you to fund, and the figure the route ranking\ncharged against this leg. `null` when no USD gas price was available; the leg still ranks,\njust without its gas term, and a `speed_route_unpriced_gas` warning naming this leg's\n`chain` says so.\n\nThat warning does **not** mean the leg fell back: this leg IS a speed-route leg and only its\ngas figure is missing, so price the gas yourself before choosing it over a gasless leg.\n\nOn a cross-chain buy leg it prices the **origin** chain's transactions. A sol-origin or\nuser-operation cross-chain leg carries `null` with no warning: the SOL network fee is\nneither estimated nor ranked, and a user operation's gas is your paymaster's.\n\nA cross-chain sell leg (`payout_chain` present) carries it whatever the `priority`: on `eth`\nor `base` it prices the `approve` and the sale on the leg's `chain` and is what the ranking\ncharges; it is `null`, with no warning, on `sol`, under `execution: \"user_operation\"` (your\npaymaster pays), or when no USD gas price was available.\n\nA same-chain `sol` leg carrying `sol_fee_payer` carries what that sponsor pays: the network\nfees plus the rent of any token account the trade opens for your user's wallet, or `null`\nwhen no USD price for SOL was available. It is not ranked.\n\nAn estimate over a live gas market: the signed transaction bounds what you can actually\nspend, this string does not.\n"
      },
      "LegSolFeePayer": {
        "allOf": [
          {
            "$ref": "#/components/schemas/SolAddress"
          }
        ],
        "description": "**Same-chain `sol` legs quoted with `sol_fee_payer` only.** Echoes the request's `sol_fee_payer` on a leg whose transaction it must co-sign and pay for: sign that leg's `solana_versioned_tx` with both the `sol_fee_payer` and your sol wallet, as issued. Absent on every other leg, including a `sol` leg filled by a market maker, which pays its own fee: sign that one with your sol wallet alone."
      },
      "SolFeePayer": {
        "allOf": [
          {
            "$ref": "#/components/schemas/SolAddress"
          }
        ],
        "description": "A sol wallet you fund that pays the SOL network fees, and the rent of any token account the\ntrade opens, on every same-chain `sol` leg it can. Lets a wallet holding no SOL trade on\n`sol`: without it, such a wallet is refused there with `422 no_routes`. Each `sol` leg is\nthen either a market-maker fill (no `sol_fee_payer` on the leg; the maker pays the fee) or a\nleg carrying `sol_fee_payer`, which this wallet co-signs.\n\nEvery `ondo` leg is a market-maker fill, so this wallet never pays for one: a first buy of\nan `ondo` token opens your user's token account at the user's own cost (about 0.01 SOL), and\na wallet short of it loses the `ondo` leg. Once sent, a `sol` leg that is not a market-maker\nfill is only ever the sponsored one, so a sponsor that cannot pay fails the leg even when\nyour user's wallet holds SOL.\n\nIt must be **one fixed address** that signs from quote to submit: a fee payer whose address\nchanges between the two cannot sign the transaction it was quoted for. Requires `sol_wallet`\nand must differ from it; refused with `quote_only: true`, which has nothing to sponsor.\nNaming it proves nothing about it and grants nothing: the transaction does nothing until it\nsigns. It is screened like your wallets.\n\nA first buy of a token opens your user's token account for roughly 0.0016 to 0.0021 SOL of\nrent, paid by this wallet and kept by your user's wallet, so fund it for rent as well as\nfees: when it cannot cover them, its `sol` legs are refused and the quote reads\n`422 no_routes`. Cross-chain `sol` legs are unaffected. It covers only the quote it rides\non: send it on `/quote/sell` as well, because a sponsored buy does not sponsor the later\nsell of the same position.\n"
      },
      "QuoteBuyLeg": {
        "type": "object",
        "required": [
          "quote_index",
          "chain",
          "protocol",
          "price_usdc_per_share",
          "estimated_output_shares",
          "estimated_output_tokens",
          "cost_breakdown_bps"
        ],
        "properties": {
          "quote_index": {
            "type": "integer",
            "minimum": 0
          },
          "chain": {
            "$ref": "#/components/schemas/Chain"
          },
          "protocol": {
            "$ref": "#/components/schemas/Protocol"
          },
          "price_usdc_per_share": {
            "$ref": "#/components/schemas/DecimalString"
          },
          "estimated_output_shares": {
            "$ref": "#/components/schemas/DecimalString"
          },
          "estimated_output_tokens": {
            "$ref": "#/components/schemas/DecimalString"
          },
          "base_asset": {
            "type": "string",
            "enum": [
              "usdc",
              "usdg"
            ],
            "description": "Base currency the caller spends; `usdc` on sol/eth/base/arbitrum/bnb legs, `usdg` on\nrobinhood legs. Disambiguates the `_usdc`-named fields (`price_usdc_per_share`,\n`amount_usdc`) when the base is USDG, which shares USDC's 6-decimal scale.\n\n**`usdc` is a wire enum, not a fungibility signal**: on `bnb` it is 18-decimal\nBinance-Peg USDC, not a Circle deploy, and converting it to Circle USDC costs roughly 31\nbps in and 7 to 9 bps out. Read `chain` alongside it before treating two legs as the\nsame money.\n\n**On a cross-chain leg (`origin_chain` present) this names the ORIGIN's currency, not\nthe destination cell's**. For example, a robinhood-origin leg into an eth-priced cell\nstill carries `\"usdg\"`, because that is what actually left your wallet.\n"
          },
          "amount_base": {
            "allOf": [
              {
                "$ref": "#/components/schemas/DecimalString"
              }
            ],
            "description": "Base amount spent, human-decimal, as the base-asset alias of `amount_usdc`."
          },
          "expires_at": {
            "type": "integer",
            "description": "Unix seconds: **this leg's** signing deadline, and the one `/trade/submit` enforces when you sign this leg. Expiry is per leg because the venues' auction clocks differ: a `bnb` leg runs about 17 s where an `eth` leg runs about 60 s. The response's top-level `expires_at` is the EARLIEST leg's, safe for any leg but pessimistic for the longer-lived ones, so read this field once you have picked a leg. Omitted on `quote_only` previews and on `POST /quote/preview`."
          },
          "origin_chain": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Chain"
              }
            ],
            "description": "**Present only on a cross-chain leg, and its presence is what marks one**: a\n`priority:\"speed\"` buy for a cell you are not funded on, reaching its destination\nthrough a cross-chain hop. Names the chain your stable actually left (the request's\n`origin_chain` whenever it sent one); `chain` above stays the destination cell (never\nthe origin), consistent with every other field on this leg.\n\n- `eth` (including a `chain:[\"eth\"]` pin), `sol/xstocks`, `sol/backpack`, `bnb/bstocks`,\n  and `base` on an unpinned or multi-chain request are reachable cross-chain\n- a single-chain `base`/`robinhood` pin always routes same-chain\n- `robinhood`, `sol/ondo`, `eth/xstocks`, `bnb/ondo` and `bnb/xstocks` are never\n  cross-chain destinations.\n- `bnb` is a destination only: it is never an `origin_chain`.\n\n`cross_chain_cost_bps` and `cross_chain_cost_usdc` disclose the hop's own cost. Absent on\nevery same-chain leg.\n"
          },
          "cross_chain_cost_bps": {
            "allOf": [
              {
                "$ref": "#/components/schemas/BridgeCostBreakdownBps"
              }
            ],
            "description": "**Cross-chain legs only.** The hop's own cost in basis points (`swap_slippage_bps`, `gas_fee_bps`, `bridge_fee_bps`, `total_bps`), separate from `cost_breakdown_bps` above, whose `dex_swap_fee_bps` is `null` on this leg (the hop's swap cost lives here instead). `price_impact_bps` on `cost_breakdown_bps` equals this object's `swap_slippage_bps`."
          },
          "cross_chain_cost_usdc": {
            "allOf": [
              {
                "$ref": "#/components/schemas/BridgeCostBreakdownUsdc"
              }
            ],
            "description": "The same breakdown as `cross_chain_cost_bps`, in USDC."
          },
          "cost_breakdown_bps": {
            "$ref": "#/components/schemas/CostBreakdownBps"
          },
          "gasless": {
            "$ref": "#/components/schemas/LegGasless"
          },
          "estimated_gas_usd": {
            "$ref": "#/components/schemas/LegEstimatedGasUsd"
          },
          "sol_fee_payer": {
            "$ref": "#/components/schemas/LegSolFeePayer"
          },
          "signable_payloads": {
            "type": "array",
            "minItems": 1,
            "description": "Omitted on `quote_only` previews and on every `POST /quote/preview` leg; the leg is non-executable.",
            "items": {
              "$ref": "#/components/schemas/SignablePayload"
            }
          },
          "tradability": {
            "$ref": "#/components/schemas/Tradability",
            "description": "Probe warning for **this leg's own cell**: an exact `(ticker, protocol, chain)` match, not a ticker roll-up. `thin`: the cell fills, but not at every size below its measured minimum. `untradable`: nothing filled at any size across a full measurement window. **Advisory, never a block**: the leg is still planned, priced and submittable, and there is no request param to exclude warned cells. Absent means unmeasured or unwarned, never healthy-with-value-null.\n"
          },
          "warn_reason": {
            "$ref": "#/components/schemas/WarnReason",
            "description": "Why the cell is warned, strongest evidence first. Absent when unwarned, or when the warn predates reason recording. Not stable over a cell's lifetime: a `low_volume` warn that later kills a real order flips to `settlement_failure`.\n"
          },
          "thin_since": {
            "$ref": "#/components/schemas/ThinSince"
          }
        }
      },
      "QuoteSellLeg": {
        "type": "object",
        "required": [
          "quote_index",
          "chain",
          "protocol",
          "shares_consumed",
          "tokens_consumed",
          "estimated_output_usdc",
          "price_usdc_per_share",
          "cost_breakdown_bps",
          "signable_payloads"
        ],
        "properties": {
          "quote_index": {
            "type": "integer",
            "minimum": 0
          },
          "chain": {
            "$ref": "#/components/schemas/Chain"
          },
          "protocol": {
            "$ref": "#/components/schemas/Protocol"
          },
          "shares_consumed": {
            "$ref": "#/components/schemas/DecimalString"
          },
          "tokens_consumed": {
            "$ref": "#/components/schemas/DecimalString"
          },
          "estimated_output_usdc": {
            "$ref": "#/components/schemas/DecimalString"
          },
          "price_usdc_per_share": {
            "$ref": "#/components/schemas/DecimalString"
          },
          "base_asset": {
            "type": "string",
            "enum": [
              "usdc",
              "usdg"
            ],
            "description": "Base currency the caller receives; `usdc` on sol/eth/base/arbitrum/bnb legs, `usdg` on robinhood legs. Disambiguates the `_usdc`-named fields (`price_usdc_per_share`, `estimated_output_usdc`) when the base is USDG, which shares USDC's 6-decimal scale. On a cross-chain leg (`payout_chain` present) it names the payout chain's currency, always `usdc`. A same-chain `bnb` sell pays out **18-decimal Binance-Peg USDC**, a different token from Circle USDC; see `QuoteBuyLeg.base_asset`."
          },
          "amount_base": {
            "allOf": [
              {
                "$ref": "#/components/schemas/DecimalString"
              }
            ],
            "description": "Base amount received, human-decimal: the base-asset alias of `estimated_output_usdc` (equal value, base-denominated)."
          },
          "expires_at": {
            "type": "integer",
            "description": "Unix seconds: this leg's signing deadline. See `QuoteBuyLeg.expires_at` for why it is per leg. A **sell** submit must sign EVERY leg, so the deadline that actually binds a sell is the earliest of them, i.e. the top-level `expires_at`."
          },
          "payout_chain": {
            "allOf": [
              {
                "$ref": "#/components/schemas/PayoutChain"
              }
            ],
            "description": "**Present only on a cross-chain sell leg, and its presence is what marks one**: a\nposition sold on its own chain (`chain`/`protocol` above, unchanged) whose USDC is paid\nout on this chain, to your wallet there, because you sent `payout_chain`. The sale and\nthe payout are one leg, with no separate payout step to submit.\n\n`estimated_output_usdc` and `price_usdc_per_share` are what lands on this chain, net of\nthe route's fees; the network gas you pay to submit the sale is separate.\n`cross_chain_cost_bps` and `cross_chain_cost_usdc` disclose the hop's own cost, and\n`cost_breakdown_bps.dex_swap_fee_bps` is `null`. Absent on every same-chain leg.\n"
          },
          "origin_chain": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Chain"
              }
            ],
            "description": "Wire-shape parity with `/quote/buy`; never populated on a sell leg (a cross-chain sell carries `payout_chain` instead)."
          },
          "cross_chain_cost_bps": {
            "allOf": [
              {
                "$ref": "#/components/schemas/BridgeCostBreakdownBps"
              }
            ],
            "description": "**Cross-chain legs only** (`payout_chain` present): the hop's own cost in basis points of the sale's USD value, as on a cross-chain buy leg. `price_impact_bps` on `cost_breakdown_bps` equals this object's `swap_slippage_bps`."
          },
          "cross_chain_cost_usdc": {
            "allOf": [
              {
                "$ref": "#/components/schemas/BridgeCostBreakdownUsdc"
              }
            ],
            "description": "The same breakdown as `cross_chain_cost_bps`, in USDC."
          },
          "cost_breakdown_bps": {
            "$ref": "#/components/schemas/CostBreakdownBps"
          },
          "gasless": {
            "$ref": "#/components/schemas/LegGasless"
          },
          "estimated_gas_usd": {
            "$ref": "#/components/schemas/LegEstimatedGasUsd"
          },
          "sol_fee_payer": {
            "$ref": "#/components/schemas/LegSolFeePayer"
          },
          "signable_payloads": {
            "type": "array",
            "minItems": 1,
            "items": {
              "$ref": "#/components/schemas/SignablePayload"
            }
          },
          "tradability": {
            "$ref": "#/components/schemas/Tradability",
            "description": "Probe warning for **this leg's own cell**, filtered to the sell side. Same two words as on a buy leg, but published only when `warn_reason` is side-neutral (see below), so a sell leg carries all three keys or none. **Advisory, never a block**: nothing here refuses an exit. No `min_trade_size_usd` accompanies a sell anywhere on the API: it is a USD buy floor while a sell is denominated in shares. A sell refused for its size names its own minimum instead, as `min_notional_usdc` on the `no_routes` refusal.\n"
          },
          "warn_reason": {
            "$ref": "#/components/schemas/SideNeutralWarnReason",
            "description": "Why the cell is warned. **Sell legs carry only the side-neutral reasons**:\n\n- `low_volume` (a thin pool is a bad exit as surely as a bad entry)\n- `no_price_feed` (no feed is no feed, either direction)\n- `no_settlements` (nothing ever settling here is no less a dead end on exit).\n\nThe two buy-sided reasons, `no_fill_window` (the measurement ladder quotes buys) and\n`settlement_failure` (recorded on buys only), say nothing about an exit and are\nsuppressed along with the whole trio, as is a warn whose reason was never recorded.\n"
          },
          "thin_since": {
            "$ref": "#/components/schemas/ThinSince"
          }
        }
      },
      "QuoteOriginChain": {
        "type": "string",
        "enum": [
          "sol",
          "eth",
          "robinhood",
          "base"
        ],
        "description": "Where the stable you will pay with sits (USDC; USDG on `robinhood`). Buy and preview only;\n`/quote/sell` refuses it.\n\nOn the default route it changes the **ranking only**: a leg on any other chain ranks as if\nit cost the measured transfer from this chain, so `quote_index: 0` is the cheapest leg for\nmoney held here. That transfer cost is the route's measured fee only; it excludes the gas\nyou pay to send the transfer on this chain, which matters most on `eth`. No leg is added,\ndropped or repriced, and a leg off this chain is still a same-chain leg: fund its chain\n(for example through `/bridge/quote`) before you submit it.\n\nUnder `priority:\"speed\"` it is also the **only** chain a cross-chain leg may spend from\n(`origin_chain` on such a leg is always this value); a cell already funded on its own chain\nstill trades there (`eth` aside: it has no `\"speed\"` route of its own, so an `eth`-funded\nspeed request returns no `eth` leg), and when this chain does not cover the amount no\ncross-chain leg is offered at all. A single-chain `base` or `robinhood` pin is never\ncross-chain, so there it is inert.\n\nOn `/quote/buy` the wallet for this chain must be in the request (`sol_wallet` for `sol`,\n`eth_wallet` otherwise), else `400 invalid_request`. Absent or `null` = today's ranking and\norigin choice.\n"
      },
      "QuoteBuyRequest": {
        "type": "object",
        "required": [
          "ticker",
          "amount_usdc",
          "max_slippage_bps",
          "ownership_proof"
        ],
        "properties": {
          "ticker": {
            "$ref": "#/components/schemas/Ticker"
          },
          "amount_usdc": {
            "$ref": "#/components/schemas/UsdcHumanAmount"
          },
          "chain": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/Chain"
              },
              {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Chain"
                },
                "minItems": 1,
                "maxItems": 6,
                "uniqueItems": true
              },
              {
                "type": "null"
              }
            ],
            "description": "One chain pins routing to it. An array (one or more, unique) auto-routes within those chains only; `[\"x\"]` is identical to `\"x\"`; a member the ticker has no cell on is dropped, and an empty intersection is 422 no_routes. null/omitted = every chain the ticker lists."
          },
          "protocol": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/Protocol"
              },
              {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Protocol"
                },
                "minItems": 1,
                "maxItems": 7,
                "uniqueItems": true
              },
              {
                "type": "null"
              }
            ],
            "description": "One protocol pins routing to it. An array (one or more, unique) auto-routes within those protocols only; `[\"x\"]` is identical to `\"x\"`; a member the ticker has no cell on is dropped, and an empty intersection is 422 no_routes. Narrowing by protocol never relaxes admission: whatever survives still passes the same gates the unpinned route applies. null/omitted = every protocol the ticker lists. To exclude one, send the others."
          },
          "preferred_chain": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/Chain"
              },
              {
                "type": "null"
              }
            ],
            "description": "A preference, not a pin. The leg on this chain becomes `quote_index: 0` when the plan has one; the other legs keep their price order, and none is added or dropped. Must be one of the chains named in `chain` whenever `chain` is sent; a contradiction is `400 invalid_request`, never a silent fallback. Absent, or naming a chain the plan has no leg on, leaves the ordering exactly as it is today (cheapest first)."
          },
          "origin_chain": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/QuoteOriginChain"
              },
              {
                "type": "null"
              }
            ]
          },
          "priority": {
            "$ref": "#/components/schemas/Priority"
          },
          "execution": {
            "$ref": "#/components/schemas/Execution"
          },
          "max_slippage_bps": {
            "$ref": "#/components/schemas/SlippageBps"
          },
          "integrator_fee_bps": {
            "$ref": "#/components/schemas/IntegratorFeeBps"
          },
          "sol_wallet": {
            "$ref": "#/components/schemas/SolAddress"
          },
          "eth_wallet": {
            "$ref": "#/components/schemas/EvmAddress"
          },
          "sol_fee_payer": {
            "$ref": "#/components/schemas/SolFeePayer"
          },
          "ownership_proof": {
            "$ref": "#/components/schemas/OwnershipProof"
          },
          "quote_only": {
            "type": "boolean",
            "default": false,
            "description": "Price-only preview. When `true`, the quote is priced for a wallet that\nneed not hold the funds, but the result is non-executable: `quote_id`,\n`expires_at`, and every leg's `signable_payloads` are omitted, nothing is\npersisted, and there is no `/quote/{quote_id}/status` to poll or anything\nto submit. `ownership_proof` is still required. Buy-only; sending it to\n`/quote/sell` is rejected as an unknown field.\n"
          }
        },
        "additionalProperties": false,
        "description": "At least one of `sol_wallet` / `eth_wallet` is required, with the matching signature in `ownership_proof`."
      },
      "QuoteSellRequest": {
        "type": "object",
        "required": [
          "ticker",
          "amount_shares",
          "max_slippage_bps",
          "ownership_proof"
        ],
        "properties": {
          "ticker": {
            "$ref": "#/components/schemas/Ticker"
          },
          "amount_shares": {
            "$ref": "#/components/schemas/SharesHumanAmount"
          },
          "chain": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/Chain"
              },
              {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Chain"
                },
                "minItems": 1,
                "maxItems": 6,
                "uniqueItems": true
              },
              {
                "type": "null"
              }
            ],
            "description": "One chain pins routing to it. An array (one or more, unique) auto-routes within those chains only; `[\"x\"]` is identical to `\"x\"`; a member the ticker has no cell on is dropped, and an empty intersection is 422 no_routes. null/omitted = every chain the ticker lists."
          },
          "protocol": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/Protocol"
              },
              {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Protocol"
                },
                "minItems": 1,
                "maxItems": 7,
                "uniqueItems": true
              },
              {
                "type": "null"
              }
            ],
            "description": "One protocol pins routing to it. An array (one or more, unique) auto-routes within those protocols only; `[\"x\"]` is identical to `\"x\"`; a member the ticker has no cell on is dropped, and an empty intersection is 422 no_routes. Narrowing by protocol never relaxes admission: whatever survives still passes the same gates the unpinned route applies. null/omitted = every protocol the ticker lists. To exclude one, send the others."
          },
          "preferred_chain": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/Chain"
              },
              {
                "type": "null"
              }
            ],
            "description": "A preference, not a pin. The greedy fill runs over this chain's holdings first and over\neverything still unfilled after, so it changes which cells fill, never which cells are\neligible, and never the all-or-nothing submit rule. A cell on this chain that cannot be\npriced on the first pass rejoins the second pass alongside the other chains, so the\npreference costs at most one extra quote attempt and can never leave a shortfall the\nunpinned fill would have covered.\n\nMust be one of the chains named in `chain` whenever `chain` is sent; a contradiction is\n`400 invalid_request`. Absent = the plain greedy fill.\n"
          },
          "priority": {
            "$ref": "#/components/schemas/Priority"
          },
          "execution": {
            "$ref": "#/components/schemas/Execution"
          },
          "payout_chain": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/PayoutChain"
              },
              {
                "type": "null"
              }
            ],
            "description": "Where the sale's USDC lands. Absent or `null` (the default) sells every position on its\nown chain, exactly as a request without this field. Independent of `priority`.\nSell-only: sending it to `/quote/buy` or `/quote/preview` is `400 invalid_request`.\n\nWhen set, every leg pays out USDC on this chain, to your own wallet there, and each\nposition you hold is planned on its own terms:\n- a position on `payout_chain` sells on that chain as usual (under `priority: \"speed\"`\n  it keeps the speed filter, so an `eth` position is left out when paying out on `eth`);\n- a `sol/xstocks`, `sol/backpack`, `base/coinbase`, `eth/ondo` or `bnb/bstocks` position\n  on another chain sells cross-chain as one leg, marked by `payout_chain` on that leg,\n  whatever the `priority`;\n- any other position (`sol/ondo`, `eth/xstocks`, `bnb/ondo`, `bnb/xstocks`, `robinhood`,\n  `arbitrum`) is left out and named by a `cross_chain_route_unavailable` warning. It is\n  never sold on its own chain instead, because that would pay out somewhere you did not\n  ask for.\n\n`400 invalid_request` (message prefixed `payout_chain: `) when the wallet for this chain\nis missing (`sol_wallet` for `sol`, `eth_wallet` otherwise), or when nothing in your\n`chain`/`protocol` scope can pay out here (for example a `robinhood` pin, or\n`chain: [\"eth\"]` with `protocol: \"xstocks\"`).\n\nUnder `execution: \"user_operation\"` a `base` or `eth` position pays out cross-chain as\nONE `evm_calls` payload (an `approve` of the stock, then a `deposit`) that your\n`eth_wallet` sends on the position's chain; a `sol` position keeps its\n`solana_versioned_tx`; a `bnb/bstocks` position has no `user_operation` lane and is left\nout with a `cross_chain_route_unavailable` warning (`disabled`). With a payout elsewhere,\n`chain: [\"eth\"]` together with `priority: \"speed\"` is accepted: the `eth/ondo` position\nsells cross-chain.\n\n- `422 holdings_insufficient` when your holdings in scope fall short, wherever they sit.\n- `422 no_routes` with `reason: payout_route_unavailable` when you hold enough, but not\n  enough of it can pay out on this chain, or a cross-chain leg was refused or could not\n  land. A leg that fails on our side does not count toward that reason; re-quote.\n"
          },
          "max_slippage_bps": {
            "$ref": "#/components/schemas/SlippageBps"
          },
          "integrator_fee_bps": {
            "$ref": "#/components/schemas/IntegratorFeeBps"
          },
          "sol_wallet": {
            "$ref": "#/components/schemas/SolAddress"
          },
          "eth_wallet": {
            "$ref": "#/components/schemas/EvmAddress"
          },
          "sol_fee_payer": {
            "$ref": "#/components/schemas/SolFeePayer"
          },
          "ownership_proof": {
            "$ref": "#/components/schemas/OwnershipProof"
          }
        },
        "additionalProperties": false,
        "description": "At least one of `sol_wallet` / `eth_wallet` is required, with the matching signature in `ownership_proof`."
      },
      "QuotePreviewRequest": {
        "type": "object",
        "description": "`QuoteBuyRequest` minus every wallet-bound field. `sol_wallet`, `eth_wallet`, `sol_fee_payer`, `ownership_proof` and `quote_only` are all rejected here as unknown keys; a preview binds no wallet, so there is nothing to prove ownership of and nothing that could be executed. `amount_usdc` is additionally capped at 1000000 on this route (unbounded on `/quote/buy`, which settles against a real balance): above it the request is a 400.",
        "required": [
          "ticker",
          "amount_usdc",
          "max_slippage_bps"
        ],
        "properties": {
          "ticker": {
            "$ref": "#/components/schemas/Ticker"
          },
          "amount_usdc": {
            "allOf": [
              {
                "$ref": "#/components/schemas/UsdcHumanAmount"
              },
              {
                "description": "Preview-only bound; must be ≤ 1000000 USDC."
              }
            ]
          },
          "chain": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/Chain"
              },
              {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Chain"
                },
                "minItems": 1,
                "maxItems": 6,
                "uniqueItems": true
              },
              {
                "type": "null"
              }
            ],
            "description": "One chain pins routing to it. An array (one or more, unique) auto-routes within those chains only; `[\"x\"]` is identical to `\"x\"`; a member the ticker has no cell on is dropped, and an empty intersection is 422 no_routes. null/omitted = every chain the ticker lists."
          },
          "protocol": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/Protocol"
              },
              {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Protocol"
                },
                "minItems": 1,
                "maxItems": 7,
                "uniqueItems": true
              },
              {
                "type": "null"
              }
            ],
            "description": "One protocol pins routing to it. An array (one or more, unique) auto-routes within those protocols only; `[\"x\"]` is identical to `\"x\"`; a member the ticker has no cell on is dropped, and an empty intersection is 422 no_routes. null/omitted = every protocol the ticker lists. To exclude one, send the others."
          },
          "preferred_chain": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/Chain"
              },
              {
                "type": "null"
              }
            ],
            "description": "A preference, not a pin: the leg on this chain becomes `quote_index: 0` when the preview has one, and the rest keep their price order. Must be one of the chains named in `chain` whenever `chain` is sent (`400 invalid_request` otherwise)."
          },
          "origin_chain": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/QuoteOriginChain"
              },
              {
                "type": "null"
              }
            ],
            "description": "As on `/quote/buy`, except that the preview reads no balance: under `priority:\"speed\"` it prices as if the whole amount sits on this chain and nowhere else, so a leg on it is same-chain and a cross-chain-capable leg off it comes back cross-chain from it. `eth` is the exception on the first half: it has no `\"speed\"` route of its own, so a `\"speed\"` preview funded on `eth` returns no `eth` leg. Absent, a `\"speed\"` preview assumes `sol`, and the default route ranks exactly as it does today."
          },
          "priority": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Priority"
              }
            ],
            "description": "Accepted here so a preview prices what an executable `speed` request would route. The preview binds no wallet, so the speed route is priced without one; its balance and allowance conditions surface only on `/quote/buy` or `/quote/sell`."
          },
          "execution": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Execution"
              }
            ],
            "description": "Accepted so a preview prices the `user_operation` lane as it would execute (`gasless: true`, `estimated_gas_usd: \"0\"`). No wallet is bound, so the delegation check runs only on `/quote/buy` or `/quote/sell`."
          },
          "max_slippage_bps": {
            "$ref": "#/components/schemas/SlippageBps"
          },
          "integrator_fee_bps": {
            "$ref": "#/components/schemas/IntegratorFeeBps"
          }
        },
        "additionalProperties": false
      },
      "IntegratorFeeBps": {
        "type": "integer",
        "minimum": 0,
        "maximum": 10000,
        "description": "Your fee on this quote, net bps, overriding the default we configured for your key, up to your per-partner ceiling. Omit to use the default. Requires an `X-API-Key` (`tik_…`); a non-zero value without one is `400 integrator_fee_requires_api_key`. It is stacked into the same on-wire fee as Treasures' and already reflected in `estimated_output_*`; on Solana the venue keeps half of that fee, so it charges the trader twice this figure for you to net it. A quote that carries your fee can only be submitted with your key (`403 quote_integrator_mismatch`)."
      },
      "IntegratorFeeError": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string",
            "enum": [
              "invalid_integrator_fee",
              "integrator_fee_requires_api_key"
            ]
          },
          "max_bps": {
            "type": "integer",
            "description": "Your per-request ceiling; present on `invalid_integrator_fee`."
          },
          "reason": {
            "type": "string",
            "description": "Why a venue refused the requested fee, when that is the cause rather than your ceiling: `fee_above_maximum`, `fee_below_minimum` (raise it, or send 0), or `fee_unavailable` (no fee can be charged on some route right now). An open set; treat an unrecognised value as \"this fee can't be charged\"."
          }
        }
      },
      "TradeWarning": {
        "type": "object",
        "required": [
          "code"
        ],
        "description": "One disclosed risk on a quote. `code` shares the open vocabulary of `WarnReason` plus the two price-check codes below, so you learn one set rather than two; treat an unrecognised code as \"warned, reason unknown\" rather than an error. The other keys are the material values behind the code (a deviation in bps, the anchor used, the instant a warn was raised) and vary by code.\n",
        "properties": {
          "code": {
            "type": "string",
            "description": "- `no_reference`: no reference market price could be obtained for the asset, so nothing\n  independent checked this quote's price. Permanent for an asset our market-data\n  provider does not cover (the HK listings, the Ondo basket); transient during a\n  provider outage.\n- `off_reference`: a reference exists and the quote sits beyond its cap, in the\n  direction that costs you. Beyond an implausibility bound the quote is refused\n  outright instead (`no_routes` / `price_implausible`) and no acknowledgement can\n  clear it.\n- `speed_route_unavailable`: you sent `priority: \"speed\"` and the speed route could not\n  serve the named chain, so **that chain's leg is absent** from this response (the one\n  case returned on its relayed route instead is `speed_route_fallback`, below). It\n  carries `reason` and `chain` (the\n  dropped leg's chain; absent only when the whole speed route is off, which is a\n  response-level fact, not a per-leg one). Advisory: every leg that IS returned is\n  fully executable; re-quote without `priority` to get the relayed route on that chain.\n\n  The `reason` values this API emits today are exactly:\n\n  - `disabled` (the speed route is switched off; this is the one reason with no `chain`)\n  - `insufficient_balance` (the wallet is short the spent token)\n  - `no_routes` (no reachable pool, or the built swap failed an integrity check)\n  - `provider_error` (an upstream failure, caught and downgraded, including a delegation\n    read that failed under `execution: \"user_operation\"`)\n  - under `execution: \"user_operation\"` only, `wallet_not_delegated` (the wallet is\n    delegated to code other than Modular Account v2 on the named chain), where\n    `disabled` then also carries `chain` when it means \"no bundler serves this chain\n    yet\".\n\n  A missing router allowance is not a reason: the quote bundles the approve instead\n  (`SignableEvmTx`).\n\n  One more reason rides only a `no_routes` refusal (`NoRoutesError.warnings[]`), never a\n  served quote: `no_speed_venue`, which also carries `protocol` and names a chain the\n  speed route does not serve that listing on (`eth`, `bnb` or `arbitrum`). The named\n  listing exists for this ticker but its own-chain venue is one `\"speed\"` never quotes\n  (a gasless order that can take minutes to fill), so that venue was not tried.\n  Re-quote without `priority` to reach it.\n\n  The list is **open**: this object does not restrict its properties, and a future\n  release may add a value. Branch on the ones you handle and treat anything else as\n  \"speed route unavailable, reason unknown\" rather than an error.\n- `speed_route_unpriced_gas`: the opposite outcome, and a separate code for exactly that\n  reason: the leg on the named `chain` **was** served on the speed route, but no USD gas\n  price was available, so its `estimated_gas_usd` is `null` and the route ranking\n  ignored gas for it. Carries `chain`, and no `reason`. Advisory: price the gas yourself\n  before choosing this leg over a gasless one.\n- `speed_route_fallback`: you sent `priority: \"speed\"` on `/quote/sell` and the speed\n  route answered `no_routes` for the named `chain`/`protocol`, so that leg **is** in\n  this response but on its **relayed route**, not the fast path you asked for:\n  `gasless: true`, one `evm_eip712_typed_data` payload, and a fill that can take\n  minutes. Carries `chain`, `protocol`, `reason` (`no_routes`), `approval_needed` and\n  `approval_spender`.\n\n  `approval_needed` is `true` when the wallet's allowance of the stock token to\n  `approval_spender` does not cover the sale. A relayed order from that wallet\n  **cannot fill** until you approve, and this API does not send that approval for you:\n  `POST /trade/submit` may refuse it as `not_enough_balance_or_allowance`, or it stays\n  pending and expires unfilled. `false` means the allowance covers it, and `null` that\n  it could not be read. Once the wallet has approved, a later speed quote for the same\n  position is normally served on the speed route again.\n\n  Sent only for a leg this response carries. A position the relayed route priced but\n  that another leg outranked reads `speed_route_unavailable` with `reason: \"no_routes\"`\n  instead.\n- `cross_chain_route_unavailable`: a `priority:\"speed\"` cell you were not funded on, and\n  that can be reached cross-chain (`eth/ondo`, `sol/xstocks`, `sol/backpack`,\n  `base/coinbase`, `bnb/bstocks`), could not be served cross-chain and **fell back** to\n  today's plan for that cell instead (a dropped same-chain speed leg on base or bnb, or\n  no leg at all on sol and eth: a sol leg your `sol_wallet` cannot fund is never served,\n  and eth is never served on its gasless route under `\"speed\"`).\n\n  It also names a sol cell with no cross-chain route (such as `sol/ondo`) that your\n  `sol_wallet` cannot fund while another of your wallets could: `reason: no_routes`, and\n  no leg. When nothing is left to serve, the same entries ride the refusal's\n  `NoRoutesError.warnings[]`.\n\n  Carries `chain`, `protocol` and `reason`, a closed set today:\n\n  - `no_routes`\n  - `over_max` (above the cross-chain ceiling)\n  - `fee_unavailable`\n  - `disabled`\n  - `provider_error`\n  - `wallet_not_delegated`\n  - `wallet_missing`, which this API has never yet emitted on this code (a missing\n    origin wallet is dropped before a per-cell warning is composed); treat it as\n    reserved.\n\n  Not a `speed_route_unavailable` reason: that code means \"your same-chain speed leg\n  fell back\", this one means \"the cross-chain attempt for this cell fell back\".\n\n  On `/quote/sell` with `payout_chain` (any `priority`) the same code names a position\n  you hold that is **left out** of the plan because it cannot pay out on that chain: a\n  cell with no cross-chain route (`reason: no_routes`), or a cross-chain leg that was\n  refused or could not land (its own `reason` from the set above). Such a position is\n  never sold on its own chain instead, and one that a later part of the plan did sell\n  is not named.\n- `cross_chain_price_deviation`: the leg named by `chain`/`protocol` priced more than\n  `threshold_bps` (500) away from the reference market price. Carries `deviation_bps`\n  and `threshold_bps`. **Advisory only, never a refusal**: the leg is fully executable;\n  a quote under this deviation, but still above what you would normally expect on that\n  cell, may ship with no warning at all (the threshold is a bound, not a tight one).\n- `exit_gas_unfunded`: a cross-chain buy leg (one carrying `origin_chain`) lands the\n  asset on the named `chain`/`protocol` in a wallet whose native balance cannot pay the\n  cheapest later exit: on an EVM chain, one token approval at the current gas price,\n  doubled; on `sol`, two transaction fees, plus the rent for a USDC token account when\n  the wallet has none. Carries `chain` and `protocol`.\n  **Advisory only, never a refusal**: the leg is fully executable and you fund your own\n  gas, so fund that wallet before you sell.\n\n  A balance that could not be read is not warned. Also sent on `quote_only`; never sent\n  by `POST /quote/preview`, which quotes no wallet of yours.\n\n`cross_chain_route_unavailable` and `exit_gas_unfunded` appear once per affected\n`chain`/`protocol` pair, `speed_route_unavailable` once per `chain` and `reason` (once\nper `chain`/`protocol` pair for `no_speed_venue`, and once in all for `disabled`),\n`speed_route_unpriced_gas` once per `chain`, and `speed_route_fallback` once per\n`chain`/`protocol` pair; every other code appears at most once per response.\n\nEvery other `code` value is the routed cell's own `WarnReason`.\n"
          }
        },
        "additionalProperties": true
      },
      "WarningsAckToken": {
        "type": "string",
        "pattern": "^[0-9a-f]{32}$",
        "description": "A digest over this `quote_id` and the exact `warnings[]` served with it. Present only alongside a non-empty set, and never on a preview; `quote_only` and `POST /quote/preview` both omit it, having no `quote_id` to bind one to and nothing to submit it against. Echo it back as `acknowledged_warnings` on `POST /trade/submit` to record that you received these warnings before executing, see that field for what the record does and does not mean.\n"
      },
      "QuoteBuyResponse": {
        "type": "object",
        "required": [
          "side",
          "ticker",
          "tradfi_reference",
          "quotes",
          "warnings"
        ],
        "properties": {
          "quote_id": {
            "type": "string",
            "description": "Omitted on `quote_only` previews and on `POST /quote/preview` (no executable quote to submit)."
          },
          "side": {
            "type": "string",
            "enum": [
              "buy"
            ]
          },
          "ticker": {
            "$ref": "#/components/schemas/Ticker"
          },
          "expires_at": {
            "type": "integer",
            "description": "Unix seconds: the EARLIEST leg's deadline, so it is safe for any leg. Each leg also carries its own `expires_at`, which is what `/trade/submit` enforces for the leg you sign; on a multi-chain quote the longer-lived legs stay submittable past this value. A leg already past its own deadline when the response is built is dropped, so `quote_index` values can skip; always echo `quotes[].quote_index`, never the array position. Omitted on `quote_only` previews and on `POST /quote/preview`; neither has an executable quote to expire."
          },
          "tradfi_reference": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/TradfiReference"
              },
              {
                "type": "null"
              }
            ]
          },
          "quotes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/QuoteBuyLeg"
            }
          },
          "warnings": {
            "type": "array",
            "description": "Everything this quote discloses about the trade. **Always present**, `[]` when there is\nnothing to disclose, so an empty list is never ambiguous with an older build. A warned\nquote is still executable: this plane discloses and does not gate. Deciding what to show\nan end user, and whether to proceed, is yours.\n\nA leg reporting `tradability: \"thin\"` with no `warn_reason` emits NO\n`warnings[]` entry: the reason column is newer than the verdict, so a cell warned before\nit existed has nothing to name here and stays silent until the next probe pass records\none. The leg's own `tradability` is the disclosure in that window; do not read an empty\n`warnings[]` beside a `thin` leg as \"no risk\".\n",
            "items": {
              "$ref": "#/components/schemas/TradeWarning"
            }
          },
          "warnings_ack_token": {
            "$ref": "#/components/schemas/WarningsAckToken"
          }
        }
      },
      "QuoteSellResponse": {
        "type": "object",
        "required": [
          "quote_id",
          "side",
          "ticker",
          "expires_at",
          "tradfi_reference",
          "quotes",
          "totals",
          "warnings"
        ],
        "properties": {
          "quote_id": {
            "type": "string"
          },
          "side": {
            "type": "string",
            "enum": [
              "sell"
            ]
          },
          "ticker": {
            "$ref": "#/components/schemas/Ticker"
          },
          "expires_at": {
            "type": "integer",
            "description": "Unix seconds: the EARLIEST leg's deadline. A sell submit signs every leg, so this is the deadline that binds it; each leg's own `expires_at` is never later."
          },
          "tradfi_reference": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/TradfiReference"
              },
              {
                "type": "null"
              }
            ]
          },
          "quotes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/QuoteSellLeg"
            }
          },
          "totals": {
            "type": "object",
            "required": [
              "shares_total",
              "usdc_total_estimated"
            ],
            "properties": {
              "shares_total": {
                "$ref": "#/components/schemas/DecimalString"
              },
              "usdc_total_estimated": {
                "$ref": "#/components/schemas/DecimalString"
              }
            }
          },
          "warnings": {
            "type": "array",
            "description": "See `QuoteBuyResponse.warnings`; same contract on both sides.",
            "items": {
              "$ref": "#/components/schemas/TradeWarning"
            }
          },
          "warnings_ack_token": {
            "$ref": "#/components/schemas/WarningsAckToken"
          }
        }
      },
      "PublicLegStatus": {
        "type": "string",
        "enum": [
          "pending",
          "completed",
          "failed",
          "broadcast_failed"
        ]
      },
      "AggregateStatus": {
        "type": "string",
        "enum": [
          "in_progress",
          "completed",
          "partial_failed",
          "all_failed"
        ]
      },
      "PublicLeg": {
        "type": "object",
        "required": [
          "quote_index",
          "trade_id",
          "ticker",
          "chain",
          "protocol",
          "side",
          "tx_hash",
          "order_hash",
          "user_op_hash",
          "status",
          "error_code",
          "filled_shares",
          "filled_tokens",
          "filled_usdc",
          "last_synced_at"
        ],
        "properties": {
          "quote_index": {
            "type": "integer",
            "minimum": 0
          },
          "trade_id": {
            "type": "string"
          },
          "ticker": {
            "$ref": "#/components/schemas/Ticker"
          },
          "chain": {
            "$ref": "#/components/schemas/Chain"
          },
          "protocol": {
            "$ref": "#/components/schemas/Protocol"
          },
          "side": {
            "type": "string",
            "enum": [
              "buy",
              "sell"
            ]
          },
          "tx_hash": {
            "type": [
              "string",
              "null"
            ],
            "description": "The leg's transaction hash or signature. On a `failed` same-chain `sol` leg it is the signature the execution venue reported, which may not exist on chain."
          },
          "order_hash": {
            "type": [
              "string",
              "null"
            ]
          },
          "user_op_hash": {
            "type": [
              "string",
              "null"
            ],
            "description": "`user_operation` legs only: the ERC-4337 op hash, from `broadcast` on. On a same-chain leg `tx_hash` is null until the bundle mines, then carries the bundle transaction; on a cross-chain leg (`origin_chain` or `payout_chain` present) it stays null until the leg is terminal, then carries the destination fill (a completed buy) or the bundle (a sell, or a failed leg whose op was included); a leg whose op never landed keeps it null, so this hash is the leg's handle. Null on every other leg."
          },
          "status": {
            "$ref": "#/components/schemas/PublicLegStatus"
          },
          "error_code": {
            "type": [
              "string",
              "null"
            ]
          },
          "payout_chain": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Chain"
              }
            ],
            "description": "**Cross-chain sell legs only** (quoted with `payout_chain`; absent on every other leg):\nthe chain the leg's USDC lands on: the `PayoutChain` you asked for, or the leg's own\n`chain` after a return there (below), which can be `bnb`, not itself a payout chain.\n\n`tx_hash` stays the sale on `chain` (under `execution: \"user_operation\"`, null until the\nleg completes, then the bundle that sold it).\n\nOn `completed` it names where the USDC actually landed: if the cross-chain payout could\nnot be made, the USDC may be returned on the sale's own `chain` instead, and this field\nthen equals `chain`. `filled_usdc` is the USDC that landed.\n"
          },
          "payout_tx_hash": {
            "type": [
              "string",
              "null"
            ],
            "description": "Present with `payout_chain`: the transaction on `payout_chain` that paid the USDC out. `null` unless the leg is `completed`."
          },
          "filled_shares": {
            "$ref": "#/components/schemas/DecimalString"
          },
          "filled_tokens": {
            "$ref": "#/components/schemas/DecimalString"
          },
          "filled_usdc": {
            "$ref": "#/components/schemas/DecimalString"
          },
          "last_synced_at": {
            "type": "integer"
          }
        }
      },
      "QuoteStatusResponse": {
        "type": "object",
        "required": [
          "quote_id",
          "aggregate_status",
          "is_cached",
          "poll_after_ms",
          "legs"
        ],
        "properties": {
          "quote_id": {
            "type": "string"
          },
          "aggregate_status": {
            "$ref": "#/components/schemas/AggregateStatus"
          },
          "is_cached": {
            "type": "boolean",
            "description": "True when served from the in-progress cache; false on DB-fresh reads and all terminal aggregates."
          },
          "poll_after_ms": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Minimum useful interval before the next poll, in milliseconds.\n\n- `1250` while a speed-route leg submitted in the last 5 min is still in flight (it\n  settles by receipt within a block or two)\n- `3250` when only gasless or Solana legs remain (the upstream order status is synced\n  at most every 3 s per leg regardless of poll rate) or a speed-route leg has sat\n  unmined past 5 min.\n- `null` once `aggregate_status` is terminal; stop polling.\n\nThe value sits just above the server-side cache window so a client polling at it never\nreads a stale entry. On a cached response (`is_cached: true`) it is the time left on\nthat cached view, not the full window, so a client that arrives late is not asked to\nwait another one; it is never below 1000. Advisory: polling faster returns the cached\nview.\n"
          },
          "legs": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PublicLeg"
            }
          }
        }
      },
      "SignedSolanaPayload": {
        "type": "object",
        "required": [
          "type",
          "signed_tx_base64"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "solana_versioned_tx"
            ]
          },
          "signed_tx_base64": {
            "type": "string",
            "minLength": 1,
            "maxLength": 2048,
            "description": "Base64 fully-signed Solana `VersionedTransaction`."
          }
        },
        "additionalProperties": false
      },
      "SignedEvmPayload": {
        "type": "object",
        "description": "Signed gasless EVM order: the caller's EIP-712 signature over the quote leg's typed data. Used by **every** EVM leg: eth (mainnet), robinhood (Robinhood Chain / 4663), base (Base / 8453), arbitrum (Arbitrum One / 42161) and bnb (BNB Smart Chain / 56). The server relays the signed order to that chain's own resolver network; the caller never broadcasts an on-chain tx.",
        "required": [
          "type",
          "signature"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "evm_eip712_signature"
            ]
          },
          "signature": {
            "type": "string",
            "minLength": 1,
            "maxLength": 150,
            "description": "0x-prefixed EIP-712 EOA signature (132 chars)."
          }
        },
        "additionalProperties": false
      },
      "SignedEvmTx": {
        "type": "object",
        "description": "A whole signed EVM transaction: the reply to a `SignableEvmTx` (speed-route) leg. Sign the\npayload's `tx_hex` unchanged and send the serialized result back; **you do not broadcast\nit**, Treasures does, after checking that the bytes are the ones it issued (signer, chain,\n`to`, calldata, value, nonce, gas and fees all bind against the quote), that the wallet\nstill holds the token and the native gas (and the allowance, on a single-payload leg), and\nthat the transaction still simulates.\n\nAny mismatch is a per-leg `invalid_signature`; a simulation revert is `swap_reverted` (or\n`approve_failed` for a bundled approve) and nothing is sent. A leg that issued two\n`SignableEvmTx` payloads needs **both** back, one `evm_signed_tx` each; the server matches\nthem by nonce.\n",
        "required": [
          "type",
          "signed_tx_hex"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "evm_signed_tx"
            ]
          },
          "signed_tx_hex": {
            "type": "string",
            "pattern": "^0x[0-9a-fA-F]+$",
            "maxLength": 16384,
            "description": "0x-prefixed signed RLP transaction."
          }
        },
        "additionalProperties": false
      },
      "SignedEvmUserOperation": {
        "type": "object",
        "description": "The reply to a `SignableEvmCalls` leg: the sponsored, signed ERC-4337 **v0.7**\nUserOperation (unpacked fields, `factory`/`factoryData` absent). Numeric fields as decimal\nor `0x` hex strings; hex fields `0x`-prefixed.\n\nA wallet with no code on the chain adds `eip7702Auth`, its signed EIP-7702 authorization,\nwhich the bundler applies in the same transaction; it must name a Modular Account v2\ndelegate as `address`, the leg's `chain_id` (never `0`, which would delegate the wallet on\nevery chain), and be signed by `sender`, else `invalid_signature`. It does not change the\nop hash. An authorization the chain then skips (a stale `nonce`) leaves the wallet without\ncode, and the simulation refuses it as `swap_reverted`.\n\nThe server binds it to the quote (see `SignableEvmCalls`), dedupes on its hash, re-checks\nbalance (and allowance on a single-call leg), simulates it on the bundler\n(`eth_estimateUserOperationGas`; a refusal never reached the mempool: `nonce_conflict`,\n`sponsorship_rejected`, `swap_reverted`, `provider_error`), then submits it. The result is\n`broadcast` with `user_op_hash` set and `tx_hash` null; `/status` flips it once the bundle\nmines. Exactly one per leg; ≤ 16 KB.\n",
        "required": [
          "type",
          "user_operation"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "evm_user_operation"
            ]
          },
          "user_operation": {
            "type": "object",
            "required": [
              "sender",
              "nonce",
              "callData",
              "callGasLimit",
              "verificationGasLimit",
              "preVerificationGas",
              "maxFeePerGas",
              "maxPriorityFeePerGas",
              "signature"
            ],
            "properties": {
              "sender": {
                "$ref": "#/components/schemas/EvmAddress"
              },
              "nonce": {
                "$ref": "#/components/schemas/Uint256String"
              },
              "callData": {
                "type": "string",
                "pattern": "^0x[0-9a-fA-F]*$"
              },
              "callGasLimit": {
                "$ref": "#/components/schemas/Uint128String"
              },
              "verificationGasLimit": {
                "$ref": "#/components/schemas/Uint128String"
              },
              "preVerificationGas": {
                "$ref": "#/components/schemas/Uint256String"
              },
              "maxFeePerGas": {
                "$ref": "#/components/schemas/Uint128String"
              },
              "maxPriorityFeePerGas": {
                "$ref": "#/components/schemas/Uint128String"
              },
              "paymaster": {
                "$ref": "#/components/schemas/EvmAddress"
              },
              "paymasterVerificationGasLimit": {
                "$ref": "#/components/schemas/Uint128String"
              },
              "paymasterPostOpGasLimit": {
                "$ref": "#/components/schemas/Uint128String"
              },
              "paymasterData": {
                "type": "string",
                "pattern": "^0x[0-9a-fA-F]*$"
              },
              "factory": {
                "type": "string",
                "pattern": "^0x[0-9a-fA-F]*$"
              },
              "factoryData": {
                "type": "string",
                "pattern": "^0x[0-9a-fA-F]*$"
              },
              "eip7702Auth": {
                "type": "object",
                "description": "A first-operation EIP-7702 delegation, as the bundler RPC spells it (viem's `authorization` on a UserOperation).",
                "required": [
                  "address",
                  "chainId",
                  "nonce",
                  "r",
                  "s",
                  "yParity"
                ],
                "properties": {
                  "address": {
                    "$ref": "#/components/schemas/EvmAddress"
                  },
                  "chainId": {
                    "$ref": "#/components/schemas/Uint256String"
                  },
                  "nonce": {
                    "type": "string",
                    "pattern": "^(0x[0-9a-fA-F]{1,64}|[0-9]{1,78})$",
                    "description": "A uint64, decimal or `0x` hex; a larger value is `400 invalid_request`."
                  },
                  "r": {
                    "type": "string",
                    "pattern": "^0x[0-9a-fA-F]{64}$",
                    "description": "Exactly 32 bytes."
                  },
                  "s": {
                    "type": "string",
                    "pattern": "^0x[0-9a-fA-F]{64}$",
                    "description": "Exactly 32 bytes, low-s (at most half the curve order, as EIP-7702 requires); a high-s tuple is `invalid_signature`."
                  },
                  "yParity": {
                    "type": "string",
                    "pattern": "^(0x[0-9a-fA-F]{1,64}|[0-9]{1,78})$",
                    "description": "`0` or `1`, decimal or `0x` hex (`0x00` / `0x01` as viem sends it)."
                  }
                },
                "additionalProperties": false
              },
              "signature": {
                "type": "string",
                "pattern": "^0x[0-9a-fA-F]*$",
                "minLength": 4
              }
            },
            "additionalProperties": false
          }
        },
        "additionalProperties": false
      },
      "Uint256String": {
        "type": "string",
        "pattern": "^(0x[0-9a-fA-F]{1,64}|[0-9]{1,78})$",
        "description": "A uint256 as a decimal string, or as 0x-prefixed hex. The pattern admits up to 78 decimal digits, which overshoots 2^256-1; the server bounds the VALUE as well and answers `400 invalid_request` on an out-of-range one."
      },
      "Uint128String": {
        "type": "string",
        "pattern": "^(0x[0-9a-fA-F]{1,32}|[0-9]{1,39})$",
        "description": "A uint128 as a decimal string, or as 0x-prefixed hex: the ERC-4337 v0.7 PACKING width of the gas-limit and fee fields (`accountGasLimits` and `gasFees` each pack two uint128s into one 32-byte slot). Bounded by value, not only by shape: an over-wide field is `400 invalid_request` rather than a hasher throw."
      },
      "SignedPayload": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/SignedSolanaPayload"
          },
          {
            "$ref": "#/components/schemas/SignedEvmPayload"
          },
          {
            "$ref": "#/components/schemas/SignedEvmTx"
          },
          {
            "$ref": "#/components/schemas/SignedEvmUserOperation"
          }
        ],
        "discriminator": {
          "propertyName": "type",
          "mapping": {
            "solana_versioned_tx": "#/components/schemas/SignedSolanaPayload",
            "evm_eip712_signature": "#/components/schemas/SignedEvmPayload",
            "evm_signed_tx": "#/components/schemas/SignedEvmTx",
            "evm_user_operation": "#/components/schemas/SignedEvmUserOperation"
          }
        }
      },
      "SignedLeg": {
        "type": "object",
        "required": [
          "quote_index",
          "signed_payloads"
        ],
        "properties": {
          "quote_index": {
            "type": "integer",
            "minimum": 0
          },
          "signed_payloads": {
            "type": "array",
            "minItems": 1,
            "maxItems": 4,
            "items": {
              "$ref": "#/components/schemas/SignedPayload"
            },
            "description": "One entry per payload the leg issued, IN THE ORDER THE QUOTE ISSUED THEM. A speed-route leg may issue two (`approve` then `swap`); sign and return both. Order is load-bearing for idempotency: a replay is recognised by a hash over this array, so a re-submit that reorders the entries is refused as a new submit (`leg_already_submitted`, 409). Fewer or more entries than the leg issued is `incomplete_submit` (400), before anything is sent."
          }
        },
        "additionalProperties": false
      },
      "TradeSubmitRequest": {
        "type": "object",
        "required": [
          "quote_id",
          "signed"
        ],
        "properties": {
          "quote_id": {
            "type": "string",
            "minLength": 1
          },
          "signed": {
            "type": "array",
            "minItems": 1,
            "items": {
              "$ref": "#/components/schemas/SignedLeg"
            }
          },
          "acknowledged_warnings": {
            "allOf": [
              {
                "$ref": "#/components/schemas/WarningsAckToken"
              }
            ],
            "description": "**Optional, and never required.** Echo the quote's `warnings_ack_token` to have the\nacknowledgement recorded beside the trade; omit it and the trade proceeds exactly as\nbefore, with the acknowledgement columns left empty.\n\nWe record the warnings we served on **every** trade whether or not you echo anything, so\nomitting this loses you a record of your own acknowledgement, not ours of the disclosure.\n\nSending a value that does not match the warnings served with this `quote_id` is refused\nwith `warnings_not_acknowledged` (422) rather than recorded; clear it by omitting the\nfield or by re-quoting and echoing the fresh token. A clean quote (`warnings: []`)\nignores the field entirely.\n\n**What this does not cover.** Disclosing risk to your own end users, and keeping evidence\nthat you did, is governed by your integrator agreement and your records, not by this\nfield. Echoing a token records what *you* were told, never what your user was.\n"
          }
        },
        "additionalProperties": false
      },
      "LegResult": {
        "type": "object",
        "required": [
          "quote_index",
          "trade_id",
          "status",
          "tx_hash",
          "order_hash",
          "user_op_hash",
          "error_code"
        ],
        "properties": {
          "quote_index": {
            "type": "integer",
            "minimum": 0
          },
          "trade_id": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "broadcast",
              "broadcast_unknown",
              "completed",
              "failed",
              "broadcast_failed"
            ]
          },
          "tx_hash": {
            "type": [
              "string",
              "null"
            ],
            "description": "The leg's transaction hash or signature. On a `failed` same-chain `sol` leg it is the signature the execution venue reported, which may not exist on chain."
          },
          "order_hash": {
            "type": [
              "string",
              "null"
            ]
          },
          "user_op_hash": {
            "type": [
              "string",
              "null"
            ],
            "description": "`user_operation` legs only: the ERC-4337 op hash the bundler took, set from `broadcast` on while `tx_hash` is still null (it becomes the bundle transaction once mined, poll `/status`). Null on every other leg."
          },
          "error_code": {
            "type": [
              "string",
              "null"
            ],
            "description": "Per-leg failure reason: its own open vocabulary, never an HTTP `error` code:\n\n- `invalid_signature`\n- `quote_expired`\n- `not_enough_balance_or_allowance`\n- `provider_error`\n- `status_check_exhausted`\n- two that only a same-chain `sol` leg can carry, namely\n  - `market_maker_rejected` (the market maker refused the fill: re-quote, possibly at\n    another size)\n  - `not_landed` (the transaction was reported as failing to land; whether it can still\n    land later is not established, so when the leg carries a `tx_hash`, check it before\n    trading the same size again; a wallet short of the token the leg spends also ends\n    here, since its balance is not checked before sending)\n- one that only a `user_operation` leg can carry, namely\n  - `sponsorship_rejected` (your paymaster refused to sponsor the op: deposit, stake,\n    rate limit, policy signature or a paymaster revert; nothing was submitted;\n    re-sponsor and re-sign)\n- five that a speed-route leg can carry, all but `swap_reverted` only there, namely\n  - `nonce_conflict` (another transaction from this wallet took the nonce: wait for the\n    earlier trade to go terminal, then re-quote)\n  - `insufficient_native_gas` (the signed `gas × fee` exceeds the wallet's native\n    balance: fund it, then re-quote)\n  - `swap_reverted` (the swap reverted in simulation or on chain; nothing was spent on a\n    simulation revert; re-quote; a same-chain `sol` leg carries it too, when the\n    transaction was reported as failed by the execution venue with an on-chain program\n    error; its signature is on `tx_hash`)\n  - `tx_dropped` (accepted by the node, then evicted without mining: re-quote and\n    re-sign)\n  - `approve_failed` (a bundled `approve` reverted, or did not land within 10 minutes,\n    so the swap was never sent: re-quote; if the approve did mine, the new quote is\n    single-payload).\n\nOn any pair whose swap was never sent (`approve_failed`, and a `nonce_conflict` /\n`provider_error` refused at the approve send), `tx_hash` is `null`, because the swap\nhash the leg named never reached a node. `provider_error` now also covers a speed-route\npre-flight or transport failure; nothing was broadcast, so re-quoting is safe.\n\nFive more that only a `priority:\"speed\"` **cross-chain** leg (`origin_chain` present on\nthe quote) can carry:\n\n- `quote_stale` (the sol origin's deposit blockhash expired before broadcast; nothing\n  left the wallet, so re-quote; distinct from the top-level `410 quote_stale` at submit,\n  which fires before any leg's bytes leave at all)\n- `deposit_reverted` (the EVM origin's deposit reverted past the retry window: re-quote)\n- `refunded` (the cross-chain intent could not fill and the deposit was returned to your\n  origin wallet, so no token was bought; re-quote)\n- `delivered_other_currency` (terminal: you were delivered a stablecoin instead of the\n  destination token; nothing to retry)\n- `cross_chain_unsettled` (6 hours passed with no terminal outcome after the deposit\n  left your wallet: **do not re-quote**; it may still fill or refund on the origin, and\n  a late fill is healed automatically).\n\nTreat an unrecognised value as \"failed, reason unknown\".\n"
          }
        }
      },
      "FailedLeg": {
        "type": "object",
        "required": [
          "quote_index",
          "error_code"
        ],
        "properties": {
          "quote_index": {
            "type": "integer",
            "minimum": 0
          },
          "error_code": {
            "type": "string",
            "enum": [
              "internal_error"
            ]
          }
        }
      },
      "TradeSubmitResponse": {
        "type": "object",
        "required": [
          "results",
          "failed_legs"
        ],
        "properties": {
          "results": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/LegResult"
            }
          },
          "failed_legs": {
            "type": "array",
            "description": "Empty on the full-success path; populated only when a partial broadcast hit an invariant break.",
            "items": {
              "$ref": "#/components/schemas/FailedLeg"
            }
          }
        }
      },
      "TradeSubmitBatchRequest": {
        "type": "object",
        "required": [
          "submissions"
        ],
        "properties": {
          "submissions": {
            "type": "array",
            "minItems": 1,
            "maxItems": 25,
            "description": "One `POST /trade/submit` body each. No `quote_id` may appear twice.",
            "items": {
              "$ref": "#/components/schemas/TradeSubmitRequest"
            }
          }
        },
        "additionalProperties": false
      },
      "TradeSubmitBatchUnsupportedLeg": {
        "type": "object",
        "description": "`422`, `error` is `batch_leg_unsupported`.",
        "required": [
          "error",
          "quote_index"
        ],
        "properties": {
          "error": {
            "type": "string",
            "enum": [
              "batch_leg_unsupported"
            ]
          },
          "quote_index": {
            "type": "integer",
            "minimum": 0
          }
        }
      },
      "TradeSubmitBatchNotStarted": {
        "type": "object",
        "description": "`503`, `error` is `batch_deadline_exceeded`. Nothing was sent.",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string",
            "enum": [
              "batch_deadline_exceeded"
            ]
          }
        }
      },
      "TradeSubmitBatchResult": {
        "type": "object",
        "required": [
          "quote_id",
          "http_status",
          "response"
        ],
        "properties": {
          "quote_id": {
            "type": "string"
          },
          "http_status": {
            "type": "integer",
            "description": "The status `POST /trade/submit` would have answered for this submission."
          },
          "response": {
            "description": "- The body `POST /trade/submit` would have answered (body only, never headers)\n- `TradeSubmitBatchUnsupportedLeg` (422)\n- `TradeSubmitBatchNotStarted` (503)\n- `{ \"error\": \"internal_error\" }` (500).",
            "anyOf": [
              {
                "$ref": "#/components/schemas/TradeSubmitResponse"
              },
              {
                "$ref": "#/components/schemas/TradeSubmitBatchUnsupportedLeg"
              },
              {
                "$ref": "#/components/schemas/TradeSubmitBatchNotStarted"
              },
              {
                "$ref": "#/components/schemas/LegAlreadySubmittedError"
              },
              {
                "$ref": "#/components/schemas/InvalidRequestError"
              },
              {
                "$ref": "#/components/schemas/SimpleErrorWithMessage"
              },
              {
                "$ref": "#/components/schemas/SimpleError"
              }
            ]
          }
        }
      },
      "TradeSubmitBatchResponse": {
        "type": "object",
        "required": [
          "results"
        ],
        "properties": {
          "results": {
            "type": "array",
            "description": "One per submission, in request order.",
            "items": {
              "$ref": "#/components/schemas/TradeSubmitBatchResult"
            }
          }
        }
      },
      "BridgeChain": {
        "type": "string",
        "description": "Any pair of distinct chains. `bnb` answers `400 unsupported_route` on a deployment\nwithout a BNB Chain endpoint. `robinhood` settles in USDG, so a bridge to or from it\nis a USDC↔USDG swap as well as a bridge.\n",
        "enum": [
          "sol",
          "eth",
          "robinhood",
          "base",
          "arbitrum",
          "bnb"
        ]
      },
      "BridgeQuoteRequest": {
        "type": "object",
        "required": [
          "from_chain",
          "to_chain",
          "amount_usdc",
          "max_slippage_bps",
          "eth_wallet",
          "ownership_proof"
        ],
        "properties": {
          "from_chain": {
            "$ref": "#/components/schemas/BridgeChain"
          },
          "to_chain": {
            "$ref": "#/components/schemas/BridgeChain"
          },
          "amount_usdc": {
            "allOf": [
              {
                "$ref": "#/components/schemas/UsdcHumanAmount"
              },
              {
                "description": "Capped at the server-configured `BRIDGE_MAX_AMOUNT_USDC`."
              }
            ]
          },
          "max_slippage_bps": {
            "$ref": "#/components/schemas/SlippageBps"
          },
          "sol_wallet": {
            "allOf": [
              {
                "$ref": "#/components/schemas/SolAddress"
              },
              {
                "description": "Required when either side is `sol`; omit it on an EVM-to-EVM bridge."
              }
            ]
          },
          "eth_wallet": {
            "allOf": [
              {
                "$ref": "#/components/schemas/EvmAddress"
              },
              {
                "description": "The wallet on every EVM side (one address serves all EVM chains)."
              }
            ]
          },
          "ownership_proof": {
            "allOf": [
              {
                "$ref": "#/components/schemas/OwnershipProof"
              },
              {
                "description": "`eth_signature` is always required; `sol_signature` is required whenever\n`sol_wallet` is sent.\n"
              }
            ]
          },
          "delivery": {
            "type": "string",
            "enum": [
              "self_broadcast",
              "submit"
            ],
            "default": "self_broadcast",
            "description": "`self_broadcast`: you broadcast what you sign. `submit`: you hand it to\n`POST /bridge/{bridge_quote_id}/submit`, the only way to execute it; from an EVM\norigin the payload is `evm_permit_typed_data` and needs no native gas.\n"
          }
        },
        "additionalProperties": false
      },
      "BridgeCostBreakdownBps": {
        "type": "object",
        "required": [
          "swap_slippage_bps",
          "gas_fee_bps",
          "bridge_fee_bps",
          "total_bps"
        ],
        "properties": {
          "swap_slippage_bps": {
            "type": "integer"
          },
          "gas_fee_bps": {
            "type": "integer"
          },
          "bridge_fee_bps": {
            "type": "integer"
          },
          "total_bps": {
            "type": "integer"
          }
        }
      },
      "BridgeCostBreakdownUsdc": {
        "type": "object",
        "required": [
          "swap_slippage_usdc",
          "gas_fee_usdc",
          "bridge_fee_usdc",
          "total_usdc"
        ],
        "properties": {
          "swap_slippage_usdc": {
            "$ref": "#/components/schemas/DecimalString"
          },
          "gas_fee_usdc": {
            "$ref": "#/components/schemas/DecimalString"
          },
          "bridge_fee_usdc": {
            "$ref": "#/components/schemas/DecimalString"
          },
          "total_usdc": {
            "$ref": "#/components/schemas/DecimalString"
          }
        }
      },
      "BridgeSignableEvmPayload": {
        "type": "object",
        "required": [
          "type",
          "from",
          "tx_base64",
          "tx_hex",
          "approval_spender"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "evm_eip1559_tx"
            ]
          },
          "from": {
            "$ref": "#/components/schemas/EvmAddress"
          },
          "tx_base64": {
            "type": "string"
          },
          "tx_hex": {
            "type": "string"
          },
          "approval_spender": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/EvmAddress"
              },
              {
                "type": "null"
              }
            ],
            "description": "ERC-20 spender to approve USDC to before broadcasting. Null when the\ncalldata needs no allowance.\n"
          }
        }
      },
      "BridgeSignableSolanaPayload": {
        "type": "object",
        "required": [
          "type",
          "tx_base64",
          "blockhash",
          "last_valid_block_height"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "solana_versioned_tx"
            ]
          },
          "tx_base64": {
            "type": "string"
          },
          "blockhash": {
            "type": "string"
          },
          "last_valid_block_height": {
            "type": "integer"
          }
        }
      },
      "BridgeSignablePermitPayload": {
        "type": "object",
        "description": "`delivery: submit` from an EVM origin. Sign each `typed_data` (as\n`eth_signTypedData_v4` takes it) in order and send the signatures to\n`POST /bridge/{bridge_quote_id}/submit`. Each authorizes moving `amount_in_usdc` of the\norigin's base token once, to the bridge's settlement contract, for about ten minutes; sign\nit as given (its domain or type names may name that contract).\n",
        "required": [
          "type",
          "chain_id",
          "approval_tx",
          "signatures"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "evm_permit_typed_data"
            ]
          },
          "chain_id": {
            "type": "integer"
          },
          "approval_tx": {
            "description": "A one-time token approval your own wallet sends before signing, on tokens without a\nbuilt-in permit. Null on every origin offered today.\n",
            "oneOf": [
              {
                "type": "object",
                "required": [
                  "to",
                  "data",
                  "value",
                  "chain_id"
                ],
                "properties": {
                  "to": {
                    "$ref": "#/components/schemas/EvmAddress"
                  },
                  "data": {
                    "type": "string"
                  },
                  "value": {
                    "type": "string"
                  },
                  "chain_id": {
                    "type": "integer"
                  }
                },
                "additionalProperties": false
              },
              {
                "type": "null"
              }
            ]
          },
          "signatures": {
            "type": "array",
            "minItems": 1,
            "items": {
              "type": "object",
              "required": [
                "typed_data"
              ],
              "properties": {
                "typed_data": {
                  "type": "object",
                  "required": [
                    "domain",
                    "types",
                    "primaryType",
                    "message"
                  ],
                  "properties": {
                    "domain": {
                      "type": "object"
                    },
                    "types": {
                      "type": "object"
                    },
                    "primaryType": {
                      "type": "string"
                    },
                    "message": {
                      "type": "object"
                    }
                  }
                }
              },
              "additionalProperties": false
            }
          }
        }
      },
      "BridgeSignablePayload": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/BridgeSignableEvmPayload"
          },
          {
            "$ref": "#/components/schemas/BridgeSignableSolanaPayload"
          },
          {
            "$ref": "#/components/schemas/BridgeSignablePermitPayload"
          }
        ],
        "discriminator": {
          "propertyName": "type",
          "mapping": {
            "evm_eip1559_tx": "#/components/schemas/BridgeSignableEvmPayload",
            "solana_versioned_tx": "#/components/schemas/BridgeSignableSolanaPayload",
            "evm_permit_typed_data": "#/components/schemas/BridgeSignablePermitPayload"
          }
        }
      },
      "BridgeQuoteResponse": {
        "type": "object",
        "required": [
          "bridge_quote_id",
          "expires_at",
          "amount_in_usdc",
          "estimated_amount_out_usdc",
          "max_slippage_bps",
          "cost_breakdown_bps",
          "cost_breakdown_usdc",
          "signable_payload"
        ],
        "properties": {
          "bridge_quote_id": {
            "type": "string",
            "pattern": "^brq_[A-Za-z0-9_-]{21}$"
          },
          "expires_at": {
            "type": "integer"
          },
          "amount_in_usdc": {
            "$ref": "#/components/schemas/UsdcHumanAmount"
          },
          "estimated_amount_out_usdc": {
            "$ref": "#/components/schemas/DecimalString"
          },
          "max_slippage_bps": {
            "type": "integer"
          },
          "cost_breakdown_bps": {
            "$ref": "#/components/schemas/BridgeCostBreakdownBps"
          },
          "cost_breakdown_usdc": {
            "$ref": "#/components/schemas/BridgeCostBreakdownUsdc"
          },
          "signable_payload": {
            "$ref": "#/components/schemas/BridgeSignablePayload"
          }
        }
      },
      "BridgeStatusResponse": {
        "type": "object",
        "required": [
          "bridge_quote_id",
          "status",
          "source_tx_hash",
          "destination_tx_hash",
          "updated_at"
        ],
        "properties": {
          "bridge_quote_id": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "completed",
              "failed"
            ]
          },
          "source_tx_hash": {
            "type": [
              "string",
              "null"
            ]
          },
          "destination_tx_hash": {
            "type": [
              "string",
              "null"
            ]
          },
          "updated_at": {
            "type": "integer"
          }
        }
      },
      "BridgeSubmitRequest": {
        "type": "object",
        "description": "Exactly one of `signatures` (EVM origin) or `signed_tx` (Solana origin).",
        "properties": {
          "signatures": {
            "type": "array",
            "minItems": 1,
            "maxItems": 4,
            "items": {
              "type": "string",
              "maxLength": 132
            },
            "description": "One 65-byte signature (0x-hex) per `signable_payload.signatures[]` item, in the same\norder, by `eth_wallet`.\n"
          },
          "signed_tx": {
            "type": "string",
            "maxLength": 65536,
            "description": "The `signable_payload` Solana transaction signed by `sol_wallet`, as base64, with its\nmessage byte-for-byte unchanged (a wallet that adds instructions is refused).\n"
          }
        },
        "additionalProperties": false
      },
      "BridgeSubmitResponse": {
        "type": "object",
        "required": [
          "bridge_quote_id",
          "status",
          "source_tx_hash"
        ],
        "properties": {
          "bridge_quote_id": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "submitted"
            ]
          },
          "source_tx_hash": {
            "type": [
              "string",
              "null"
            ],
            "description": "The Solana signature. Null from an EVM origin: the deposit is sent moments later and\nappears in `GET /bridge/{bridge_quote_id}/status`.\n"
          }
        }
      },
      "PortfolioPosition": {
        "type": "object",
        "required": [
          "ticker",
          "token_ticker",
          "chain",
          "protocol",
          "token_address",
          "tokens",
          "shares",
          "usd_per_token",
          "usd_per_share",
          "usd_value",
          "shares_internal_only",
          "avg_entry_price_per_share",
          "unrealized_pnl"
        ],
        "properties": {
          "ticker": {
            "$ref": "#/components/schemas/Ticker"
          },
          "token_ticker": {
            "type": "string"
          },
          "chain": {
            "$ref": "#/components/schemas/Chain"
          },
          "protocol": {
            "$ref": "#/components/schemas/Protocol"
          },
          "token_address": {
            "type": "string"
          },
          "tokens": {
            "$ref": "#/components/schemas/DecimalString"
          },
          "shares": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/DecimalString"
              },
              {
                "type": "null"
              }
            ]
          },
          "usd_per_token": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/DecimalString"
              },
              {
                "type": "null"
              }
            ]
          },
          "usd_per_share": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/DecimalString"
              },
              {
                "type": "null"
              }
            ]
          },
          "usd_value": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/DecimalString"
              },
              {
                "type": "null"
              }
            ]
          },
          "shares_internal_only": {
            "description": "Equity shares acquired via Treasures and still held (internal lot). Populated only with `source=internal`; null in `all` mode and when the cell has no share multiplier.",
            "oneOf": [
              {
                "$ref": "#/components/schemas/DecimalString"
              },
              {
                "type": "null"
              }
            ]
          },
          "avg_entry_price_per_share": {
            "description": "Weighted-average cost basis per share of the internal lot. Populated only with `source=internal`; null otherwise.",
            "oneOf": [
              {
                "$ref": "#/components/schemas/DecimalString"
              },
              {
                "type": "null"
              }
            ]
          },
          "unrealized_pnl": {
            "description": "internal_tokens × usd_per_token − internal cost. Populated only with `source=internal` and when a spot price exists; null otherwise.",
            "oneOf": [
              {
                "$ref": "#/components/schemas/DecimalString"
              },
              {
                "type": "null"
              }
            ]
          },
          "tradability": {
            "$ref": "#/components/schemas/Tradability",
            "description": "Probe warning for the exact `(ticker, protocol, chain)` cell this position names, filtered to the sell side. Published only when `warn_reason` is side-neutral (see below), so a position carries all three keys or none. **Advisory, never a block**: it never marks a holding unsellable. `min_trade_size_usd` is never published on a position: it is a USD buy floor while a sell is denominated in shares. Absent means unmeasured, unwarned, or buy-sided, never healthy-with-value-null."
          },
          "warn_reason": {
            "$ref": "#/components/schemas/SideNeutralWarnReason",
            "description": "Why the held cell is warned. **Positions carry only the side-neutral reasons**: `low_volume`, `no_price_feed` and `no_settlements`. The buy-sided reasons (`no_fill_window`, `settlement_failure`) say nothing about an exit and suppress the whole trio, as does a warn whose reason was never recorded."
          },
          "thin_since": {
            "$ref": "#/components/schemas/ThinSince"
          }
        }
      },
      "PortfolioResponse": {
        "type": "object",
        "required": [
          "positions",
          "usdc",
          "usdg",
          "partial",
          "as_of",
          "is_cached"
        ],
        "properties": {
          "positions": {
            "type": "array",
            "description": "The sol/eth positions are read on-chain against the reconciler ledger. Positions on the\ntwo single-cell venues, Robinhood Chain (4663) and Base (8453), are read for every\nwallet Treasures knows on any chain, snapshotted for 30 s (invalidated the moment a\ntrade on that venue settles).\n\nAn `eth_wallet` that is not in Treasures's own custody, is not a B2C wallet, and has no\nB2B ledger row anywhere gets an empty `positions` list here with no RPC, and is not\nflagged `partial`. For a KNOWN wallet there is no trade-history gate on top of that: a\ntoken transferred into your own EOA from outside shows exactly like one bought through\nthis API.\n\n**Idle cash on these two venues (`usdc.base`, `usdg.robinhood`) is never gated**; it\nstill reads live even for an unknown wallet, so a wallet holding only cash still reports\nit.\n\nBNB Smart Chain (56) positions are read the same way, off the same EOA. On `bnb` a\nposition's `protocol` is one of `ondo`, `xstocks` or `bstocks`: like `sol` and `eth`, 56\ncarries more than one, so do not infer `protocol` from `chain`. Positions and `usdc.bnb`\nare reported **even while the bnb venue is closed**: a portfolio reports what a wallet\nholds.\n",
            "items": {
              "$ref": "#/components/schemas/PortfolioPosition"
            }
          },
          "usdc": {
            "type": "object",
            "description": "Idle USDC per chain.\n\n- ⚠ **`base` is Base-native USDC on 8453, a DIFFERENT contract from mainnet USDC.** It is\n  read from the caller's own 8453 EOA (keyed on `eth_wallet`) through its own 30 s\n  snapshot that a settled trade invalidates (exactly like `usdg.robinhood`), not from\n  the sol/eth reconciler. A failed read is never cached. `base` is `\"0\"` when no\n  `eth_wallet` is supplied, no B20 cell is listed in the catalog, or the 8453 read\n  fails.\n- `arbitrum` is Arbitrum-native USDC on 42161, read the same way from the caller's own\n  42161 EOA, and is `\"0\"` when no `eth_wallet` is supplied, no Arbitrum cell is listed,\n  or the 42161 read fails.\n- `bnb` is **Binance-Peg USDC on BNB Smart Chain (56): 18 decimals, and not a Circle\n  deploy at all** (BSC has none). It is reported under the `usdc` name for wire\n  compatibility; converting it to Circle USDC costs roughly 31 bps inbound and 7 to 9\n  bps outbound, a cross-chain swap rather than a transfer. The value here is\n  human-decimal, so the 18-dp scale does not leak into this field. It is read the same\n  way from the caller's own 56 EOA, is `\"0\"` when no `eth_wallet` is supplied, no bnb\n  cell is listed, or the 56 read fails, and is reported even while the bnb venue is\n  closed.\n\nThe five keys are five different tokens: never pool them.\n",
            "required": [
              "sol",
              "eth",
              "base",
              "arbitrum",
              "bnb"
            ],
            "properties": {
              "sol": {
                "$ref": "#/components/schemas/DecimalString"
              },
              "eth": {
                "$ref": "#/components/schemas/DecimalString"
              },
              "base": {
                "$ref": "#/components/schemas/DecimalString"
              },
              "arbitrum": {
                "$ref": "#/components/schemas/DecimalString"
              },
              "bnb": {
                "$ref": "#/components/schemas/DecimalString"
              }
            }
          },
          "usdg": {
            "type": "object",
            "description": "Base-currency cash on Robinhood Chain (4663): the venue's USDG, the 4663 analog of `usdc`. Read from the caller's own 4663 EOA (keyed on `eth_wallet`) through a 30 s snapshot that a settled trade invalidates, so a post-trade read reflects the new cash rather than waiting out the TTL. A failed read is never cached. `\"0\"` when no `eth_wallet` is supplied, the Robinhood venue is dormant, or the 4663 read fails.",
            "required": [
              "robinhood"
            ],
            "properties": {
              "robinhood": {
                "$ref": "#/components/schemas/DecimalString"
              }
            }
          },
          "partial": {
            "type": "boolean",
            "description": "`true` when a balance read failed on this pass, so `positions` omits cells the wallet\nmay hold and any sum over `usd_value` undercounts. Covers **every** position source: an\nunreadable sol/eth cell, and an unreadable cell on any EOA-read venue chain (Robinhood\nChain 4663, Base 8453, Arbitrum One 42161, BNB Smart Chain 56).\n\nCash is not covered; `usdc`/`usdg` fault-isolate to `\"0\"` independently, since a failed\nread there is indistinguishable from a real zero.\n\nRetry for a complete answer; the response is otherwise a normal 200. May be `true`\nalongside `is_cached: true`; the cells were unreadable when the snapshot was taken.\n"
          },
          "as_of": {
            "type": "integer",
            "description": "Unix seconds: when this snapshot was actually computed, so it is always the true age of the data. Reads are served from a snapshot that is refreshed in the background once it passes 30 s and recomputed inline past 5 minutes, so `as_of` can trail the request by **up to 5 minutes**. A settled trade invalidates the snapshot, so a post-trade read always recomputes rather than replaying a pre-trade view. Check `as_of` if your use case needs a tighter bound."
          },
          "is_cached": {
            "type": "boolean",
            "description": "`true` when the response was served from an existing snapshot rather than a fresh on-chain read. Says nothing about how old it is; use `as_of` for that."
          }
        }
      },
      "TradeEntry": {
        "type": "object",
        "required": [
          "trade_id",
          "source",
          "side",
          "ticker",
          "token_ticker",
          "chain",
          "protocol",
          "tx_hash",
          "order_hash",
          "tokens",
          "shares",
          "usdc_amount",
          "usd_per_share",
          "avg_entry_price_per_share",
          "realized_pnl",
          "submitted_at",
          "status"
        ],
        "properties": {
          "trade_id": {
            "type": "string"
          },
          "source": {
            "type": "string",
            "enum": [
              "internal",
              "external"
            ]
          },
          "side": {
            "oneOf": [
              {
                "type": "string",
                "enum": [
                  "buy",
                  "sell"
                ]
              },
              {
                "type": "null"
              }
            ]
          },
          "ticker": {
            "$ref": "#/components/schemas/Ticker"
          },
          "token_ticker": {
            "type": "string"
          },
          "chain": {
            "$ref": "#/components/schemas/Chain"
          },
          "protocol": {
            "$ref": "#/components/schemas/Protocol"
          },
          "tx_hash": {
            "type": [
              "string",
              "null"
            ]
          },
          "order_hash": {
            "type": [
              "string",
              "null"
            ]
          },
          "payout_chain": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Chain"
              }
            ],
            "description": "**Cross-chain sells only** (quoted with `payout_chain`; absent on every other row): the chain this sale's USDC lands on, as on the `/quote/{quote_id}/status` leg (so `bnb` when a `bnb/bstocks` sale's USDC was returned on `bnb`). `tx_hash` stays the sale on `chain`, and `usdc_amount` is the USDC that landed."
          },
          "payout_tx_hash": {
            "type": [
              "string",
              "null"
            ],
            "description": "Present with `payout_chain`: the transaction on `payout_chain` that paid the USDC out. `null` unless the row is `completed`."
          },
          "tokens": {
            "$ref": "#/components/schemas/DecimalString"
          },
          "shares": {
            "$ref": "#/components/schemas/DecimalString"
          },
          "usdc_amount": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/DecimalString"
              },
              {
                "type": "null"
              }
            ]
          },
          "usd_per_share": {
            "description": "This row's settled execution price (usdc_amount / shares). Populated only with `source=internal` on completed rows; null in `all` mode, on non-completed (in-flight/failed/external) rows, and when usdc_amount is null.",
            "oneOf": [
              {
                "$ref": "#/components/schemas/DecimalString"
              },
              {
                "type": "null"
              }
            ]
          },
          "avg_entry_price_per_share": {
            "description": "Running internal weighted-average cost basis per share at this row. Populated only with `source=internal`; null on non-internal rows.",
            "oneOf": [
              {
                "$ref": "#/components/schemas/DecimalString"
              },
              {
                "type": "null"
              }
            ]
          },
          "realized_pnl": {
            "description": "Realized P&L for a closing internal sell: (px − avg_entry) × closed shares, gross of fees (Hyperliquid closedPnl parity). Populated only with `source=internal`; null on buys, oversell-uncovered, and non-internal rows.",
            "oneOf": [
              {
                "$ref": "#/components/schemas/DecimalString"
              },
              {
                "type": "null"
              }
            ]
          },
          "submitted_at": {
            "type": "integer"
          },
          "status": {
            "type": "string",
            "enum": [
              "completed",
              "broadcast",
              "failed",
              "external"
            ]
          }
        }
      },
      "TradesResponse": {
        "type": "object",
        "required": [
          "trades",
          "next_offset"
        ],
        "properties": {
          "trades": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TradeEntry"
            }
          },
          "next_offset": {
            "oneOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "description": "Pass back as `offset` to fetch the next page; `null` when there are no more rows."
          }
        }
      },
      "SettlementToken": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "address",
          "symbol",
          "name",
          "price_usd",
          "price_usd_per_share"
        ],
        "properties": {
          "address": {
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Mint (Solana) or contract address (EVM) of this leg's token. `null` in the rare case where the catalog entry for the ticker is unavailable; the trade is still returned, since omitting a settled fill would understate your volume."
          },
          "symbol": {
            "type": "string",
            "description": "Wrapped-token symbol, e.g. `AAPLon` / `AAPLx`, or `USDC` / `USDG`."
          },
          "name": {
            "type": "string"
          },
          "price_usd": {
            "type": "string",
            "description": "Realized execution price for this leg, derived from the fill itself, not a market quote. Quoted per unit of THIS leg's token, matching `amount`/`tokens`; see `price_usd_per_share` for the equity-denominated figure. `1` on the stablecoin leg, which is the accounting unit. Truncated to 12 decimal places."
          },
          "price_usd_per_share": {
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "The same realized fill priced per equity share rather than per token; `amount_usd ÷ shares`, truncated to 12 decimal places. Prefer this when comparing against a market or tradfi reference: on the rebase venues (xStocks on Ethereum and BNB Smart Chain) `price_usd` is a price per conserved internal unit and so matches no market quote, while this figure is comparable across venues and chains. The two coincide wherever the share multiplier is 1. `null` on the stablecoin leg, which has no share denomination, and on the rare fill whose `shares` floor to zero."
          }
        }
      },
      "SettlementLeg": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "tx_hash",
          "tx_link",
          "chain",
          "timestamp",
          "amount",
          "transfer_amount",
          "tokens",
          "token"
        ],
        "properties": {
          "tx_hash": {
            "type": "string",
            "description": "On-chain hash of this leg's transfer, on this leg's `chain`. Identical on both legs of a single-chain swap. On a sell paid out on another chain (or returned on the sale's own chain) the stock leg's hash is the sale and the USDC leg's is the payout."
          },
          "tx_link": {
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Block-explorer link, or `null` where no explorer is published for the chain (Robinhood Chain). The hash is still returned."
          },
          "chain": {
            "$ref": "#/components/schemas/Chain"
          },
          "timestamp": {
            "type": "integer",
            "description": "Settlement time, unix seconds."
          },
          "amount": {
            "type": "string",
            "description": "Raw integer base units of this leg's token."
          },
          "transfer_amount": {
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Raw integer base units as they appear in the on-chain transfer: the figure a block\nexplorer renders. Equal to `amount` on every venue except xStocks on Ethereum and\nBNB Smart Chain, whose token rebases: there the contract emits BOTH a standard ERC-20\n`Transfer` (carrying this value) and a shares-transfer event (carrying `amount`, the\nconserved internal unit). Both are on-chain; they differ by the share multiplier, and\nan explorer shows only the first. Reconcile explorer-visible movement on this field and\ninternal accounting on `amount`.\n\nThe byte-exact match to an explorer is an EVM property: on Solana Token-2022 ScaledUI\ncells the transfer instruction carries the value reported here, but some explorers\nrender a display-scaled figure instead.\n\nThis is the raw movement on THIS leg, not a gross notional. Whether `fee_costs` has\nalready been netted out of the stablecoin leg is venue-dependent, so do not assume\neither way:\n\n- on a buy it is the full amount spent\n- on an Ethereum/Robinhood sell the venue skims its fee from this leg, so the figure is\n  already net and IS the wallet credit\n- on a Solana sell the referral fee is collected in a separate transfer, so the figure\n  sits above the credit by the disclosed bps\n- on a sell paid out on another chain it is the payout transfer itself, so already net\n  and IS the wallet credit.\n\nSumming `transfer_amount + fee_costs` therefore does NOT give a consistent total across\nchains.\n\n`null` only for a rebasing trade settled before this field was recorded; no backfill is\npossible, so treat `null` as unknown, never as zero.\n"
          },
          "tokens": {
            "type": "string",
            "description": "`amount` in human-readable units. Provided because the token's decimal precision is not part of this contract; do not hardcode a scale."
          },
          "token": {
            "$ref": "#/components/schemas/SettlementToken"
          }
        }
      },
      "AccruedIntegratorFees": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "amount_usd",
          "trade_count",
          "payout_chain",
          "payout_address",
          "previous_payout_address",
          "payout_address_updated_at",
          "payouts_enabled",
          "minimum_usd",
          "maximum_usd",
          "next_eligible_at"
        ],
        "properties": {
          "amount_usd": {
            "type": "string",
            "description": "Owed to you now, in USD at 6 dp, truncated.",
            "example": "412.300000"
          },
          "trade_count": {
            "type": "integer"
          },
          "payout_chain": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "sol",
              "base",
              null
            ],
            "description": "The chain payouts are sent on. `null` until Treasures registers an address."
          },
          "payout_address": {
            "type": [
              "string",
              "null"
            ],
            "description": "The one address payouts go to. EVM addresses are EIP-55 checksummed."
          },
          "previous_payout_address": {
            "type": [
              "string",
              "null"
            ],
            "description": "The address the last change replaced; `null` if it has never changed."
          },
          "payout_address_updated_at": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Unix seconds of the last registration or change."
          },
          "payouts_enabled": {
            "type": "boolean",
            "description": "Whether `POST /payouts` is open on this environment."
          },
          "minimum_usd": {
            "type": "string",
            "description": "The smallest payout `POST /payouts` makes."
          },
          "maximum_usd": {
            "type": "string",
            "description": "The largest payout `POST /payouts` makes; above it, Treasures pays on request."
          },
          "next_eligible_at": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Unix seconds before which `POST /payouts` will refuse (cooldown or address hold); `null` when nothing is waiting."
          }
        }
      },
      "Payout": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "payout_id",
          "status",
          "amount_usd",
          "trade_count",
          "chain",
          "to_address",
          "tx_hash",
          "created_at",
          "paid_at"
        ],
        "properties": {
          "payout_id": {
            "type": "string",
            "example": "ipo_V1StGXR8Z5jdHi6BmyT2k9"
          },
          "status": {
            "type": "string",
            "enum": [
              "processing",
              "paid",
              "failed",
              "cancelled"
            ],
            "description": "- `processing`: created or sent, not yet final.\n- `paid`: final (see `tx_hash`).\n- `failed`: the transfer did not happen; its fees are owed to you again.\n- `cancelled`: withdrawn before sending; its fees went back into what you are owed."
          },
          "amount_usd": {
            "type": "string",
            "description": "Sum of the `integrator_fee` entries it covers, exactly as `/settlements` reports each one (`GET /settlements?payout_id=…`)."
          },
          "trade_count": {
            "type": "integer"
          },
          "chain": {
            "type": [
              "string",
              "null"
            ],
            "description": "The chain it is paid on; `null` on a payout cut before an address was registered, until paid."
          },
          "to_address": {
            "type": [
              "string",
              "null"
            ]
          },
          "tx_hash": {
            "type": [
              "string",
              "null"
            ],
            "description": "The transfer. On Solana it is known as soon as the payout is sent (while `processing`); on Base once it lands."
          },
          "created_at": {
            "type": "integer",
            "description": "Unix seconds."
          },
          "paid_at": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Unix seconds; `null` until paid."
          }
        }
      },
      "PayoutsResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "data",
          "next_cursor",
          "has_more"
        ],
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Payout"
            }
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ]
          },
          "has_more": {
            "type": "boolean"
          }
        }
      },
      "SignalSourceKind": {
        "type": "string",
        "enum": [
          "congressional_disclosure",
          "institutional_13f",
          "media_inverse",
          "social_account",
          "manager_published"
        ],
        "description": "What the strategy's book is derived from.\n\n- `congressional_disclosure`: a legislator's periodic transaction reports.\n- `institutional_13f`: an institution's quarterly 13F holdings.\n- `media_inverse`: the inverse of a broadcast pundit's calls.\n- `social_account`: a public social-media account's posts.\n- `manager_published`: a fund manager publishes the book to Treasures directly.\n\nNew values may be added; treat an unknown value as opaque."
      },
      "SignalReplication": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "as_of",
          "names_total",
          "names_replicated",
          "skipped_source_weight",
          "universe"
        ],
        "description": "How much of the source portfolio the book carries. A book is the source cut down to the names Treasures can trade on chain and renormalised to them.",
        "properties": {
          "as_of": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Unix seconds of the pass that produced these numbers."
          },
          "names_total": {
            "type": "integer",
            "description": "Positions in the source portfolio."
          },
          "names_replicated": {
            "type": "integer",
            "description": "Positions carried into the book."
          },
          "skipped_source_weight": {
            "type": "string",
            "description": "Decimal share of the source portfolio's weight that the book leaves out."
          },
          "universe": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "chains",
              "buyable_by_chain"
            ],
            "properties": {
              "chains": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "The chains the book was cut against."
              },
              "buyable_by_chain": {
                "type": "object",
                "additionalProperties": {
                  "type": "integer"
                },
                "description": "How many of the source's names each chain could buy."
              }
            }
          }
        }
      },
      "SignalStrategy": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "strategy_id",
          "slug",
          "name",
          "tagline",
          "description",
          "portrait_url",
          "status",
          "source_kind",
          "listed_at",
          "replication"
        ],
        "properties": {
          "strategy_id": {
            "type": "string"
          },
          "slug": {
            "type": [
              "string",
              "null"
            ]
          },
          "name": {
            "type": [
              "string",
              "null"
            ]
          },
          "tagline": {
            "type": [
              "string",
              "null"
            ]
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "portrait_url": {
            "type": [
              "string",
              "null"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "paused",
              "halted"
            ],
            "description": "`active`: new books are expected. `paused` and `halted`: no new books for now; the last one stays readable."
          },
          "source_kind": {
            "$ref": "#/components/schemas/SignalSourceKind"
          },
          "listed_at": {
            "type": "integer",
            "description": "Unix seconds."
          },
          "replication": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/SignalReplication"
              },
              {
                "type": "null"
              }
            ]
          }
        }
      },
      "SignalBookWeight": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "ticker",
          "weight"
        ],
        "properties": {
          "ticker": {
            "type": "string"
          },
          "weight": {
            "type": "string",
            "description": "Decimal fraction of the book, at most 8 decimals."
          }
        }
      },
      "SignalBook": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "signal_id",
          "as_of",
          "book_hash",
          "position_count",
          "deployed_weight",
          "cash_weight",
          "weights"
        ],
        "properties": {
          "signal_id": {
            "type": "string"
          },
          "as_of": {
            "type": "integer",
            "description": "Unix seconds. When Treasures ingested the book, not the filing or disclosure date."
          },
          "book_hash": {
            "type": "string",
            "description": "Hex SHA-256 of the book's contents. Two books with the same weights have the same hash whatever their `signal_id`; compare hashes to detect a change."
          },
          "position_count": {
            "type": "integer"
          },
          "deployed_weight": {
            "type": "string",
            "description": "Decimal sum of the weights."
          },
          "cash_weight": {
            "type": "string",
            "description": "Decimal remainder (one minus `deployed_weight`), never negative."
          },
          "weights": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SignalBookWeight"
            }
          }
        }
      },
      "SignalBookHistoryEntry": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "signal_id",
          "as_of",
          "trading_day",
          "book_hash",
          "position_count",
          "deployed_weight",
          "cash_weight",
          "weights"
        ],
        "properties": {
          "signal_id": {
            "type": "string"
          },
          "as_of": {
            "type": "integer",
            "description": "Unix seconds. When Treasures ingested the book."
          },
          "trading_day": {
            "type": "string",
            "description": "The US trading day (`YYYY-MM-DD`) the book was acted on."
          },
          "book_hash": {
            "type": "string"
          },
          "position_count": {
            "type": "integer"
          },
          "deployed_weight": {
            "type": "string"
          },
          "cash_weight": {
            "type": "string"
          },
          "weights": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SignalBookWeight"
            }
          }
        }
      },
      "SignalCatalogStrategy": {
        "type": "object",
        "description": "A catalog row, `SignalStrategy` plus its latest book's identity.",
        "additionalProperties": false,
        "required": [
          "strategy_id",
          "slug",
          "name",
          "tagline",
          "description",
          "portrait_url",
          "status",
          "source_kind",
          "listed_at",
          "replication",
          "book_hash",
          "book_as_of",
          "signal_id"
        ],
        "properties": {
          "strategy_id": {
            "type": "string"
          },
          "slug": {
            "type": [
              "string",
              "null"
            ]
          },
          "name": {
            "type": [
              "string",
              "null"
            ]
          },
          "tagline": {
            "type": [
              "string",
              "null"
            ]
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "portrait_url": {
            "type": [
              "string",
              "null"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "paused",
              "halted"
            ],
            "description": "As on `SignalStrategy`."
          },
          "source_kind": {
            "$ref": "#/components/schemas/SignalSourceKind"
          },
          "listed_at": {
            "type": "integer",
            "description": "Unix seconds."
          },
          "replication": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/SignalReplication"
              },
              {
                "type": "null"
              }
            ]
          },
          "book_hash": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^[0-9a-f]{64}$",
            "description": "The latest book's `book_hash`; `null` when the strategy has no book yet."
          },
          "book_as_of": {
            "type": [
              "integer",
              "null"
            ],
            "description": "The latest book's `as_of` (unix seconds); `null` with no book."
          },
          "signal_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "The latest book's `signal_id`; `null` with no book."
          }
        }
      },
      "SignalStrategiesResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "data",
          "truncated"
        ],
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SignalCatalogStrategy"
            }
          },
          "truncated": {
            "type": "boolean",
            "description": "`true` when the page cap of 100 cut the catalog short."
          }
        }
      },
      "SignalStrategyDetail": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "strategy",
          "book"
        ],
        "properties": {
          "strategy": {
            "$ref": "#/components/schemas/SignalStrategy"
          },
          "book": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/SignalBook"
              },
              {
                "type": "null"
              }
            ]
          }
        }
      },
      "SignalBookHistoryResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "data",
          "next_cursor",
          "has_more"
        ],
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SignalBookHistoryEntry"
            }
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ]
          },
          "has_more": {
            "type": "boolean"
          }
        }
      },
      "SignalOrdersRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "strategy_id",
          "ownership_proof"
        ],
        "properties": {
          "strategy_id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 64,
            "description": "The strategy's `strategy_id` (stable) or its `slug` (may be renamed)."
          },
          "chain": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/SignalOrderChain"
              },
              {
                "type": "null"
              }
            ],
            "description": "The order venue. null/omitted plans `sol_wallet`'s orders on Solana. `bnb` plans\n`eth_wallet`'s ondo and xStocks positions on BNB Smart Chain (bStocks is never read or\nplanned), on `/exit/plan` and `/rebalance/plan` only: `/exit` and `/rebalance` refuse it\nwith `400 invalid_request` at `chain`.\n\nQuote each planned `bnb` order with `POST /quote/buy` or `POST /quote/sell` pinned to\n`chain: \"bnb\"` and the protocols the plan read (`protocol: [\"ondo\", \"xstocks\"]`, or\nyour own `protocol` pin), and submit each with its own `POST /trade/submit`. An\nunpinned `bnb` quote can route to a cell the plan never read (bStocks).\n\nA `bnb` body needs `eth_wallet` and its `eth_signature`, refuses `sol_wallet`, and a\n`protocol` pin must include `ondo` or `xstocks`; each is a `400 invalid_request` at\nthat field.\n\nOff-hours, xStocks quotes on BNB Smart Chain were measured at a median of about 130 bps\nof price impact and up to about 600 bps, so an xStocks order there may need a\n`max_slippage_bps` near 300 on its quote; ondo measured under 100 bps.\n"
          },
          "sol_wallet": {
            "$ref": "#/components/schemas/SolAddress",
            "description": "Required unless `chain` is `bnb`, where it is refused."
          },
          "eth_wallet": {
            "$ref": "#/components/schemas/EvmAddress",
            "description": "Required when `chain` is `bnb`, and accepted only then: any other body carrying it is refused with `400 invalid_request`."
          },
          "ownership_proof": {
            "$ref": "#/components/schemas/OwnershipProof",
            "description": "The `sol_signature` over the canonical challenge is required, or with `chain: \"bnb\"` the `eth_signature`."
          },
          "tickers": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Ticker"
            },
            "minItems": 1,
            "maxItems": 25,
            "uniqueItems": true,
            "description": "Names to exit beside the book's own, for a position you hold that has since left the book. Each is sold only if held."
          },
          "max_slippage_bps": {
            "$ref": "#/components/schemas/SlippageBps",
            "description": "Optional on `/exit/plan`, required on `/exit`."
          },
          "expected_book_hash": {
            "type": "string",
            "pattern": "^[0-9a-f]{64}$",
            "description": "The `book_hash` you planned against. When sent and the served book differs, the call is refused with `409 book_changed` before the wallet is read or anything is quoted."
          },
          "protocol": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/Protocol"
              },
              {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Protocol"
                },
                "minItems": 1,
                "maxItems": 7,
                "uniqueItems": true
              },
              {
                "type": "null"
              }
            ],
            "description": "Narrows which holdings are read and sold, as on `POST /quote/sell`. null/omitted = every protocol. Must include a protocol the venue reads (on Solana `ondo`, `xstocks` or `backpack`; with `chain: \"bnb\"` `ondo` or `xstocks`), or the request is refused with `400 invalid_request`. A pinned exit covers the pinned venues only: a name also held on another venue is sold from the pinned one alone, with no `skipped` entry for the rest, so repeat the call per venue to exit fully."
          }
        }
      },
      "SignalOrderSkipReason": {
        "type": "string",
        "enum": [
          "leg_cap",
          "not_held",
          "holdings_unknown",
          "below_min_notional",
          "awaiting_sell_proceeds",
          "not_tradable",
          "insufficient_balance",
          "price_unavailable"
        ],
        "description": "- `leg_cap`: more orders than fit: past 25 orders or, on Solana, 30 upstream quote calls\n  (`chain: \"bnb\"` has no quote-call cap). On `/exit` the smallest by notional, unpriced\n  first, are skipped; on `/rebalance` sells are admitted first.\n- `not_held`: no position on the venue (Solana, or with `chain: \"bnb\"` BNB Smart Chain), or\n  one worth under $0.01, or one that floors to zero shares, or a Solana token account that\n  cannot be decoded into a balance (read as zero).\n- `holdings_unknown`: the holding could not be read, so it is never assumed absent (`/exit`\n  only; a rebalance refuses the whole request instead).\n- `below_min_notional`: a rebalance gap under $1. With `chain: \"bnb\"` the floor is the\n  venue's per name: $10 for a name buyable or held on xStocks alone, else $1; it also\n  applies on `/exit/plan`, where a held name worth under its floor is skipped.\n- `awaiting_sell_proceeds`: a rebalance buy `amount_usdc` cannot fund while the plan also\n  sells; call again with the proceeds once the sells settle.\n- `not_tradable`: a book name Treasures cannot buy on the venue (Solana, or with\n  `chain: \"bnb\"` ondo or xStocks on BNB Smart Chain); its weight stays in USDC.\n- `insufficient_balance`: a rebalance buy `amount_usdc` cannot fund, with no sell to wait\n  on.\n- `price_unavailable`: `chain: \"bnb\"` on `/exit/plan` only: a held name with no price, so\n  its venue floor cannot be checked.\n"
      },
      "SignalOrderChain": {
        "type": "string",
        "enum": [
          "bnb"
        ],
        "description": "An order venue other than Solana, on the plan routes only. `bnb` is BNB Smart Chain, read from `eth_wallet`. Only the wallet's `ondo` and `xstocks` tokens are read there: a name held as bStocks reads as `not_held`, so a rebalance buys its full target again, an exit leaves it, and its value is not in `nav_usdc`."
      },
      "SignalOrderApproval": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "token",
          "spender",
          "approval_required"
        ],
        "properties": {
          "token": {
            "type": "string",
            "description": "The token's address on BNB Smart Chain: the Binance-Peg USDC contract on the USDC row, else the held cell's token as the catalog lists it."
          },
          "spender": {
            "type": "string",
            "description": "The router contract a gasless order on BNB Smart Chain pulls the token through."
          },
          "approval_required": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "Whether `eth_wallet`'s allowance to `spender` falls short: for USDC, of `amount_usdc`; for a held token, of the wallet's balance read in the same call. `null` when it could not be read, including a read past its deadline: unknown, never approved, so read the allowance on-chain or approve before signing. Advisory only: no approval is built, and the plan is served either way."
          }
        }
      },
      "SignalOrderSide": {
        "type": "string",
        "enum": [
          "buy",
          "sell"
        ],
        "description": "Every `/exit` order is a sell; a rebalance order is either."
      },
      "SignalOrder": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "ticker",
          "side",
          "shares",
          "notional_usdc"
        ],
        "properties": {
          "ticker": {
            "$ref": "#/components/schemas/Ticker"
          },
          "side": {
            "$ref": "#/components/schemas/SignalOrderSide"
          },
          "shares": {
            "type": [
              "string",
              "null"
            ],
            "description": "A sell's share count, floored to 18 decimal places (the full position on `/exit`). Send as `amount_shares`. `null` on a buy, which is sized by `notional_usdc`."
          },
          "notional_usdc": {
            "type": [
              "string",
              "null"
            ],
            "description": "On a sell, its USD value, or `null` when it could not be priced (`/exit` only). On a buy, the USDC it spends, floored to 6 decimal places; send as `amount_usdc`."
          },
          "quote": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/QuoteSellResponse"
              },
              {
                "$ref": "#/components/schemas/QuoteBuyResponse"
              }
            ],
            "description": "On `/exit` and `/rebalance` only. Exactly the `POST /quote/sell` (or, for a buy, `POST /quote/buy`) answer for this order."
          }
        }
      },
      "SignalOrderSkip": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "ticker",
          "side",
          "reason",
          "detail"
        ],
        "properties": {
          "ticker": {
            "$ref": "#/components/schemas/Ticker"
          },
          "side": {
            "$ref": "#/components/schemas/SignalOrderSide"
          },
          "reason": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/SignalOrderSkipReason"
              },
              {
                "type": "string"
              }
            ],
            "description": "One of `SignalOrderSkipReason`, or, on `/exit` and `/rebalance`, the error code the order's quote route would have answered for that leg."
          },
          "detail": {
            "type": [
              "object",
              "null"
            ],
            "additionalProperties": true,
            "description": "The rest of that order's quote route error body, or `null` when there is none."
          }
        }
      },
      "SignalOrderPlan": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "strategy_id",
          "book_hash",
          "signal_id",
          "as_of",
          "nav_usdc",
          "usdc_available",
          "orders",
          "skipped"
        ],
        "properties": {
          "strategy_id": {
            "type": "string",
            "description": "The canonical id, even when the request named the slug."
          },
          "book_hash": {
            "type": "string",
            "pattern": "^[0-9a-f]{64}$",
            "description": "The book's `book_hash`, as on `GET /signals/strategies/{id}`."
          },
          "signal_id": {
            "type": "string",
            "description": "The served book's `signal_id`, as on `GET /signals/strategies/{id}`."
          },
          "as_of": {
            "type": "integer",
            "description": "Unix seconds. When Treasures ingested the book, not the filing date."
          },
          "nav_usdc": {
            "type": "string",
            "description": "The USD value of the priced names you hold in scope. Unpriced names are excluded."
          },
          "usdc_available": {
            "type": "string",
            "description": "The wallet's Solana USDC, as a decimal string. With `chain: \"bnb\"`, `eth_wallet`'s Binance-Peg USDC on BNB Smart Chain, floored to 6 decimal places."
          },
          "orders": {
            "type": "array",
            "maxItems": 25,
            "items": {
              "$ref": "#/components/schemas/SignalOrder"
            },
            "description": "Largest notional first; unpriced last."
          },
          "skipped": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SignalOrderSkip"
            }
          },
          "approvals": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SignalOrderApproval"
            },
            "description": "`chain: \"bnb\"` only, absent otherwise. One row for USDC when the plan buys, then one per token a planned sell spends. Approve any row that is `true` before submitting its orders, or the order cannot fill. A `null` row is unknown, never approved: read the allowance on-chain, or approve, before signing."
          }
        }
      },
      "SignalOrdersResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "strategy_id",
          "book_hash",
          "signal_id",
          "as_of",
          "nav_usdc",
          "usdc_available",
          "orders",
          "skipped",
          "expires_at",
          "signing_window_sec"
        ],
        "properties": {
          "strategy_id": {
            "type": "string"
          },
          "book_hash": {
            "type": "string",
            "pattern": "^[0-9a-f]{64}$"
          },
          "signal_id": {
            "type": "string"
          },
          "as_of": {
            "type": "integer"
          },
          "nav_usdc": {
            "type": "string"
          },
          "usdc_available": {
            "type": "string"
          },
          "orders": {
            "type": "array",
            "maxItems": 25,
            "items": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/SignalOrder"
                },
                {
                  "required": [
                    "quote"
                  ]
                }
              ]
            }
          },
          "skipped": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SignalOrderSkip"
            }
          },
          "expires_at": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Unix seconds. The earliest `orders[].quote.expires_at`; `null` when no order was quoted. Each quote's own `expires_at` is what `/trade/submit` enforces for it."
          },
          "signing_window_sec": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Seconds from this response until `expires_at`; `null` when no order was quoted."
          }
        }
      },
      "SignalRebalanceRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "strategy_id",
          "ownership_proof"
        ],
        "properties": {
          "strategy_id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 64,
            "description": "The strategy's `strategy_id` (stable) or its `slug` (may be renamed)."
          },
          "chain": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/SignalOrderChain"
              },
              {
                "type": "null"
              }
            ],
            "description": "The order venue. null/omitted plans `sol_wallet`'s orders on Solana. `bnb` plans\n`eth_wallet`'s ondo and xStocks positions on BNB Smart Chain (bStocks is never read or\nplanned), on `/exit/plan` and `/rebalance/plan` only: `/exit` and `/rebalance` refuse it\nwith `400 invalid_request` at `chain`.\n\nQuote each planned `bnb` order with `POST /quote/buy` or `POST /quote/sell` pinned to\n`chain: \"bnb\"` and `protocol: [\"ondo\", \"xstocks\"]`, the protocols the plan read (this\nrequest takes no `protocol`), and submit each with its own `POST /trade/submit`. An\nunpinned `bnb` quote can route to a cell the plan never read (bStocks).\n\nA `bnb` body needs `eth_wallet` and its `eth_signature` and refuses `sol_wallet`; each\nis a `400 invalid_request` at that field.\n\nOff-hours, xStocks quotes on BNB Smart Chain were measured at a median of about 130 bps\nof price impact and up to about 600 bps, so an xStocks order there may need a\n`max_slippage_bps` near 300 on its quote; ondo measured under 100 bps.\n"
          },
          "sol_wallet": {
            "$ref": "#/components/schemas/SolAddress",
            "description": "Required unless `chain` is `bnb`, where it is refused."
          },
          "eth_wallet": {
            "$ref": "#/components/schemas/EvmAddress",
            "description": "Required when `chain` is `bnb`, and accepted only then: any other body carrying it is refused with `400 invalid_request`."
          },
          "ownership_proof": {
            "$ref": "#/components/schemas/OwnershipProof",
            "description": "The `sol_signature` over the canonical challenge is required, or with `chain: \"bnb\"` the `eth_signature`."
          },
          "tickers": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Ticker"
            },
            "minItems": 1,
            "maxItems": 25,
            "uniqueItems": true,
            "description": "Names to bring into scope beside the book's own, for a position you hold that has since left the book. Each has weight zero, so it is sold in full if held."
          },
          "max_slippage_bps": {
            "$ref": "#/components/schemas/SlippageBps",
            "description": "Optional on `/rebalance/plan`, required on `/rebalance`."
          },
          "expected_book_hash": {
            "type": "string",
            "pattern": "^[0-9a-f]{64}$",
            "description": "The `book_hash` you planned against. When sent and the served book differs, the call is refused with `409 book_changed` before the wallet is read or anything is quoted."
          },
          "amount_usdc": {
            "$ref": "#/components/schemas/UsdcHumanAmount",
            "description": "USDC from the wallet to deploy, counted into nav and the only USDC buys may spend. At most `usdc_available`. Omit it for none (`\"0\"` is refused); on the second round of a rebalance, send the smaller of `funding.next_amount_usdc` and `usdc_available`."
          }
        }
      },
      "SignalOrdersBookChangedError": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "error",
          "book_hash"
        ],
        "properties": {
          "error": {
            "type": "string",
            "enum": [
              "book_changed"
            ]
          },
          "book_hash": {
            "type": "string",
            "pattern": "^[0-9a-f]{64}$",
            "description": "The book served now."
          }
        }
      },
      "SignalOrdersInFlightError": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "error",
          "quote_ids"
        ],
        "properties": {
          "error": {
            "type": "string",
            "enum": [
              "orders_in_flight"
            ]
          },
          "quote_ids": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "The earlier call's quotes that are neither final nor five minutes past their expiry; empty while that call is still quoting."
          }
        }
      },
      "SignalOrderRefusalCode": {
        "type": "string",
        "enum": [
          "holdings_unknown",
          "price_unavailable"
        ],
        "description": "`holdings_unknown`: a name in scope could not be read. `price_unavailable`: a held name in scope could not be priced. Either would mis-size every order, so nothing is planned."
      },
      "SignalOrderRefusal": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "error",
          "tickers"
        ],
        "properties": {
          "error": {
            "$ref": "#/components/schemas/SignalOrderRefusalCode"
          },
          "tickers": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Ticker"
            },
            "minItems": 1,
            "description": "The names that caused the refusal."
          }
        }
      },
      "SignalOrderFunding": {
        "type": "object",
        "description": "How `amount_usdc` funds the buys. Buys are scaled pro rata and a scaled buy under $1 is skipped, so a small pool spread over many buys can deploy nothing this round; the whole shortfall then stays in `buys_deferred_usdc`. With `chain: \"bnb\"` a scaled buy is held to its venue floor instead ($10 on a name buyable on xStocks alone), and the pool a skipped buy frees is not spread over the others, so a small account on an xStocks-only book, or a funded rebalance whose floors bind, can plan zero buys with no error; the pool then stays in `buys_deferred_usdc`.",
        "additionalProperties": false,
        "required": [
          "usdc_spendable",
          "buys_required_usdc",
          "buys_scaled",
          "buys_deferred_usdc",
          "buys_deferred_until_sells_settle",
          "next_amount_usdc"
        ],
        "properties": {
          "usdc_spendable": {
            "type": "string",
            "description": "`amount_usdc`, or `\"0\"` when omitted: the only USDC this plan's buys spend. Differs from `usdc_available`, the wallet's whole USDC on the venue (Solana, or with `chain: \"bnb\"` the Binance-Peg USDC on BNB Smart Chain)."
          },
          "buys_required_usdc": {
            "type": "string",
            "description": "Every buy the book asks for, ordered or not, excluding buys under the $1 minimum (`below_min_notional`) and names that cannot be bought (`not_tradable`)."
          },
          "buys_scaled": {
            "type": "boolean",
            "description": "True when buys were scaled down pro rata to fit `usdc_spendable`."
          },
          "buys_deferred_usdc": {
            "type": "string",
            "description": "`buys_required_usdc` less the buys in `orders` (on `/rebalance`, the buys quoted). Not the next round's `amount_usdc`: send `next_amount_usdc`."
          },
          "buys_deferred_until_sells_settle": {
            "type": "boolean",
            "description": "True when some buys are deferred and this plan sells: submit the sells, wait for them to settle, then call again."
          },
          "next_amount_usdc": {
            "type": "string",
            "description": "The next call's `amount_usdc`. The server does not cap it at `usdc_available`, since\nsell proceeds land net of fees and slippage: send the smaller of the two, and omit\n`amount_usdc` when that is `\"0\"`.\n\nIt is `usdc_spendable` plus the sells in `orders`, less the buys in `orders` (on\n`/rebalance`, only the orders quoted, so a refused sell adds nothing and a refused buy\nspends nothing), rounded down to 6 decimal places and never below `\"0\"`. It is the\nstrategy's cash after this round, so the book's unweighted remainder and the weight of\nany `not_tradable` name stay in nav and the next call does not sell again.\n"
          }
        }
      },
      "SignalRebalancePlan": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "strategy_id",
          "book_hash",
          "signal_id",
          "as_of",
          "nav_usdc",
          "usdc_available",
          "funding",
          "orders",
          "skipped"
        ],
        "properties": {
          "strategy_id": {
            "type": "string",
            "description": "The canonical id, even when the request named the slug."
          },
          "book_hash": {
            "type": "string",
            "pattern": "^[0-9a-f]{64}$",
            "description": "The book's `book_hash`, as on `GET /signals/strategies/{id}`."
          },
          "signal_id": {
            "type": "string",
            "description": "The served book's `signal_id`, as on `GET /signals/strategies/{id}`."
          },
          "as_of": {
            "type": "integer",
            "description": "Unix seconds. When Treasures ingested the book, not the filing date."
          },
          "nav_usdc": {
            "type": "string",
            "description": "The USD value of what you hold in scope, plus `amount_usdc`."
          },
          "usdc_available": {
            "type": "string",
            "description": "The wallet's Solana USDC, as a decimal string. With `chain: \"bnb\"`, `eth_wallet`'s Binance-Peg USDC on BNB Smart Chain, floored to 6 decimal places."
          },
          "funding": {
            "$ref": "#/components/schemas/SignalOrderFunding"
          },
          "orders": {
            "type": "array",
            "maxItems": 25,
            "items": {
              "$ref": "#/components/schemas/SignalOrder"
            },
            "description": "Sells first, then buys, each largest notional first."
          },
          "skipped": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SignalOrderSkip"
            }
          },
          "approvals": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SignalOrderApproval"
            },
            "description": "`chain: \"bnb\"` only, absent otherwise. One row for USDC when the plan buys, then one per token a planned sell spends. Approve any row that is `true` before submitting its orders, or the order cannot fill. A `null` row is unknown, never approved: read the allowance on-chain, or approve, before signing."
          }
        }
      },
      "SignalRebalanceResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "strategy_id",
          "book_hash",
          "signal_id",
          "as_of",
          "nav_usdc",
          "usdc_available",
          "funding",
          "orders",
          "skipped",
          "expires_at",
          "signing_window_sec"
        ],
        "properties": {
          "strategy_id": {
            "type": "string"
          },
          "book_hash": {
            "type": "string",
            "pattern": "^[0-9a-f]{64}$"
          },
          "signal_id": {
            "type": "string"
          },
          "as_of": {
            "type": "integer"
          },
          "nav_usdc": {
            "type": "string"
          },
          "usdc_available": {
            "type": "string"
          },
          "funding": {
            "$ref": "#/components/schemas/SignalOrderFunding"
          },
          "orders": {
            "type": "array",
            "maxItems": 25,
            "items": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/SignalOrder"
                },
                {
                  "required": [
                    "quote"
                  ]
                }
              ]
            }
          },
          "skipped": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SignalOrderSkip"
            }
          },
          "expires_at": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Unix seconds. The earliest `orders[].quote.expires_at`; `null` when no order was quoted. Each quote's own `expires_at` is what `/trade/submit` enforces for it."
          },
          "signing_window_sec": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Seconds from this response until `expires_at`; `null` when no order was quoted."
          }
        }
      },
      "SettlementFeeCost": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "name",
          "percentage",
          "amount_usd",
          "included"
        ],
        "properties": {
          "name": {
            "type": "string",
            "enum": [
              "treasures_fee",
              "dex_fee",
              "integrator_fee"
            ],
            "description": "- `integrator_fee` is your own fee on the trade, present only when the trade carried\n  one; it is what payouts to you are summed from, entry by entry.\n- `treasures_fee` is our own take and is always present.\n- `dex_fee` is the venue's take, net of ours, and is present only when it was recorded;\n  trades settled before it was captured omit the entry rather than reporting a\n  fabricated zero, so read its absence as unknown. A recorded `0` IS emitted and means\n  the venue charged no fee. On a speed-route leg that the server broadcast, it is\n  measured from the settled transaction rather than taken from the quote.\n\n`dex_fee` covers the venue's FEE, not execution spread. A resolver's auction margin on\nan intent-based fill sits outside it, so `0.0000` means \"no venue fee\", not \"no\nexecution cost\". To measure all-in cost, compare `amount_usd` against a reference price\nrather than summing this array.\n"
          },
          "percentage": {
            "type": "string",
            "description": "Fee as a decimal fraction at 4 dp, e.g. `0.0025` for 25 bps."
          },
          "amount_usd": {
            "type": "string",
            "description": "The fee in the settlement currency, derived as `percentage` applied to the entry's `amount_usd`, not read back from the venue's own fee event. Treat it as a close estimate rather than a reconciled figure: the recorded settlement notional is already net of the fee on an Ethereum sell, on a sell paid out on another chain and on a Solana buy, and on other buys the fee is taken in the token received rather than in the settlement currency. Same caveat applies to reconstructing a gross notional from it. Both entries carry this caveat identically."
          },
          "included": {
            "type": "boolean",
            "description": "`true` when the fee was taken out of the swap rather than charged on top."
          },
          "payout_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "`integrator_fee` only: the payout this fee went out in (see `GET /payouts/{payoutId}`), or `null` while it is still owed to you."
          }
        }
      },
      "SettlementEntry": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "trade_id",
          "status",
          "side",
          "ticker",
          "protocol",
          "chain",
          "from_address",
          "to_address",
          "recipient",
          "timestamp",
          "tx_hash",
          "token_out_address",
          "amount",
          "amount_usd",
          "shares",
          "sending",
          "receiving",
          "fee_costs"
        ],
        "properties": {
          "trade_id": {
            "type": "string",
            "description": "Stable id for this leg. One user-facing sell can fan out across several venues, producing several entries with distinct hashes."
          },
          "status": {
            "type": "string",
            "enum": [
              "DONE"
            ],
            "description": "Only settled trades are returned, so this is currently always `DONE`."
          },
          "side": {
            "type": "string",
            "enum": [
              "buy",
              "sell"
            ]
          },
          "ticker": {
            "type": "string"
          },
          "protocol": {
            "$ref": "#/components/schemas/Protocol"
          },
          "chain": {
            "$ref": "#/components/schemas/Chain"
          },
          "from_address": {
            "type": "string",
            "description": "The wallet that sent the input token. EVM addresses are EIP-55 checksummed."
          },
          "to_address": {
            "type": "string",
            "description": "The wallet that received the output token: the same wallet, for a swap; on a sell paid out on another chain, your wallet on that chain."
          },
          "recipient": {
            "type": "string",
            "description": "Alias of `to_address`."
          },
          "timestamp": {
            "type": "integer",
            "description": "Settlement time, unix seconds. Mirrors `receiving.timestamp`."
          },
          "tx_hash": {
            "type": "string",
            "description": "The trade's own transaction on `chain`, the same hash `GET /trades` reports. Equal to both legs' `tx_hash` on a single-chain swap; on a sell paid out on another chain it is the sale (`sending.tx_hash`), and the payout is `receiving.tx_hash`."
          },
          "token_out_address": {
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Address of the token received. Mirrors `receiving.token.address`: the stock token on a buy, the stablecoin on a sell. `null` when the catalog entry is unavailable."
          },
          "amount": {
            "type": "string",
            "description": "Raw base units received. Mirrors `receiving.amount`. For the rebase venues (xStocks on Ethereum and BNB Smart Chain) this is the conserved internal unit rather than the wallet-visible balance; reconcile on `shares`, which is the equity measure, or on `receiving.transfer_amount`, which is the raw figure the on-chain `Transfer` event carries and a block explorer renders."
          },
          "amount_usd": {
            "type": "string",
            "description": "USD value of the trade, as a decimal string at the settlement currency's scale, like every money field in this API. On Robinhood Chain the settlement currency is USDG rather than USDC."
          },
          "shares": {
            "type": "string",
            "description": "Equity shares this leg moved, floored: the same rounding `/trades` and `/portfolio` use. The denomination is the one recorded with the trade at submit, so if a token's on-chain denomination changes afterwards this value can differ in its trailing digits from the same trade on `/trades`, which reads the current one. Reconcile on `trade_id`."
          },
          "sending": {
            "$ref": "#/components/schemas/SettlementLeg"
          },
          "receiving": {
            "$ref": "#/components/schemas/SettlementLeg"
          },
          "fee_costs": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SettlementFeeCost"
            }
          }
        }
      },
      "SettlementsResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "data",
          "next_cursor",
          "has_more"
        ],
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SettlementEntry"
            }
          },
          "next_cursor": {
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Pass back as `cursor` for the next page; `null` on the last page."
          },
          "has_more": {
            "type": "boolean",
            "description": "Whether another page exists. Authoritative; `data` can be shorter than `limit` while this is `true`, so do not treat a short page as the end."
          }
        }
      }
    }
  }
}
