# Treasures Finance API docs > Docs for the Treasures Finance B2B Public API (tokenized stock discovery, quotes and trades, USDC bridging, portfolio reads, strategy signals) and the Manager API (fund managers publishing a strategy). Treasures lets people and AI agents buy real tokenized stocks with USDC, routed across every issuer and chain for the most shares per dollar, held in a wallet the caller controls. Trading carries a flat 0.1% fee. Machine-readable resources: - [B2B Public API spec (OpenAPI JSON)](https://docs.treasures.io/openapi.json) - [Manager API spec (OpenAPI JSON)](https://docs.treasures.io/manager-openapi.json) - [Agent skills navigator](https://docs.treasures.io/skill.md): install lines for the Treasures agent skills - [Chains and venues](https://docs.treasures.io/overview/chains-and-venues.md): what each chain needs before you trade on it (stablecoin, approvals and spender, who pays gas, which options it takes) - [Full docs in one file](https://docs.treasures.io/llms-full.txt) ## Treasures Finance B2B Public API endpoints Base URL: https://api.treasures.io/public/v1. Full spec as JSON: https://docs.treasures.io/openapi.json - `GET /stocks`: List active tradable stocks (catalog + live enrichment) - `GET /stocks/tickers`: List active tickers (no price enrichment) - `GET /stocks/prices`: Live per-protocol prices for requested tickers - `GET /stocks/{ticker}`: Company / ticker details (integrator key required) - `POST /quote/buy`: Quote USDC → stock token (one leg per chain the ticker lists, better first) - `POST /quote/preview`: Wallet-less price preview (integrator key required) - `POST /quote/sell`: Quote stock holdings → USDC (all legs needed; all-or-nothing submit) - `GET /quote/{quote_id}/status`: Aggregate + per-leg status for a previously issued quote - `POST /trade/submit`: Submit signed quote legs atomically - `POST /trade/submit/batch`: Submit up to 25 signed quotes in one request - `POST /bridge/quote`: Quote a cross-chain USDC bridge - `GET /bridge/{bridge_quote_id}/status`: Status of a previously issued bridge quote - `POST /bridge/{bridge_quote_id}/submit`: Submit a signed bridge for execution - `GET /portfolio`: Reconciled holdings + USDC / USDG balances for the given wallets - `GET /trades`: Swap-only trade history for the given wallets - `GET /settlements`: Your organisation's settled trades, paginated - `GET /payouts/accrued`: What you are owed right now, and where it will be paid - `GET /payouts`: Your payout history, newest first - `POST /payouts`: Pay out everything you are owed, to your registered address - `GET /payouts/{payoutId}`: One of your payouts - `GET /signals/strategies`: The strategies whose target-weight books you may read - `GET /signals/strategies/{id}`: One strategy and its current target-weight book - `GET /signals/strategies/{id}/history`: The strategy's past books, newest first - `POST /signals-orders/exit/plan`: The sells that exit a strategy book from your wallet, with no quotes - `POST /signals-orders/exit`: The sells that exit a strategy book, each with its signable quote - `POST /signals-orders/rebalance/plan`: The sells and buys that bring your strategy positions to its book, with no quotes - `POST /signals-orders/rebalance`: The sells and buys that bring your strategy positions to its book, each with its signable quote ## Treasures Finance Manager API endpoints Base URL: https://api.treasures.io/manager/v1. Full spec as JSON: https://docs.treasures.io/manager-openapi.json - `GET /strategies`: The strategies assigned to you - `GET /strategies/{strategyId}/signals`: The signal history of your strategy - `POST /strategies/{strategyId}/signals`: Publish the target weights of your strategy - `GET /strategies/{strategyId}/performance`: The performance chart of your strategy - `GET /strategies/{strategyId}/accounts`: The separately managed accounts of your SMA strategy - `GET /strategies/{strategyId}/accounts/{address}/fills`: The fills of one separately managed account - `GET /strategies/{strategyId}/accounts/{address}/holdings`: What one separately managed account holds right now - `GET /strategies/{strategyId}/accounts/{address}/performance`: The daily valuations of one separately managed account - `GET /strategies/{strategyId}/orders`: Every fill across the accounts of your SMA strategy - `GET /fees`: Your fee ledger (your share of each collection, and what reached you on-chain) - `GET /keys`: Your API keys (metadata only) - `POST /keys`: Mint a new API key - `DELETE /keys/{keyId}`: Revoke one of your API keys ## Buying and Selling Every trade takes the same four calls. The options you add to the quote change three things: which kinds of legs come back, what each leg asks you to sign, and who pays the gas. This page maps every combination of `priority`, `execution`, `origin_chain` and `payout_chain` to what you get, shows how to pay Solana fees for your users with `sol_fee_payer`, so you can pick the right one and handle any quote it returns. The chain-by-chain rules behind each option are in [Routing and Priority Mode](/overview/routing-and-priority-mode), and what each chain needs from the wallet (its stablecoin, approvals and gas) is in [Chains and Venues](/overview/chains-and-venues). ### The four calls 1. **Quote.** [`POST /quote/buy`](/api/quote-buy) with `amount_usdc`, or [`POST /quote/sell`](/api/quote-sell) with `amount_shares`, plus the `ticker`, the wallets, an [ownership proof](/overview/ownership-proof) and any of the options below. You get a `quote_id`, an `expires_at`, `warnings[]` and `quotes[]`: one **leg** per chain, each carrying its own `expires_at` and the `signable_payloads` to sign. 2. **Sign.** Sign every payload of the legs you will submit, each as its `type` says ([below](#sign-by-payload-type)). 3. **Submit.** [`POST /trade/submit`](/api/submit-trade) with the `quote_id` and, for each leg, its `quote_index` and `signed_payloads`. Treasures broadcasts them. With an integrator key, up to 25 signed quotes can go in one request through [`POST /trade/submit/batch`](/api/submit-trade-batch), same-chain Solana legs only, each answered as the single route would. 4. **Track.** Poll [`GET /quote/{quote_id}/status`](/api/get-quote-status) at the `poll_after_ms` it returns until every leg is terminal. **Which legs you submit is the one rule that differs by side.** - **Buy:** the legs are alternatives, best price first. Submit **exactly one** `quote_index`, usually `0`. Two or more is `400 quote_index_mismatch`. - **Sell:** the legs are parts of one sale, each selling a slice of your holdings. Submit **every** leg. A subset is `400 incomplete_submit`; to sell from fewer chains, re-quote with `chain`. Submit before the `expires_at` of the leg you signed. The top-level `expires_at` is the earliest leg's, so it is safe for any leg but understates the others; a sell signs every leg, so it is bound by the earliest. Echo each leg's `quote_index` rather than its position in the array: a buy alternative that had already expired when the quote was built is left out, so the values can skip. To price a buy with no wallet attached, [`POST /quote/preview`](/api/quote-preview) takes the same buy options without the wallets, the ownership proof or `sol_fee_payer` (it needs an [integrator key](/enterprises/integrator-api-keys)) and returns the legs with nothing to sign. ### The options | Option | Values | What it changes | | --- | --- | --- | | `chain`, `protocol` | One value (a pin) or an array (a subset) | Which venues are considered. Default: every one the ticker lists | | `preferred_chain` | A chain inside your `chain` scope | Order only: that chain's leg comes first on a buy, and is filled first on a sell | | `priority` | `"speed"` | One-block swaps on Robinhood Chain and Base instead of gasless orders, and cross-chain buys | | `origin_chain` | `"sol"`, `"eth"`, `"robinhood"` or `"base"` | Buys and previews only: the chain your stablecoin sits on. Legs on other chains rank as if they also paid to move it there, and under `priority: "speed"` it is the only chain a cross-chain buy spends from | | `execution` | `"transaction"` (default) or `"user_operation"` | With `priority: "speed"` only: EVM legs come back as one call bundle your own paymaster sponsors | | `payout_chain` | `"sol"`, `"eth"` or `"base"` | Sells only: the sale's USDC lands on that chain, and positions elsewhere can sell cross-chain | | `sol_fee_payer` | A Solana address you fund | Buys and sells: that wallet pays the SOL fees, and any new token account's rent, on each same-chain Solana swap a market maker does not fill, so a wallet holding no SOL can trade everything except a first buy of an `ondo` token. See [below](#paying-solana-fees-for-your-users) | | `integrator_fee_bps` | `0` to your ceiling, in net bps | With your integrator key only: your own fee on this quote, instead of your configured default. See [Integrator Fees and Payouts](/enterprises/integrator-fees-and-payouts) | These combinations are refused up front with `400 invalid_request`: - `execution: "user_operation"` without `priority: "speed"`. - `payout_chain` on `/quote/buy` or `/quote/preview`, or `origin_chain` on `/quote/sell`. - `origin_chain` on `/quote/buy` without the wallet for that chain (`sol_wallet` for `sol`, `eth_wallet` otherwise). - `priority: "speed"` with `chain: "arbitrum"`, which has no speed route. - `sol_fee_payer` without `sol_wallet`, equal to it, beside `quote_only: true`, or on `/quote/preview`. - `priority: "speed"` with `chain: "eth"` on a sell, unless `payout_chain` names another chain. - A `preferred_chain` outside the `chain` you sent. ### The kinds of leg Whatever you ask for, each leg that comes back is one of these. The rest of the page names them. | Leg | What you sign | Who pays gas | | --- | --- | --- | | **Swap** (Solana) | One `solana_versioned_tx`; also signed by your `sol_fee_payer` when the leg carries it | Usually the wallet, in SOL, or your `sol_fee_payer`; `gasless` on the leg says whether anyone on your side pays | | **Gasless order** | One `evm_eip712_typed_data` | Nobody on your side: a settlement network broadcasts it | | **Speed swap** | One or two EVM transactions: an `approve` (first time only), then the `swap` | The wallet, in native ETH on that chain | | **Sponsored swap** | One `evm_calls` bundle, packed into an ERC-4337 UserOperation | Your paymaster | | **Cross-chain buy** (`origin_chain` set) | The origin chain's shape: a Solana transaction, an `approve` and `deposit` pair, or one `evm_calls` | The wallet on the origin chain, or your paymaster when sponsored | | **Cross-chain sell** (`payout_chain` set) | On Ethereum and Base, an `approve` and `deposit` pair, or one `evm_calls` when sponsored; on Solana, one transaction | The wallet on the chain the stock is sold on, or your paymaster when sponsored | Every leg carries `gasless`: `true` when nobody on your side pays (a gasless order, or your paymaster), `false` when the wallet or your `sol_fee_payer` does. It can be absent on a Solana leg, and absent is not `false`. ### Buying: what each combination returns | You add | Solana | Ethereum | Robinhood Chain | Base | | --- | --- | --- | --- | --- | | Nothing | Swap | Gasless order | Gasless order | Gasless order | | `priority: "speed"` | Swap, or cross-chain buy | Cross-chain buy only | Speed swap | Speed swap, or cross-chain buy | | `priority: "speed"` and `execution: "user_operation"` | Swap, or cross-chain buy | Cross-chain buy only | Sponsored swap | Sponsored swap, or cross-chain buy | - **A cross-chain buy** is offered only on a chain the wallet is not funded on, and only into `sol/xstocks`, `sol/backpack`, `eth/ondo` and, on an unpinned or multi-chain request, `base/coinbase`. The funds leave from another chain where the wallet does hold enough (only from `origin_chain`, when you send it), so send both `sol_wallet` and `eth_wallet`. - **`origin_chain` on the default route** changes the order of the legs and nothing else. A leg on another chain is still a same-chain leg: fund that chain (for example through a [bridge](/api/quote-bridge)) and re-quote before you submit it. - **Arbitrum** returns a gasless order by default and is never quoted under speed. - **Choose** the default for the best price with no native gas on the EVM chains beyond each wallet's one-time approvals ([Chains and Venues](/overview/chains-and-venues#approvals-by-chain)). Choose speed when settlement inside one block matters, or when the user's USDC sits on a different chain from the listing. Add `user_operation` when you run an ERC-4337 stack and would rather your paymaster paid than hold native gas. ### Selling: what each combination returns Without `payout_chain`, each position sells on its own chain: | You add | Solana | Ethereum | Robinhood Chain | Base | | --- | --- | --- | --- | --- | | Nothing | Swap | Gasless order | Gasless order | Gasless order | | `priority: "speed"` | Swap | Not sold | Speed swap | Speed swap | | `priority: "speed"` and `execution: "user_operation"` | Swap | Not sold | Sponsored swap | Sponsored swap | With `payout_chain`, all of the USDC lands on that chain, in the wallet you sent for it (`sol_wallet` on `sol`, `eth_wallet` on `eth` and `base`). Each position is planned by where it sits, whatever the `priority`: | Position | On the payout chain | On another chain | | --- | --- | --- | | `sol/xstocks`, `sol/backpack`, `base/coinbase` | Sells as in the table above | Cross-chain sell | | `eth/ondo` | Sells as in the table above (so not under speed) | Cross-chain sell | | `sol/ondo`, `eth/xstocks` | Sells as in the table above | Left out, with a warning | | Robinhood Chain, Arbitrum | Never a payout chain | Left out, with a warning | A position that cannot pay out on `payout_chain` is never sold on its own chain instead, because that would pay out somewhere you did not ask for. It is named by a `cross_chain_route_unavailable` warning. Adding `priority: "speed"` and `execution: "user_operation"` turns the Ethereum and Base cross-chain sells into sponsored `evm_calls` bundles. ### Paying Solana fees for your users A Solana swap that a market maker does not fill pays its network fee from the wallet's SOL, and a wallet holding almost none is refused on Solana at quote time with `422 no_routes` and `reason: "insufficient_gas"` ([thresholds](/overview/chains-and-venues#solana-sol)). A sponsor that would only co-sign later never gets the chance, because the quote itself needs the SOL. To pay it yourself, send `sol_fee_payer`: one fixed Solana address you fund, on `/quote/buy` **and** `/quote/sell`. Each Solana leg then comes back one of two ways: - **Carrying `sol_fee_payer`** (your address, echoed). Your wallet is the transaction's fee payer: it pays the network fees and the rent of any token account the trade opens for your user (roughly 0.0016 to 0.0021 SOL on a first buy of a token; the account, and its rent, stay with your user). The leg reads `gasless: false`, and `estimated_gas_usd` is what your wallet pays. Sign the transaction **as issued** with both keys, your `sol_fee_payer` and the user's `sol_wallet`, and never rebuild it. - **Without it.** A market maker fills the order and pays its own fee. Sign with the user's wallet alone. Every `ondo` leg comes back this way, so `sol_fee_payer` never pays for one, and on a first buy of an `ondo` token the new token account's rent is the user's own: keep about 0.01 SOL in a wallet that buys an `ondo` token it does not hold yet, or its `ondo` leg is dropped. The rules: - **Send it on sells as well as buys.** It covers only the quote it rides on, and a sponsored buy leaves the user's SOL where it was, so a wallet still short of SOL is refused on its sell too unless that sell also carries `sol_fee_payer`. - **Once you send it, a leg your wallet pays for is the only pool-filled option.** A sponsor that cannot cover the fees and rent fails the leg even when the user's own wallet holds enough SOL. - **One fixed address from quote to submit.** A fee payer whose address changes between the two (as some hosted sponsorship services do) cannot sign the transaction it was quoted for. - **Keep it funded for rent as well as fees.** When it cannot cover them, its legs are refused and the quote reads `422 no_routes`. - It needs `sol_wallet` and must differ from it, it is refused beside `quote_only: true` and on `/quote/preview`, and it is screened like your other wallets. Naming it grants nothing: the transaction does nothing until it signs. Cross-chain legs and bridges from Solana are unchanged: they still spend the wallet's SOL. ### Handling a quote A single quote can mix leg kinds. An unpinned speed buy, for example, can return a Solana swap, a Base speed swap and an Ethereum cross-chain buy side by side. So handle each leg on its own: read what it is, then sign each payload by its `type`. #### Recognise the leg | On the leg | It is | Read it as | | --- | --- | --- | | `payout_chain` present | A cross-chain sell | `chain` is where the stock is sold; the USDC lands on `payout_chain` | | `origin_chain` present | A cross-chain buy | `chain` is the destination; the funds leave `origin_chain`, and `base_asset` names that chain's currency | | Neither | A same-chain leg | `chain` is where everything happens | A cross-chain leg also carries `cross_chain_cost_bps` and `cross_chain_cost_usdc`, the hop's own cost, and its `cost_breakdown_bps.dex_swap_fee_bps` is `null`. #### Sign by payload type Sign every payload in `signable_payloads`, in the order issued: | Payload `type` | How to sign it | Return | | --- | --- | --- | | `solana_versioned_tx` | Deserialize `tx_base64` and sign with the wallet's transaction signer, not `signMessage` | `solana_versioned_tx` with `signed_tx_base64` | | `evm_eip712_typed_data` | `eth_signTypedData_v4` over `typed_data`, exactly as given | `evm_eip712_signature` with `signature` | | `evm_eip1559_tx`, `evm_legacy_tx` | `signTransaction` over `tx_hex` as issued; never change the nonce, gas or fees | `evm_signed_tx` with `signed_tx_hex`, one per payload | | `evm_calls` | Pack `calls` into one ERC-4337 v0.7 UserOperation for `sender` on `chain_id` (`execute` for one call, `executeBatch` in order for two), sponsor it with your paymaster, sign it; a wallet with no code yet adds its `eip7702Auth` | `evm_user_operation` with `user_operation` | Rules that hold for every leg: - **Branch on `type`**, never on `chain` or on the options you sent. - **Return every payload, in order.** Two EVM transactions on one leg (an `approve`, then the `swap` or `deposit`) are normal. Returning only one is `incomplete_submit`, and reordering them on a retry is read as a new submit. - **Approve before the first gasless order on each EVM chain.** The default order is gasless, but the wallet first sends its own one-time approval of the token it spends, and the spender differs by chain (Robinhood Chain's is not the one the others use). The addresses are in [Chains and Venues](/overview/chains-and-venues#approvals-by-chain). - **Never broadcast a trade payload yourself.** You sign; Treasures sends it. The only transaction you broadcast is a bridge. - **Know what an approve grants.** A speed swap's `approve` gives the router an unlimited allowance on the token spent, once per wallet, token and chain, so surface that consent to your user. A cross-chain leg's `approve` is for the exact amount, and on a sell it comes every time. - **The sponsored lane needs a Modular Account v2 wallet, or one with no code yet.** - The wallet must be EIP-7702-delegated to Modular Account v2 on that chain, or have no code there: its first operation then carries the delegation itself as `eip7702Auth`, the wallet's signed EIP-7702 authorization for that chain (account SDKs with a 7702 mode attach it on their own). - The authorization must name Modular Account v2, carry the leg's `chain_id` (never `0`) and be signed by `sender`, or the leg is refused as `invalid_signature`. Every operation must carry a paymaster. - The lane serves Base and Robinhood Chain; a chain it cannot serve at the moment is dropped with `speed_route_unavailable` and `reason: "disabled"`. A signing loop that handles every combination above, whatever options were sent: ```ts import { VersionedTransaction } from '@solana/web3.js'; import { parseTransaction } from 'viem'; // `signers` is yours: a Solana transaction signer, an EVM account that signs typed data and // transactions without sending them, (sponsored lane only) your ERC-4337 account SDK, and (with // sol_fee_payer only) a signer for the Solana wallet you fund. async function signLeg(leg: QuoteLeg, signers: Signers) { const signedPayloads = []; for (const payload of leg.signable_payloads) { switch (payload.type) { case 'solana_versioned_tx': { const unsigned = VersionedTransaction.deserialize(Buffer.from(payload.tx_base64, 'base64')); let signed = await signers.solana.signTransaction(unsigned); // A leg carrying sol_fee_payer needs that wallet's signature too, on the same bytes. if (leg.sol_fee_payer) signed = await signers.solFeePayer.signTransaction(signed); signedPayloads.push({ type: 'solana_versioned_tx', signed_tx_base64: Buffer.from(signed.serialize()).toString('base64'), }); break; } case 'evm_eip712_typed_data': { const { domain, types, primaryType, message } = payload.typed_data; const { EIP712Domain: _domainType, ...orderTypes } = types; // viem adds the domain type itself const signature = await signers.evm.signTypedData({ domain, types: orderTypes, primaryType, message }); signedPayloads.push({ type: 'evm_eip712_signature', signature }); break; } case 'evm_eip1559_tx': case 'evm_legacy_tx': { const signedTxHex = await signers.evm.signTransaction(parseTransaction(payload.tx_hex)); signedPayloads.push({ type: 'evm_signed_tx', signed_tx_hex: signedTxHex }); break; } case 'evm_calls': { // Build one UserOperation from payload.calls for payload.sender on payload.chain_id, // run your paymaster's sponsorship, sign it, and return the unpacked v0.7 fields (plus // eip7702Auth on a wallet's first operation, while it has no code on that chain). const userOperation = await signers.userOperation.buildSponsorAndSign(payload); signedPayloads.push({ type: 'evm_user_operation', user_operation: userOperation }); break; } default: throw new Error(`Unrecognised payload type ${payload.type}; update your integration`); } } return { quote_index: leg.quote_index, signed_payloads: signedPayloads }; } ``` Submit one signed leg for a buy (`signed: [await signLeg(quote.quotes[0], signers)]`), and every leg for a sell. ### Recipes | Goal | Add to the quote request | What to expect | | --- | --- | --- | | Cheapest buy, no native gas on EVM | Nothing | `quotes[0]` is the best price | | Buy on one chain only | `"chain": "base"` | One leg, or `422 no_routes` | | Prefer a chain, keep the fallbacks | `"preferred_chain": "sol"` | That chain's leg is `quotes[0]` | | Settle in one block | `"priority": "speed"` | A speed swap, with an `approve` the first time | | Settle in one block, no native gas | `"priority": "speed"`, `"execution": "user_operation"` | One `evm_calls` per EVM leg | | Buy where the user holds no USDC | `"priority": "speed"`, both wallets | A leg with `origin_chain` set | | Buy with USDC held on one chain | `"priority": "speed"`, `"origin_chain": "eth"`, both wallets | Cross-chain legs spend only from that chain | | Rank for USDC held on one chain | `"origin_chain": "eth"`, both wallets | `quotes[0]` is cheapest counting the cost of moving the USDC | | Sell, all USDC to Solana | `"payout_chain": "sol"` | Cross-chain legs carry `payout_chain`; submit every leg | | Trade from a Solana wallet holding no SOL | `"sol_fee_payer": ""`, on the buy and the sell | Solana legs carry `sol_fee_payer`: sign them with both wallets | | Sell to USDC on Base, no native gas | `"payout_chain": "base"`, `"priority": "speed"`, `"execution": "user_operation"` | Ethereum and Base legs as `evm_calls` | The request for the last recipe, with the proof built as in [Ownership Proof](/overview/ownership-proof): ```json { "ticker": "NVDA", "amount_shares": "2.5", "sol_wallet": "7xKXtg2C…", "eth_wallet": "0xab5801a7…", "payout_chain": "base", "priority": "speed", "execution": "user_operation", "max_slippage_bps": 100, "ownership_proof": { "issued_at": 1750000000, "sol_signature": "", "eth_signature": "0x" } } ``` ### Tracking the trade Poll [`GET /quote/{quote_id}/status`](/api/get-quote-status) at the `poll_after_ms` it returns: `1250` while a speed swap is in flight, `3250` otherwise. Which handle identifies a leg depends on its kind: | Leg | What to watch | | --- | --- | | Swap (Solana) | `tx_hash`, usually final at submit. On `broadcast_unknown`, do not resubmit: poll | | Gasless order | `order_hash` until the order fills, then `tx_hash` | | Speed swap | `tx_hash`, set from submit; on an `approve` and `swap` pair it lands once the approve mines | | Sponsored swap | `user_op_hash`; `tx_hash` is filled in once the operation is included | | Cross-chain sell | `tx_hash` is the sale, `payout_tx_hash` the payout, set on `completed`. The completed leg's `payout_chain` is where the USDC landed: it equals `chain` if the payout was returned there | | Cross-chain buy | The leg's `status`. `cross_chain_unsettled` after 6 hours means wait, because it may still fill or refund; do not re-quote | Resubmitting the same signed payloads for the same `quote_index` is safe and returns the original result. Only one speed trade per wallet per chain can be in flight at a time; wait for it to finish before quoting the next. ### When a quote comes back short | You see | What to do | | --- | --- | | `speed_route_unavailable` warning | A Robinhood Chain or Base leg was dropped under speed; its `reason` says why. Take another leg, fix the reason, or re-quote without `priority` | | `speed_route_fallback` warning, on a sell | That Robinhood Chain or Base leg is on its [relayed route](/overview/routing-and-priority-mode#what-you-trade-away), not the speed route: sign its typed-data payload and expect minutes. If `approval_needed` is `true`, approve the stock token to `approval_spender` first, or the order cannot fill | | `speed_route_unavailable` with `reason: "no_speed_venue"` on a `422` | Speed [never quotes that listing](/overview/routing-and-priority-mode#what-you-trade-away). Re-quote without `priority` to reach it | | `cross_chain_route_unavailable` warning | A listing could not be reached cross-chain, or (with `payout_chain`) a position was left out. Choose another leg or payout chain, or re-quote later | | `422 no_routes`, `reason: "insufficient_gas"` | The Solana wallet holds too little SOL for fees. Send `sol_fee_payer`, on the sell as well as the buy, or fund the wallet with SOL | | `422 no_routes`, `reason: "no_market_maker_fill"` | Market makers declined the order at that size. Try the size in `min_notional_usdc` when present, another chain, or later. On Solana, also check the wallet's [SOL](/overview/chains-and-venues#solana-sol) | | `422 no_routes`, `reason: "insufficient_balance"` | The wallet's own balance refused the request. Fund the token spent on that chain | | `422 no_routes`, `reason: "cross_chain_route_unavailable"` | The cross-chain route a speed buy needed could not be used. Fund the listing's own chain, or re-quote later | | `422 no_routes`, `reason: "cross_chain_wallet_missing"` | The buy could only be funded from a chain whose wallet you did not send. Send both wallets | | `422 no_routes`, `reason: "payout_route_unavailable"` | You hold enough, but not enough of it can pay out on `payout_chain`. Pay out elsewhere, or drop `payout_chain` | | `400 wallet_not_delegated` | The sponsored lane on a pinned chain, with a wallet delegated to code other than Modular Account v2 there. Re-delegate it to Modular Account v2, or drop `execution` | | `insufficient_native_gas` at submit | The wallet pays gas on this leg and has too little. Fund it and re-quote | | `nonce_conflict` at submit | Another speed trade from this wallet on that chain is in flight. Wait, then re-quote | | `sponsorship_rejected` at submit | Your paymaster declined the operation. Fix the sponsorship and re-sign | | `market_maker_rejected` on a Solana leg | The market maker refused the fill when the transaction was sent. Re-quote, possibly at another size | | `not_landed` on a Solana leg | The transaction was reported as not landing; a leg short of the token it spends also ends here. Check `tx_hash` on chain and the wallet's balance before re-quoting | Every error code and field is in the [API Reference](/api/quote-buy). --- ## Chains and Venues Every chain Treasures trades on has its own rules: which stablecoin it trades in, who pays the gas, what the wallet has to approve and to which address, and which quote options it accepts. A quote can mix chains, so an integration that handles one chain correctly can still fail on the next leg it receives. This page puts those rules in one place. Read the row for each chain your users trade on before you build for it. For how the quote options combine, see [Buying and Selling](/overview/buying-and-selling). For how routes are ranked and what priority mode changes, see [Routing and Priority Mode](/overview/routing-and-priority-mode). ### At a glance | `chain` | Network | Issuers (`protocol`) | Trades in | Open | | --- | --- | --- | --- | --- | | `sol` | Solana | `ondo`, `xstocks`, `backpack` | USDC on Solana | Yes | | `eth` | Ethereum mainnet | `ondo`, `xstocks` | USDC on Ethereum | Yes | | `robinhood` | Robinhood Chain (4663) | `robinhood` | **USDG**, not USDC | Yes | | `base` | Base (8453) | `coinbase` | Base-native USDC | Yes, per ticker once minted | | `arbitrum` | Arbitrum One (42161) | `reality` | Arbitrum-native USDC | Yes, per ticker once minted | | `bnb` | BNB Smart Chain (56) | `ondo`, `xstocks`, `bstocks` | Binance-Peg USDC (18 decimals) | Yes for `ondo` and `xstocks`; `bstocks` not yet | Which tickers trade where changes over time. [`GET /stocks/tickers`](/api/list-stock-tickers) is the authority: read `available_chains` and each issuer's listing block at runtime rather than hardcoding a list. #### Who pays gas, and what you sign | `chain` | Default leg: you sign | Who pays the trade's gas | Native gas the wallet still needs | | --- | --- | --- | --- | | `sol` | A Solana transaction | The wallet in SOL, a market maker, or your [`sol_fee_payer`](#solana-sol) | SOL for fees and new token accounts. With `sol_fee_payer`, only for a first buy of an `ondo` token and for bridges or cross-chain legs leaving Solana | | `eth` | A gasless order (EIP-712 typed data) | Nobody on your side | ETH, for the one-time approvals | | `robinhood` | A gasless order | Nobody on your side | ETH on Robinhood Chain, for the one-time approvals | | `base` | A gasless order | Nobody on your side | ETH on Base, for the one-time approvals | | `arbitrum` | A gasless order | Nobody on your side | ETH on Arbitrum, for the one-time approvals | | `bnb` | A gasless order (`ondo`, `xstocks`) | Nobody on your side | BNB, for the one-time approvals | "Gasless" covers the trade itself. On every EVM chain the wallet sends its own one-time ERC-20 approval first, and that transaction costs that chain's native gas. Under `priority: "speed"` the Robinhood Chain and Base legs stop being gasless: the wallet pays each swap's gas too, unless your paymaster sponsors it with `execution: "user_operation"`. #### Which options each chain takes | `chain` | `priority: "speed"` | Cross-chain buy into it (speed only) | `origin_chain` | `payout_chain` | Reached by `/bridge/quote` | | --- | --- | --- | --- | --- | --- | | `sol` | Unchanged: the normal swap | `xstocks` and `backpack`, never `ondo` | Yes | Yes | Yes | | `eth` | Never on its own route | `ondo` only, never `xstocks` | Yes | Yes | Yes | | `robinhood` | Speed swap, **only with USDG already on Robinhood Chain** | Never | Yes | No | Yes, arriving as USDG | | `base` | Speed swap | `coinbase`, on an unpinned or multi-chain request only | Yes | Yes | Yes | | `arbitrum` | Never (`400 invalid_request` when pinned) | Never | No | No | Yes | | `bnb` | `bstocks` only, the same transaction it uses at every priority; never `ondo` or `xstocks` | `bstocks` | No | No | Yes; `delivery: "submit"` not yet | `execution: "user_operation"` (your paymaster pays) applies only to the Robinhood Chain and Base speed swaps and to cross-chain legs leaving an EVM chain. #### Records and reads | `chain` | Trade made outside Treasures appears in `/trades` | Positions read by `/portfolio` | | --- | --- | --- | | `sol`, `eth` | Yes, as an `external` balance-change row (no price), recorded on the next `/trades` or `/portfolio` read | For the wallets you send | | `robinhood`, `base`, `arbitrum`, `bnb` | **No.** Only trades submitted through Treasures are recorded, with their cost basis | For any wallet when you send your [integrator key](/enterprises/integrator-api-keys); without it, only for wallets Treasures already knows | ### Solana (`sol`) - **Three issuers, ranked against each other.** `ondo`, `xstocks` and `backpack` (Backpack Securities, Solana only). Backpack tokens report a bare `token_ticker` (`MU`, no suffix), so branch on `protocol` and `chain`, never on the symbol's shape. - **No approvals.** Solana has no allowances. - **SOL is the gas you cannot skip by default.** Every Solana transaction pays a network fee, and a first buy of a token opens its token account (roughly 0.0016 to 0.0021 SOL of rent, which stays with the wallet). A wallet short of SOL is refused at quote time with `422 no_routes` and `reason: "insufficient_gas"`: under 0.01 SOL when the trade opens a token account, under 0.002 SOL otherwise. A wallet just above 0.002 SOL can still be refused, as `no_market_maker_fill`, so keep about 0.01 SOL in a wallet buying a token it does not hold yet and a little over 0.003 SOL otherwise. - **A market maker pays its own fee, but not the token account.** Every `ondo` leg on Solana is filled by a market maker, and so are some `xstocks` and `backpack` legs depending on size; the maker pays the network fee. A first buy of a token still opens the wallet's token account at the wallet's own cost. On an `ondo` leg that means the wallet needs about 0.01 SOL, or the `ondo` leg is dropped, and `sol_fee_payer` cannot pay it. Other legs fill against an on-chain pool and pay the network fee from the wallet's SOL. - **To pay the fees for your users, send `sol_fee_payer`** on every buy **and** sell quote: one fixed Solana address you fund. - A leg it pays for echoes it, reads `gasless: false` with `estimated_gas_usd`, and must be signed as issued by both your `sol_fee_payer` and the user's wallet. - It covers only the quote it rides on, so a wallet still short of SOL needs it again on the sell. - It never pays for an `ondo` leg (above), and it covers same-chain legs only: a bridge or cross-chain leg leaving Solana still spends the wallet's SOL. - Once you send it, a pool-filled leg is only ever the sponsored one, so a sponsor that cannot cover the fees and rent fails the leg even when the user's wallet could have paid. - Details: [Paying Solana fees for your users](/overview/buying-and-selling#paying-solana-fees-for-your-users). - **Check the USDC balance before quoting.** There is no general balance check. A market maker may refuse a Solana quote for a wallet short of USDC (`422 no_routes` with `reason: "insufficient_balance"`), but a Solana leg that still reaches `/trade/submit` short of the token it spends is sent and fails as `not_landed`. On the default route of the EVM chains an underfunded buy still gets a quote. - **Minimums bear on the exit.** A market maker that declines a small buy usually declines a small sell too, so a Solana position worth less than its [minimum](#sessions-and-minimums) may not be sellable there until topped up: avoid partial sells that leave less than the minimum behind. - **Fast.** A Solana leg is usually final when `/trade/submit` returns. On `broadcast_unknown`, poll; do not resubmit. A failed leg reports `market_maker_rejected` or `not_landed` and keeps the reported signature on `tx_hash` ([what to do](/overview/buying-and-selling#when-a-quote-comes-back-short)). - **Under `priority: "speed"`** a buy's Solana leg the wallet cannot fund is dropped; otherwise Solana legs are unchanged. An `xstocks` or `backpack` listing the wallet is not funded for on Solana can come back as a cross-chain leg paid from another chain. ### Ethereum (`eth`) - **Two issuers, two token addresses.** `ondo` and `xstocks` each have their own token for the same ticker, and a sell can fill from both. - **Gasless orders.** You sign an EIP-712 order and a settlement network fills and broadcasts it. A fill can take minutes: poll status (`order_hash` while it is live, then `tx_hash`). An order still unresolved after an hour ends as `status_check_exhausted`. - **Approve before the first trade.** USDC to buy, and each issuer's stock token to sell, to `0x111111125421ca6dc452d289314280a0f8842a65`, sent with ETH. Before selling, approve every issuer's token the wallet holds for that ticker: a sell can draw on each of them, and the quote window is too short to send an approval in between. - **An underfunded or unapproved buy still gets a quote.** Treasures does not check the wallet's USDC on a default buy. The leg fails at submit (`broadcast_failed`), or later as `failed`, with `not_enough_balance_or_allowance`, so check the balance and the allowance before quoting. - **Not part of priority mode.** Under `priority: "speed"` Ethereum is never quoted on its own route; a buy can reach `eth/ondo` only as a cross-chain leg, and a speed sell leaves Ethereum holdings out unless the sale [pays out on another chain](/overview/routing-and-priority-mode#paying-out-a-sell-on-another-chain-payout_chain). ### Robinhood Chain (`robinhood`) - **One issuer**, Robinhood Stock Tokens (`protocol: "robinhood"`), with bare tickers. - **USDG only.** A buy spends USDG and a sell pays out USDG. The leg says so with `base_asset: "usdg"`, and its `_usdc`-named amounts (`amount_usdc`, `price_usdc_per_share`, `estimated_output_usdc`) are in USDG. To get USDG onto the chain, [bridge](/api/quote-bridge) USDC from any other chain: the bridge converts it. - **It is in unpinned quotes.** A request without `chain` can return a Robinhood leg when it prices best, so check `base_asset` on every leg, not only when you asked for Robinhood. - **Approvals go to a different address.** The settlement contract on Robinhood Chain is `0x5A705DE8982235a7fa45bB83dCaCf03a211389C7`, not the `0x1111…0a65` the other EVM chains use. Approve USDG (to buy) or the stock token (to sell) to it once, from the wallet, with a little ETH on Robinhood Chain. An approval to the wrong address leaves the order unfillable (`not_enough_balance_or_allowance`). - **Listing is not liquidity.** Many listed names have little or no settlement liquidity and return `422 no_routes`. Read `tradability` and `min_trade_size_usd` on the `robinhood` listing block before quoting. - **Priority mode needs USDG already in the wallet.** - Under `priority: "speed"` a Robinhood leg is a single on-chain swap that spends the wallet's own USDG and pays gas in its own ETH on Robinhood Chain (or your paymaster's, with `execution: "user_operation"`). - The quote reads the USDG balance: if it is short, the leg is dropped with a `speed_route_unavailable` warning (`reason: "insufficient_balance"`), or the quote is `422 no_routes` with that reason when you pinned `chain: "robinhood"`. - Robinhood Chain is never a cross-chain destination, so USDC elsewhere cannot fund a speed buy here: bridge to USDG first. - A wallet with too little ETH for the swap fails at submit with `insufficient_native_gas`. - The speed quote carries its own `approve` when one is needed. - A speed sell the speed route cannot price is the exception: it comes back as a gasless order with a `speed_route_fallback` warning, which needs the stock token approved to the settlement contract above. - **Never a payout chain.** A sell with `payout_chain` leaves Robinhood positions out. USDG on Robinhood Chain can fund a cross-chain speed buy elsewhere (`origin_chain: "robinhood"`). ### Base (`base`) - **One issuer**, Coinbase B20 tokens (`protocol: "coinbase"`), with bare tickers. - **Base-native USDC** (`0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`), a different token from Ethereum's USDC even though both read `base_asset: "usdc"`. - **Listed per ticker once minted.** A ticker without minted supply is missing from `available_chains` and a buy is `422 no_routes`. Sells are never gated: a holder can always exit. - **Approvals** of USDC (to buy) or the B20 token (to sell) to `0x111111125421ca6dc452d289314280a0f8842a65` **on Base**, sent with a little ETH on Base. An Ethereum approval grants nothing here. - **Priority mode.** Under `priority: "speed"` a Base leg is a single on-chain swap paid from the wallet's ETH on Base, or by your paymaster with `execution: "user_operation"`. A pinned speed buy needs USDC on Base; on an unpinned or multi-chain request, a wallet not funded on Base can be served a cross-chain leg instead. A speed sell the speed route cannot price comes back as a gasless order with a `speed_route_fallback` warning, which needs the approval above. - **A payout chain.** A sell can pay its USDC out on Base with `payout_chain: "base"`. ### Arbitrum (`arbitrum`) - **One issuer**, Reality tokenized stocks (`protocol: "reality"`). - **Arbitrum-native USDC** (`0xaf88d065e77c8cC2239327C5EDb3A432268e5831`). - **Listed per ticker once minted**, like Base. - **Buys follow the market week.** Outside Sunday 20:00 to Friday 20:00 ET, and on US market holidays, a buy pinned to `arbitrum` is `422 no_routes` with `reason: "market_closed"`, and an unpinned buy comes back without an `arbitrum` leg. Treasures does not gate sells on the clock. - **Approvals** of USDC (to buy) or the stock token (to sell) to `0x111111125421ca6dc452d289314280a0f8842a65` **on Arbitrum**, sent with a little ETH on Arbitrum. - **The gasless route only.** No speed route (a speed request pinned to `arbitrum` is `400 invalid_request`), no cross-chain leg into it, and neither `origin_chain` nor `payout_chain` takes it. Fund it with a [bridge](/api/quote-bridge). - **No on-chain price** on [`/stocks/prices`](/api/get-stock-prices): compare a leg against the `tradfi` price instead. ### BNB Smart Chain (`bnb`) Three issuers list on one chain, so read each leg's `protocol`; which of them are open is in [At a glance](#at-a-glance). It trades in an 18-decimal Binance-Peg USDC that is not interchangeable with USDC anywhere else: [bridge](/api/quote-bridge) into it. While an issuer here is switched off for you its listings stay hidden and a buy there is `422 no_routes`, but positions you already hold stay sellable. Its legs come in two kinds: - **`ondo` and `xstocks`:** gasless orders like Ethereum's, with a signing window of about 14 seconds per leg and one-time approvals paid in BNB rather than ETH. - **`bstocks`:** a complete transaction at every priority (with its own `approve` when one is due), about 40 seconds to sign, its gas paid from the wallet's BNB. It is the one `bnb` cell served under `priority: "speed"`, and a cross-chain speed buy can reach it. Neither `origin_chain` nor `payout_chain` takes `bnb`. The [strategy signals](/enterprises/strategy-signals#on-bnb-smart-chain) plan routes take `chain: "bnb"` for `ondo` and `xstocks` positions, and report in `approvals` which of the approvals below the wallet is missing. ### Approvals by chain Allowances are per chain: an approval on one chain grants nothing on another, even where the spender address is the same. | `chain` | To buy, approve | To sell, approve | Spender | Paid in | | --- | --- | --- | --- | --- | | `sol` | Nothing | Nothing | n/a | n/a | | `eth` | USDC `0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48` | Each issuer's stock token | `0x111111125421ca6dc452d289314280a0f8842a65` | ETH | | `robinhood` | USDG `0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168` | The stock token | **`0x5A705DE8982235a7fa45bB83dCaCf03a211389C7`** | ETH on Robinhood Chain | | `base` | USDC `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` | The B20 token | `0x111111125421ca6dc452d289314280a0f8842a65` | ETH on Base | | `arbitrum` | USDC `0xaf88d065e77c8cC2239327C5EDb3A432268e5831` | The stock token | `0x111111125421ca6dc452d289314280a0f8842a65` | ETH on Arbitrum | | `bnb` | Binance-Peg USDC `0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d` | Each issuer's stock token | `0x111111125421ca6dc452d289314280a0f8842a65` | BNB | These cover the default gasless route. A speed swap's quote carries its own unlimited `approve` to the router named in its payload when the wallet needs one, and a cross-chain leg's quote carries an exact-amount `approve`: sign whatever the quote issues, in order. A bridge that you broadcast yourself names its spender in the bridge quote's `approval_spender`. ### Funding each chain | `chain` | To buy, hold | To sell, hold | Native float to keep | | --- | --- | --- | --- | | `sol` | USDC on Solana | The stock token | At least 0.02 SOL. With `sol_fee_payer`, about 0.01 SOL for first `ondo` buys, bridges and cross-chain legs leaving Solana | | `eth` | USDC on Ethereum | The stock token | About 0.01 ETH, for approvals and self-broadcast bridges | | `robinhood` | USDG | The stock token | A little ETH on Robinhood Chain, for approvals; more for speed swaps | | `base` | USDC on Base | The B20 token | About 0.001 ETH on Base, for approvals; more for speed swaps | | `arbitrum` | USDC on Arbitrum | The stock token | A little ETH on Arbitrum, for approvals | | `bnb` | Binance-Peg USDC on BNB Smart Chain | The stock token | About 0.001 BNB, for approvals and each `bstocks` trade | [`POST /bridge/quote`](/api/quote-bridge) moves stablecoin between any two of these chains. With `delivery: "submit"` from Ethereum, Base or Arbitrum, the bridge needs no native gas on the way out. The stablecoins are different tokens on every chain. [`GET /portfolio`](/api/get-portfolio) reports them separately (`usdc.sol`, `usdc.eth`, `usdc.base`, `usdc.arbitrum`, `usdc.bnb`, and USDG under `usdg.robinhood`); never add them together as one spendable balance. ### Sessions and minimums - **Sessions.** Treasures gates buys on the clock, not sells. - `ondo` listings follow the issuer's own per-ticker sessions. - Arbitrum and the `xstocks` listings outside Solana follow the continuous week, Sunday 20:00 ET to Friday 20:00 ET, closed on US market holidays. - `xstocks` on Solana, `backpack`, `robinhood`, `coinbase` and `bstocks` are not gated on the clock, though their liquidity can thin outside market hours (watch `tradability`). - A buy outside its session is `422 no_routes` with `reason: "market_closed"` when pinned, and loses that leg when not. A session can close on one chain while another still serves the ticker, so retry unpinned, or on another chain from `available_chains`, before waiting. - **Minimums.** `min_trade_size_usd` is the smallest size measured to fill: on the ticker, on the single-chain listing blocks, and per chain on the `ondo`, `xstocks` and `backpack` blocks (`sol_min_trade_size_usd`, `eth_min_trade_size_usd`, `bnb_min_trade_size_usd`). - The Solana figure is firm: where a market maker fills the listing, it comes from a quote bound to a wallet. With none listed, assume $3. - An order refused below a known floor carries `min_notional_usdc`, which on Solana can be the size a market maker quoted your wallet at refusal time; on a sell it is a USDC value, never a share count. It describes only the venues that refused for size: a venue that refused for another reason still needs its own fix. - Cross-chain legs have no floor, but a small order pays proportionally more for the hop. - **Advisories.** `tradability` and `warn_reason` (per chain on the `ondo`, `xstocks` and `backpack` blocks, such as `sol_tradability`), and the same two fields on each quote leg, flag a thin or untradable venue before you quote. An absent `tradability` means unmeasured or unwarned, not healthy. - **Signing windows.** Each leg carries its own `expires_at`: typically under a minute, about 40 seconds on a speed swap, and about 14 seconds on a BNB Smart Chain `ondo` or `xstocks` leg. Sign and submit inside it. ### Mistakes integrators hit most 1. **A Solana wallet with no SOL.** Its quotes are refused with `422 no_routes` and `reason: "insufficient_gas"`. Send `sol_fee_payer` on buys **and** sells, or fund the wallet with SOL. A first buy of an `ondo` token needs about 0.01 SOL in the wallet either way. 2. **Approving the wrong address on Robinhood Chain.** Its spender is `0x5A70…89C7`, not the `0x1111…0a65` used everywhere else. 3. **Treating USDG as USDC**, or adding the stablecoins of different chains together. Read `base_asset` and `chain` on every leg. 4. **Asking for priority mode on Robinhood Chain without USDG there.** The leg is dropped for `insufficient_balance`, and no cross-chain route can fill it. Bridge to USDG first, and keep ETH on Robinhood Chain for the gas. 5. **Expecting an underfunded EVM buy to fail at quote time.** On the default route it fails at submit. Check the stablecoin balance and the allowance first. 6. **Approving only one issuer's token before an Ethereum sell.** A sell can draw on every issuer's token the wallet holds. 7. **Hardcoding where a ticker trades.** Base and Arbitrum list a ticker only once it is minted, Robinhood Chain names can be listed with no liquidity, and venues switch on per ticker. Read `/stocks/tickers` at runtime. 8. **Expecting outside activity on Robinhood Chain, Base or Arbitrum to appear in `/trades`.** Only trades submitted through Treasures are recorded there. 9. **Indexing legs by array position.** Echo each leg's `quote_index`; the values can skip. --- ## Compare Access Paths There are three ways to use Treasures as an investor or a builder. (Fund managers who publish a strategy use a separate surface, the [Manager API](/managers/managing-a-strategy), which is not part of this table.) The web app is for people. The API is for software, and it comes in two tiers: anonymous (no key, which is how most AI agents start) and keyed (an integrator API key issued to your organisation). AI agents and enterprises call the same endpoints; the key is what separates the two columns on the right. | | **Web App** | **API, no key** | **API, integrator key** | | --- | :---: | :---: | :---: | | **Best for** | Individuals | AI agents, self-serve builders | Enterprises, partners, platforms | | **How you get in** | [treasures.io](https://treasures.io) | [Install the skill](/agents/integrating-your-agent) or call the [API](/api/treasures-finance-b-2-b-public-api) | [Request a key](/enterprises/enterprise-integration#getting-a-key) | | **Discover tickers, listings and live prices** | ✓ | ✓ | ✓ | | **Company profile, analyst view, earnings, news** | ✓ in the app | ✗ | ✓ [`GET /stocks/{ticker}`](/api/get-stock-detail) | | **Buy and sell quotes** | ✓ | ✓ with an [ownership proof](/overview/ownership-proof) | ✓ with an ownership proof | | **Price a trade with no wallet attached** | ✗ | ✗ | ✓ [`POST /quote/preview`](/api/quote-preview), capped at 1,000,000 USDC | | **Default routing** (gasless relayed orders on EVM chains) | ✓ | ✓ | ✓ | | **Priority mode** (single-block speed route on Robinhood Chain and Base, plus cross-chain buys for a chain the wallet is not funded on) | ✗ | ✓ | ✓ | | **Sponsored user-operation lane** (ERC-4337; Base and Robinhood Chain, and Ethereum for a cross-chain leg) | ✗ | ✓ | ✓ | | **Bridge USDC between chains** | ✓ | ✓ | ✓ | | **Portfolio: Solana and Ethereum positions** | ✓ | ✓ | ✓ | | **Portfolio: Robinhood Chain, Base, Arbitrum and BNB Smart Chain positions** | ✓ | Wallets Treasures already knows | ✓ any wallet | | **Trade history** | ✓ | ✓ | ✓ | | **Trades attributed to your organisation** | n/a | ✗ | ✓ send the key on [`POST /trade/submit`](/api/submit-trade) | | **Settlement reporting** | n/a | ✗ | ✓ [`GET /settlements`](/api/list-settlements), plus read-only `trk_` reporting keys | | **Strategy signals** (the target-weight books of copy-trading strategies, and the orders that exit or rebalance a wallet to one) | n/a | ✗ | ✓ [`/signals`](/enterprises/strategy-signals), general `tik_` key only | | **Submit up to 25 signed quotes in one request** | n/a | ✗ | ✓ [`POST /trade/submit/batch`](/api/submit-trade-batch) | | **Rate limits** | n/a | Per IP and per (IP, wallet) | Plus a per-organisation bucket shared by all your keys; `/portfolio` is bound by that bucket, not by IP | | **Fees** | 0.1% flat | 0.1% flat | 0.1% flat; custom arrangements on request | | **Your own fee on your users' trades** | n/a | ✗ | ✓ [integrator fees](/enterprises/integrator-fees-and-payouts), claimed in USDC through `/payouts` | | **Skill version headers** | n/a | Optional; the skill sends them for you | Not needed | | **Support** | Telegram, email | Telegram, email | Partnerships email | Every row in the "API, no key" column is available to a keyed caller too. A key never takes anything away; it only adds. ### Choose the web app if You want to hold and trade tokenized stocks yourself, from a browser, with a self-custodial wallet you control. There is nothing to install and no code to write. Go to [Using the Web App](/users/using-the-web-app). ### Choose the API without a key if You are building an AI agent or a personal tool that trades on behalf of one wallet pair, and you do not need company research data, wallet-less previews or reporting. Install the skill and your agent is calling the API correctly in minutes. Go to [Integrating Your Agent](/agents/integrating-your-agent). ### Choose an integrator key if You are integrating Treasures into a product with many end users, you need your trades attributed to your organisation so you can reconcile them, you want the company-research route or the wallet-less preview, you want the target-weight books of the copy-trading strategies Treasures publishes to integrators, or you want end-user wallets that merely hold tokens on Robinhood Chain or Base to show up in portfolio reads. The key also gives you a rate-limit bucket sized for your organisation instead of your IP addresses. Go to [Enterprise Integration](/enterprises/enterprise-integration). --- ## Getting Started ### Accessing Treasures Ready to get started? There are four ways in, depending on who you are: - **Web App (individuals)**: visit [https://treasures.io](https://treasures.io) to access the platform directly. Connect your wallet, and you are ready to browse and trade tokenized stocks in minutes. You can create a new self-custodial wallet through the Treasures onboarding flow or connect an existing wallet. Read more in [Using the Web App](/users/using-the-web-app). - **Agent Skill (AI agents, self-serve)**: [building an AI agent?](/agents/integrating-your-agent) Install the Treasures skill from [https://github.com/treasures-io/treasures-finance-agent-skills/](https://github.com/treasures-io/treasures-finance-agent-skills/) and load it into your agent platform. It gives your agent the context it needs to call our API correctly out of the box, and it is the only channel that uses the optional [skill version headers](/agents/agent-skills#versioning). - **Direct API Integration (any developer)**: connect straight to the Treasures REST API. Everything you need is in the [API Reference](/api/treasures-finance-b-2-b-public-api), and the spec itself is published as [OpenAPI JSON](https://docs.treasures.io/openapi.json) for code generators and agents. No key is required for discovery, quoting, trading, bridging or reading a wallet's holdings and history. - **Integrator API Key (enterprises and partners)**: contact [hello@treasures.io](mailto:hello@treasures.io) for an integrator key issued to your organisation. It unlocks the key-gated routes, [strategy signals](/enterprises/strategy-signals) included, and attributes your trades to you. Start at [Enterprise Integration](/enterprises/enterprise-integration). - **Manager API (fund managers)**: run a strategy that Treasures users follow. Treasures issues you a manager key and a strategy; you publish target weights and read your fee ledger. Start at [Managing a Strategy](/managers/managing-a-strategy). Still deciding? [Compare Access Paths](/overview/compare-access-paths) shows what each path can and cannot do. ### Fees Treasures charges a flat fee of 0.1% on all trading activity conducted through the platform. Additional gas or network fees may apply depending on the chain and transaction type, and on whether you opt into the [speed route](/overview/routing-and-priority-mode). Custom fee arrangements may be available for API partners and enterprise integrations; ask at [hello@treasures.io](mailto:hello@treasures.io). --- ## How Treasures Works ### Platform architecture Treasures is built as a distribution and interface layer for tokenized real-world assets. We sit above DEX aggregators and routing providers, using that infrastructure to facilitate user access to tokenized stock liquidity. You interact with Treasures through the [web interface](https://treasures.io) or [API](/api/treasures-finance-b-2-b-public-api). Treasures then routes your transaction requests to relevant third-party decentralized applications and protocols, which handle execution and settlement. Treasures provides the wallet, interface, routing and access layer. It does not execute or settle trades directly, does not issue the underlying assets and does not take custody of user funds at any point. ### Your wallet, your assets The Treasures wallet is your gateway to the Treasures platform. It is designed to support a non-custodial experience, meaning users remain responsible for their wallets, wallet credentials and digital assets. Treasures does not take custody, possession or control of your digital assets. When you initiate a transaction request through the web interface or API, the wallet authorizes that request, which Treasures then routes onward to the relevant third-party decentralized applications for execution and settlement. For API integrations, the wallet is also the authorization boundary. Any programmatic action operates within the permissions, parameters and controls explicitly granted by the wallet owner or relevant API user. ### User and AI agent transaction flow Human users interact with Treasures through the web interface at [https://treasures.io](https://treasures.io). The experience is designed to be intuitive: connect your wallet, browse supported assets, and execute trades in a few clicks. API users (including developers, technical users, B2B partners, custom applications, automated trading systems and AI agents) interact with Treasures through the API, as documented in the [API Reference](/api/treasures-finance-b-2-b-public-api). Integrations can query assets, obtain quotes, submit transaction requests and monitor transaction status programmatically. Any transaction that affects user assets should remain subject to the required wallet control, user authorisation and access restrictions configured for that integration. ### Liquidity and routing You do not need to worry about selecting liquidity sources or execution venues. Treasures' routing layer evaluates available paths across DEX aggregators and routing providers and directs your request via the optimal route automatically. API callers can additionally opt into a **speed route** on Robinhood Chain and Base, which trades the default gasless, relayed order for a single-block on-chain swap paid for with the wallet's own gas. The tradeoffs are laid out in [Routing and Priority Mode](/overview/routing-and-priority-mode). Treasures does not own, operate, or control these third-party protocols. They are independent decentralized infrastructure providers, and their availability and performance are outside our control. ### Intuitive units of measurement It is worth noting an important distinction for users familiar with traditional equity markets. In conventional stock trading, you buy and sell in units of shares, and one share represents one unit of ownership in the underlying company. Tokenized stocks work differently. A tokenized stock may not always correspond to the underlying shares on a 1:1 basis due to dividends and corporate events impacting number of shares held in custody. Treasures abstracts this complexity for you. Instead of requiring users to manually calculate token conversions, Treasures presents asset quantities, quotes and transaction amounts in units of underlying shares through the web interface and API responses. This helps users and agents understand what they are buying or selling without needing to manage the underlying token unit mechanics themselves. --- ## Brokerage-as-a-service for your apps and AI agents Treasures routes an order across every tokenizer and chain that lists the stock, settles it on-chain, and keeps the shares in a wallet only you control. These docs cover the web app, the public API and the ready-made agent skills. ### Start where you are For users Hold and trade tokenized stocks from the web app at treasures.io. No API involved. For AI agents Give an agent the ability to discover, quote and trade on a user's behalf. Start with the ready-made skill. For enterprises Integrate the API into your own product with an integrator key: attribution, reporting, richer data. AI agents and enterprises use the same public API. The difference is the integrator key, and what it unlocks is spelled out in [Compare Access Paths](/overview/compare-access-paths) and [Integrator API Keys](/enterprises/integrator-api-keys). The full [API Reference](/api/treasures-finance-b-2-b-public-api) has its own tab. ### Your first call Discovery needs no key. This returns every ticker Treasures currently trades, with the chains and tokenizers that list it: ```bash curl https://api.treasures.io/public/v1/stocks/tickers ``` ```json title="Response, trimmed" { "tickers": [ { "ticker": "AAPL", "name": "Apple Inc.", "available_chains": ["sol", "eth"], "min_trade_size_usd": 3, "ondo": { "...": "per-tokenizer listing" }, "xstocks": { "...": "per-tokenizer listing" }, "robinhood": { "...": "per-tokenizer listing" }, "coinbase": { "...": "per-tokenizer listing" }, "reality": { "...": "per-tokenizer listing" }, "backpack": { "...": "per-tokenizer listing" } } ] } ``` Quotes, trades and bridges are signed by the wallet that holds the funds; [Ownership Proof](/overview/ownership-proof) covers the one signature involved. From there, [Getting Started](/overview/getting-started) lists the four ways in. ### What Treasures is Treasures is a non-custodial platform that brings tokenized real-world assets on-chain and within reach of individual users, developers, AI agents and other applications. Starting with tokenized stocks, it lets users and integrations discover, access, trade and manage supported tokenized assets through a simple web interface or the API. Whether you are an individual who wants a simpler way to access tokenized assets, a developer giving an AI agent the ability to trade, or an enterprise integrating Treasures into your own product, Treasures provides the wallet, interface, routing and access layer that connects you to supported on-chain asset infrastructure. ### What you can do today - Access tokenized stocks without a traditional brokerage account, through the web interface - Let AI agents and applications discover, quote and trade tokenized stocks on behalf of users, through the API - Give enterprise integrators attributed trades, settlement reporting, richer market data and the target-weight books of Treasures copy-trading strategies through an integrator API key - Let fund managers publish a strategy's target weights that Treasures users follow, and read their share of the fees, through the [Manager API](/managers/managing-a-strategy) More asset classes and geographies are on the way. ### Supported assets Treasures currently supports tokenized stocks made available through selected infrastructure partners, including Ondo Global Markets, xStocks, Backpack Securities, Robinhood, Coinbase and Reality, subject to availability and jurisdictional restrictions. Listings cover US and Hong Kong names across Solana, Ethereum, Robinhood Chain, Base and Arbitrum; [Chains and Venues](/overview/chains-and-venues) sets out what each chain needs. Treasures is continuously evaluating additional infrastructure partners and will list supported assets once they are determined to be suitable. Future expansion may include tokenized ETFs, commodities and other real-world assets. --- ## Ownership Proof Some endpoints need to know that the wallet you're quoting for is actually yours. An **ownership proof** is a short-lived signature, made with the wallet's own key, that proves control of the wallet before Treasures issues a quote. It carries no funds and authorizes no transfer. It only proves "I hold the key to this wallet, right now." ### When it's required Two different credentials appear on this API, and they are independent of each other. An **ownership proof** is per request and per wallet: it proves you hold the key. An **integrator API key** is per organisation: it identifies the caller. A route can want neither, either or both. See [Integrator API Keys](/enterprises/integrator-api-keys) for the key model. | Endpoint | API key | Ownership proof | | --- | --- | --- | | [`POST /quote/buy`](/api/quote-buy) | Optional | Required, one signature per wallet supplied | | [`POST /quote/sell`](/api/quote-sell) | Optional | Required, one signature per wallet supplied | | [`POST /quote/preview`](/api/quote-preview) | **Required**, general `tik_` key | Not required, the preview binds no wallet | | [`POST /bridge/quote`](/api/quote-bridge) | Optional | Required: `eth_signature` always, and `sol_signature` too when either side is `sol` | | [`POST /bridge/{bridge_quote_id}/submit`](/api/submit-bridge) | Optional | Not required, the signed bridge payload is itself the authorization | | [`POST /trade/submit`](/api/submit-trade) | Optional, but send it: it is what attributes the trade to your organisation | Not required, the signed trade payload is itself the authorization | | [`POST /trade/submit/batch`](/api/submit-trade-batch) | **Required**, general `tik_` key | Not required, each signed submission authorizes itself | | [`GET /stocks/{ticker}`](/api/get-stock-detail) | **Required**, general `tik_` key | Not required | | [`GET /settlements`](/api/list-settlements) | **Required**, `tik_` or read-only `trk_` | Not required | | The [strategy signals](/enterprises/strategy-signals) reads, `GET /signals/strategies` and its detail and history routes | **Required**, general `tik_` key | Not required | | [`POST /signals-orders/exit/plan`](/api/plan-signal-orders-exit), [`POST /signals-orders/exit`](/api/quote-signal-orders-exit), [`POST /signals-orders/rebalance/plan`](/api/plan-signal-orders-rebalance), [`POST /signals-orders/rebalance`](/api/quote-signal-orders-rebalance) | **Required**, general `tik_` key | Required, `sol_signature` over the canonical challenge | | Every other `GET` read (stocks, tickers, prices, quote status, bridge status, portfolio, trades) | Optional | Not required | "Optional" means the route can be called anonymously. It does not mean a key you *do* send is ignored. A key is always verified, and a bad one is rejected rather than quietly downgraded to an anonymous call. The two key-gated read routes are gated for different reasons. [`POST /quote/preview`](/api/quote-preview) is the one quote route that binds no wallet at all, so there is nothing to prove ownership *of*, so the key identifies the caller instead. [`GET /stocks/{ticker}`](/api/get-stock-detail) is gated because its profile, analyst, earnings and news blocks are served to contracted integrators only. Neither accepts a read-only `trk_` reporting key. Issuing a quote consumes upstream liquidity-provider quota, so the quote endpoints verify ownership up front. Trade submission doesn't need a separate proof: the transaction (or EIP-712 order) you submit is signed by the same key and commits to the exact action, which is a stronger guarantee than the proof itself. ### The proof object Attach the proof as an `ownership_proof` field alongside the wallet(s) in the request body: ```json { "sol_wallet": "7xKXtg2C…", "eth_wallet": "0xab5801a7…", "ownership_proof": { "issued_at": 1750000000, "sol_signature": "", "eth_signature": "0x" } } ``` | Field | Type | Notes | | --- | --- | --- | | `issued_at` | integer (Unix seconds) | When the proof was created. Always required. | | `sol_signature` | string | Base64 Ed25519 signature. Required whenever `sol_wallet` is present. | | `eth_signature` | string | `0x`-prefixed EIP-191 `personal_sign` signature. Required whenever `eth_wallet` is present. | Send a signature for every wallet you include. Supplying only `sol_wallet` means you sign with Solana alone; supplying both wallets (which `/bridge/quote` requires whenever either side is `sol`) means both signatures are required and both are verified. ### What you sign: the canonical challenge Every signature is made over the same **canonical challenge**, a UTF-8 string built by joining four lines with `\n` (newline): ```text treasures-finance-quote-v1 ``` - **Line 1** is the fixed tag `treasures-finance-quote-v1`. It scopes the signature to this exact purpose; sign anything else and it won't verify. - **Line 2** is `issued_at` as a decimal string, the same integer you put in the proof object. - **Line 3** is your Solana wallet (base58, verbatim), or an empty line when you aren't supplying one. - **Line 4** is your Ethereum wallet, **lowercased**, or an empty line when you aren't supplying one. A checksummed (mixed-case) address will not verify. For example, a Solana-only request issued at `1750000000` signs this exact string (the trailing blank line is the absent Ethereum wallet): ```text treasures-finance-quote-v1 1750000000 7xKXtg2C… ``` ### Freshness window `issued_at` has to be recent. The server accepts a proof up to **5 minutes old** and at most **30 seconds in the future** (to tolerate minor clock drift). Anything outside that window is rejected with `ownership_proof_skewed`. Generate the proof immediately before each request rather than caching and reusing one. ### Signing examples #### Solana (Ed25519) ```ts import { Keypair } from "@solana/web3.js"; import { ed25519 } from "@noble/curves/ed25519"; function buildChallenge(issuedAt: number, solWallet: string, ethWallet: string): string { return ["treasures-finance-quote-v1", String(issuedAt), solWallet, ethWallet.toLowerCase()].join("\n"); } const keypair = Keypair.fromSecretKey(secretKey); const solWallet = keypair.publicKey.toBase58(); const issuedAt = Math.floor(Date.now() / 1000); const challenge = buildChallenge(issuedAt, solWallet, ""); // empty eth line: Solana only // noble expects the 32-byte Ed25519 seed, not the full 64-byte secret key const signatureBytes = ed25519.sign(Buffer.from(challenge, "utf8"), keypair.secretKey.subarray(0, 32)); const solSignature = Buffer.from(signatureBytes).toString("base64"); const ownershipProof = { issued_at: issuedAt, sol_signature: solSignature }; ``` #### Ethereum (EIP-191 `personal_sign`) ```ts import { privateKeyToAccount } from "viem/accounts"; function buildChallenge(issuedAt: number, solWallet: string, ethWallet: string): string { return ["treasures-finance-quote-v1", String(issuedAt), solWallet, ethWallet.toLowerCase()].join("\n"); } const account = privateKeyToAccount(privateKey); const ethWallet = account.address.toLowerCase(); const issuedAt = Math.floor(Date.now() / 1000); const challenge = buildChallenge(issuedAt, "", ethWallet); // empty sol line: Ethereum only const ethSignature = await account.signMessage({ message: challenge }); const ownershipProof = { issued_at: issuedAt, eth_signature: ethSignature }; ``` Signing for both chains in one request? Build the challenge with **both** wallet lines filled in, sign that single string with each key, and send both signatures under the same `issued_at`. Ethereum verification recovers the signer from an externally owned account (`personal_sign` / `ecrecover`). Smart-contract (EIP-1271) wallets aren't supported; use an EOA. ### Error codes A failed proof returns `401` with one of: | `error` | Meaning | | --- | --- | | `ownership_proof_skewed` | `issued_at` is outside the freshness window; regenerate with a current timestamp. | | `ownership_proof_sol_invalid` | The Solana signature didn't verify against `sol_wallet`. | | `ownership_proof_eth_invalid` | The Ethereum signature didn't verify against `eth_wallet`. | | `ownership_proof_invalid` | The proof was malformed, or no wallet was supplied to verify against. | When both wallets are present, Solana is checked first, so a request with two bad signatures surfaces `ownership_proof_sol_invalid` first. Fix it and retry to see the Ethereum result. --- ## Routing and Priority Mode By default Treasures picks the route for you. A quote can come back with legs on more than one chain, ordered cheapest first, and on the EVM chains those legs are relayed orders that cost the wallet no gas beyond its one-time approvals. **Priority mode** (`priority: "speed"`) changes who pays and what you sign: it asks for a single-block on-chain swap on Robinhood Chain and Base instead of a relayed order, and can serve a buy on a chain the wallet is not funded on through a [cross-chain leg](#cross-chain-legs). On a sell, [`payout_chain`](#paying-out-a-sell-on-another-chain-payout_chain) changes them too, whatever the `priority`. This page lays out the difference chain by chain, and what you give up for the speed. For how the options combine, what each kind of leg asks you to sign, and recipes for common goals, see [Buying and Selling](/overview/buying-and-selling). For each chain's own rules (its stablecoin, approvals, gas and which options it takes), see [Chains and Venues](/overview/chains-and-venues). ### Default routing Send a buy or sell quote with no `priority` and Treasures evaluates every chain the ticker lists (or the subset you allow with `chain` and `protocol`), ranks the candidates and returns up to one leg per chain. You can nudge the order with `preferred_chain`, which moves that chain's leg to `quote_index: 0` without adding or dropping anything. | Chain | Default route | Who pays gas | What you sign | | --- | --- | --- | --- | | `sol` | On-chain swap | The wallet, in SOL, or a [wallet you fund](/overview/buying-and-selling#paying-solana-fees-for-your-users) (`sol_fee_payer`) | A Solana transaction | | `eth` | Relayed order, gasless | Nobody on your side; a settlement network broadcasts | An EIP-712 typed-data order | | `robinhood` | Relayed order, gasless | Nobody on your side | An EIP-712 typed-data order | | `base` | Relayed order, gasless | Nobody on your side | An EIP-712 typed-data order | | `arbitrum` | Relayed order, gasless | Nobody on your side | An EIP-712 typed-data order | | `bnb` | For `ondo` and `xstocks`: relayed order, gasless | Nobody on your side | An EIP-712 typed-data order | On `sol`, three protocols are ranked against each other: `ondo`, `xstocks` and `backpack` (Backpack Securities, Solana only). A `backpack` leg is an ordinary Solana leg. To leave a protocol out, send the ones you want as a `protocol` array. `arbitrum` is Reality's venue on Arbitrum One. A ticker is listed there once its token is minted, and buys follow the market week (Sunday 20:00 to Friday 20:00 ET, closed on US market holidays), so read the [listings](/api/list-stock-tickers) rather than assuming it is there. `bnb` is BNB Smart Chain (56); which of its issuers are open is in [Chains and Venues](/overview/chains-and-venues#at-a-glance). It is the one EVM chain with more than one issuer (`ondo` and `xstocks` list there, and `bstocks` lists there alone), so read each leg's `protocol` rather than inferring it from `chain`. Three things differ from the other EVM chains: - its stablecoin is 18-decimal Binance-Peg USDC, which is not interchangeable with USDC on any other chain - an `ondo` or `xstocks` leg there must be signed and submitted within about 14 seconds of the quote (read that leg's own `expires_at`) - its one-time approvals cost BNB, not ETH. The only gas a default-route caller ever pays is Solana's, plus the one-time ERC-20 approvals, any bridge broadcasts and a [sell paid out on another chain](#paying-out-a-sell-on-another-chain-payout_chain), which are always the wallet's own transactions. #### Ranking by where your money is: `origin_chain` By default every leg is ranked as if your stablecoin already sat on its own chain, so `quotes[0]` can be a leg on a chain you hold nothing on. Send `origin_chain` (`sol`, `eth`, `robinhood` or `base`) on `/quote/buy` or `/quote/preview` with the chain your stablecoin actually sits on, and every leg on another chain is ranked as if it also paid the measured cost of moving the money there. `quotes[0]` is then the cheapest leg for money held on that chain. - **Ranking only.** No leg is added, dropped or repriced, and a leg on another chain is still a same-chain leg. Fund its chain first (for example through a [bridge](/api/quote-bridge)), then re-quote. - **The transfer cost excludes your own gas** for sending the transfer on the origin chain, which matters most on `eth`. - **The wallet must be in the request.** On `/quote/buy`, an `origin_chain` without that chain's wallet (`sol_wallet` for `sol`, `eth_wallet` otherwise) is `400 invalid_request`. `/quote/sell` does not take the field. - Under `priority: "speed"` it also picks where a [cross-chain leg](#cross-chain-legs) spends from. ### Priority mode: `priority: "speed"` Speed is a **filter, not a preference**. Under `priority: "speed"` the same-chain candidates are Solana (unchanged, its route is already fast) and the speed routes on Robinhood Chain and Base. Ethereum is never quoted on its own route under speed, and a Robinhood Chain or Base leg the speed route cannot serve is left out of the response with a warning rather than handed back on its relayed route. A buy can also come back as a [cross-chain leg](#cross-chain-legs) when the wallet is not funded on a listing's chain, and a buy's Solana leg that your `sol_wallet` cannot fund is dropped rather than quoted (when that leaves nothing and no other chain's wallet covers the amount, the refusal reads `insufficient_balance`). | Chain | Under `priority: "speed"` | Who pays gas | What you sign | | --- | --- | --- | --- | | `sol` | The normal on-chain swap; a buy's leg the wallet cannot fund is dropped | The wallet, in SOL | A Solana transaction | | `eth` | **Never on its own route.** On `/quote/buy` and `/quote/preview` it can come back as a [cross-chain leg](#cross-chain-legs), so a `chain: "eth"` pin yields that leg or `422 no_routes`. On `/quote/sell`, pinning `chain: "eth"` (or `["eth"]`) together with speed is `400 invalid_request` and a wider `chain` set simply loses `eth`, unless the sell [pays out on another chain](#paying-out-a-sell-on-another-chain-payout_chain) | See [cross-chain legs](#cross-chain-legs) | See [cross-chain legs](#cross-chain-legs) | | `robinhood` | Speed route: a single on-chain swap that settles in one block | **The wallet, in native ETH on Robinhood Chain (4663)**, or your paymaster on the [sponsored lane](#the-sponsored-lane-execution-user_operation) | One complete unsigned transaction (`evm_signed_tx`), or two when an approve is needed; one `evm_calls` payload on the sponsored lane | | `base` | Speed route: a single on-chain swap that settles in one block | **The wallet, in native ETH on Base (8453)**, or your paymaster on the [sponsored lane](#the-sponsored-lane-execution-user_operation) | One complete unsigned transaction (`evm_signed_tx`), or two when an approve is needed; one `evm_calls` payload on the sponsored lane | | `arbitrum` | **Never quoted.** There is no speed route; pinning `chain: "arbitrum"` together with speed is `400 invalid_request` | n/a | n/a | | `bnb` | `bstocks` only: its leg is the same complete transaction at every priority, so speed changes nothing for it. `ondo` and `xstocks` have no speed route; a speed buy pinned to `bnb` for them is `422 no_routes`, and a speed sell pinned that way is `400 invalid_request` | The wallet, in BNB, for `bstocks` | One complete unsigned transaction, or two when an approve is needed | Every leg carries `gasless` so you can tell the two apart without inspecting payload types: `true` for a relayed order, `false` for a speed-route leg. Speed-route legs also carry `estimated_gas_usd`, the figure the route ranking charged against them; it is `null` when no USD gas price was available, with a `speed_route_unpriced_gas` warning naming the chain, and the leg is still a speed-route leg. ### What you trade away Speed moves several things that the relayed route handles for you onto your side: - **Native gas.** The wallet must hold enough native ETH on that chain to fund the broadcast. A signed transaction whose `gas × fee` exceeds the balance fails at submit with `insufficient_native_gas`; fund the wallet and re-quote. - **An unlimited allowance, signed by you.** No pre-approval is needed: a wallet that has not approved the router gets an `approve` payload bundled before the `swap`. That approve grants the router an unlimited (`max-uint256`) allowance on the token being spent. You are signing that consent, so surface it to your user. - **Two payloads, in order.** When a pair is issued, sign and return both, in the order issued, branching on each payload's `role` (`approve`, then `swap`, or `deposit` on a cross-chain leg) rather than on array position. Signing only the first is `incomplete_submit`; reordering them on a replay is read as a new submit, `leg_already_submitted`. - **Nonces.** Only one speed trade per wallet per chain can be in flight. A second collides as `nonce_conflict`; wait for the first to go terminal, then re-quote. Never re-nonce, re-estimate or re-serialize a payload: the server compares the signed bytes with the ones it issued. - **Approve failures.** On a pair, `tx_hash` is the swap's from the start but appears on chain only after the approve mines. `approve_failed` means the approve reverted or did not land within 10 minutes and the swap was never sent; `tx_hash` is then `null`. Re-quote. - **Absent legs, with one exception on a sell.** A chain the speed route cannot serve is missing from `quotes[]` with a `speed_route_unavailable` warning carrying `chain` and a `reason`: `disabled`, `insufficient_balance`, `no_routes`, `provider_error`, or `wallet_not_delegated` on the sponsored lane. The list is open; treat an unknown reason as "unavailable, reason unknown". Re-quote without `priority` to get the relayed route on that chain. - **The exception: a sell that falls back.** On `/quote/sell`, a Robinhood Chain or Base position the speed route answers `no_routes` for is in `quotes[]` on its relayed route, disclosed by a `speed_route_fallback` warning. - That leg has `gasless: true` and one typed-data payload, also when you sent `execution: "user_operation"`, and its fill can take minutes. Branch on `gasless` per leg, not on the `priority` you sent. - The warning carries `chain`, `protocol`, `reason` (`no_routes`), `approval_needed` and `approval_spender`. When `approval_needed` is `true`, the order cannot fill until the wallet approves the stock token to `approval_spender`: a relayed order never bundles an approval and this API does not send it for you, so the order is refused as `not_enough_balance_or_allowance` or expires unfilled. `false` means the allowance covers the sale; `null` means it could not be read, so check it yourself. - Buys never fall back. A position the relayed route priced but another leg outranked reads `speed_route_unavailable` with `reason: "no_routes"`. - **A refusal that names what it skipped.** When speed leaves nothing to quote, the `422 no_routes` lists each listing speed never quotes (an `eth` or `bnb` relayed order, or Reality on `arbitrum`) in `warnings[]` as `speed_route_unavailable` with `reason: "no_speed_venue"`, `chain` and `protocol`. Re-quote without `priority` to reach them, if a relayed order that can take minutes to fill works for you. - **A gas estimate, not a bound.** `estimated_gas_usd` is an estimate over a live gas market. The signed transaction bounds what you can actually spend; the string does not. ### Cross-chain legs Under speed, `/quote/buy` and `/quote/preview` can serve a listing on a chain the wallet is not funded on as a **cross-chain leg**: your stablecoin leaves the chain it sits on and the purchase is filled on the listing's chain. `origin_chain` is present only on such a leg, so its presence is the marker; `chain` stays the destination. `eth/ondo` (a `chain: "eth"` pin included), `sol/xstocks`, `sol/backpack` and, on an unpinned or multi-chain request, `base/coinbase` can be reached this way. A single-chain `base` or `robinhood` pin always routes same-chain, and `robinhood`, `sol/ondo` and `eth/xstocks` are never cross-chain destinations. - **Where the funds leave from.** Only a listing the wallet is not funded on goes cross-chain. With [`origin_chain`](#ranking-by-where-your-money-is-origin_chain), the leg spends only from that chain, so its `origin_chain` always equals the value you sent, and if that chain does not cover the amount no cross-chain leg is offered. Without it, the origin is the first chain in the order `sol`, `eth`, `robinhood`, `base` among the wallets you sent that covers the amount. `/quote/preview` reads no balance, so it prices as if the whole amount sits on `origin_chain` (`sol` when you omit it). - **Cost.** `cross_chain_cost_bps` and `cross_chain_cost_usdc` disclose the hop's own cost, and `cost_breakdown_bps.dex_swap_fee_bps` is `null` on the leg. `base_asset` and `amount_base` name what left your wallet (the origin's currency), not the destination's. - **What you sign.** From `sol`, one Solana transaction with your own wallet as fee payer, so the leg is `gasless: false`. From an EVM chain, a `role: "deposit"` transaction, preceded by an `approve` for the **exact amount** (not unlimited) when the wallet has no allowance yet; on the [sponsored lane](#the-sponsored-lane-execution-user_operation), one `evm_calls` payload instead. `gasless` and `estimated_gas_usd` describe the **origin** chain. - **Both wallets.** A `422 no_routes` with `reason: cross_chain_wallet_missing` means the buy could only be served from a chain whose wallet you did not send. Send both `sol_wallet` and `eth_wallet`. - **Warnings.** `cross_chain_route_unavailable` (with `chain`, `protocol` and `reason`) means the cross-chain attempt for that listing fell back to its normal speed plan, which on `eth` means no leg at all. `cross_chain_price_deviation` flags a leg priced more than 500 bps from the reference market, and `exit_gas_unfunded` flags a destination wallet without the native gas to sell the position later. Both are advisory; the leg is executable. - **Leg outcomes.** Besides the usual ones, a cross-chain leg can fail with `refunded` (the deposit came back to your origin wallet), `deposit_reverted`, or a per-leg `quote_stale` (a Solana origin's transaction expired before broadcast); re-quote after any of them. `delivered_other_currency` is terminal: you received a stablecoin instead of the token. `cross_chain_unsettled` means 6 hours passed with no outcome: **do not re-quote**, because it may still fill or refund. ### The sponsored lane: `execution: "user_operation"` If you run an ERC-4337 stack you can make a Robinhood Chain or Base speed leg gasless again. Send `execution: "user_operation"` together with `priority: "speed"` and the leg comes back as **one `evm_calls` payload** instead of a signed-transaction pair. Pack it into an ERC-4337 v0.7 UserOperation from the wallet, which must be EIP-7702-delegated to Modular Account v2 on that chain or have no code there yet (its first operation then carries the delegation as `eip7702Auth`), sponsor it with your own paymaster, sign, and return it as `evm_user_operation`. Treasures submits it to a bundler and tracks it. The leg is then `gasless: true` with `estimated_gas_usd: "0"`, and there is no nonce to collide on. Two refusals exist only on this lane: `sponsorship_rejected` (your paymaster declined) and `wallet_not_delegated` (the wallet is delegated to code other than Modular Account v2 on that chain; `400` when pinned, a drop reason when not). Sending `execution: "user_operation"` without `priority: "speed"` is `400 invalid_request`. The lane serves Base and Robinhood Chain. A chain it cannot serve at the moment is dropped with `speed_route_unavailable` and `reason: "disabled"`, or refused as `422 no_routes` when pinned. A [cross-chain leg](#cross-chain-legs) can use this lane too. Its `evm_calls` payload carries a `deposit` call in place of the `swap`, `sender` is your wallet on the origin chain, and `chain_id` can also be `1` (Ethereum) for an Ethereum-origin leg. It is `gasless: true` and its `estimated_gas_usd` is `null`, because the gas is your paymaster's. ### Paying out a sell on another chain: `payout_chain` `POST /quote/sell` takes `payout_chain` (`sol`, `eth` or `base`) to have the sale's USDC land on that chain, in your own wallet there (`sol_wallet` on `sol`, `eth_wallet` on `eth` and `base`). It is independent of `priority` and sell-only: sending it to `/quote/buy` or `/quote/preview` is `400 invalid_request`. Absent or `null` sells every position on its own chain, as before. `robinhood`, `arbitrum` and `bnb` are not payout chains. Each position you hold is planned on its own terms: - A position already on `payout_chain` sells there as usual. Under speed it keeps the speed filter, so an `eth` position is left out when paying out on `eth`. - A `sol/xstocks`, `sol/backpack`, `base/coinbase` or `eth/ondo` position on another chain sells cross-chain as one leg, marked by `payout_chain` on the leg, with no separate payout step to submit. This is also why `chain: ["eth"]` together with speed is accepted when the payout is elsewhere. - Any other position (`sol/ondo`, `eth/xstocks`, `robinhood`, `arbitrum`) is left out, named by a `cross_chain_route_unavailable` warning. It is never sold on its own chain instead. Whatever the `priority`, the wallet pays the gas for a cross-chain sell leg on the position's own chain (`gasless: false`), and `estimated_gas_usd` prices it (`null` on `sol`). The one exception is the sponsored lane, where your paymaster pays and the leg is `gasless: true`. On `eth` or `base` the leg always carries two payloads: an exact-amount `approve` of the tokens sold, then a `deposit` that sells them and sends the USDC on. On the sponsored lane the same two calls come as one `evm_calls` payload sent from your `eth_wallet`. On `sol` it is one Solana transaction with your wallet as fee payer. `estimated_output_usdc` is what lands on `payout_chain`, and `cross_chain_cost_bps` / `cross_chain_cost_usdc` disclose the hop's own cost. The refusals are specific. `400 invalid_request` (message prefixed `payout_chain: `) means the payout chain's wallet is missing, or nothing in your `chain` and `protocol` scope can pay out there. `422 holdings_insufficient` means your holdings fall short. `422 no_routes` with `reason: payout_route_unavailable` means you hold enough, but not enough of it can pay out on that chain; pay out elsewhere, drop `payout_chain`, or re-quote later. After submit, the status leg and the `GET /trades` row carry `payout_chain` and `payout_tx_hash` (the payout transaction, `null` until `completed`), while `tx_hash` stays the sale. If the payout could not be made, the USDC may be returned on the sale's own chain, and `payout_chain` then equals `chain`. ### Reading the response - `gasless` on every leg says who pays. Under speed, a `gasless: true` leg is Solana, unless you are on the sponsored lane. - `origin_chain` marks a cross-chain buy leg and `payout_chain` a cross-chain sell leg; both are absent on every same-chain leg. - `estimated_gas_usd` appears on speed-route legs (on a cross-chain leg it prices the origin chain) and on sell legs paid out on another chain, never on a relayed leg. - `poll_after_ms` on `GET /quote/{quote_id}/status` drops to `1250` while a speed-route leg is in flight, because it settles by receipt within a block or two, and `tx_hash` is the on-chain transaction to watch. - `user_op_hash` appears on submit results and status legs for the sponsored lane and is `null` elsewhere. On a cross-chain leg on that lane `tx_hash` stays `null` until the leg is terminal, so `user_op_hash` is the handle to watch. ### When to use it Use the default route when you want the wallet to spend no gas beyond its one-time approvals and can wait for a relayed fill. Use priority mode when settlement inside one block matters more, the wallet is funded with native ETH on that chain (or you sponsor it), and your integration can handle the nonce and two-payload rules above. [Buying and Selling](/overview/buying-and-selling) walks through every combination with recipes. Field-level detail for every request and response key is in the [quote reference](/api/quote-buy). --- ## Security and Compliance ### Access restrictions Treasures and the tokenized stocks accessible through the platform are not available in the U.S. or in any other restricted jurisdictions; see our [Terms of Use](https://treasures.io/legal/terms-of-use) for the full list. Access may be restricted or unavailable based on your country of residence or the location from which you are connecting. All wallets interacting with Treasures are screened against applicable sanctions lists. Wallets associated with sanctioned individuals, entities or addresses will be denied access. ### Your responsibility You are responsible for ensuring your use of Treasures complies with all laws and regulations applicable in your jurisdiction. Treasures does not provide investment, legal, tax or financial advice. Trading tokenized assets involves various risks, including market risk, liquidity risk, technology risk, third-party protocol risk and regulatory risk. For full terms and disclaimers, please refer to our [Terms of Use](https://treasures.io/legal/terms-of-use). ### Keep your keys safe Your private keys are yours. We never store, access, or have the ability to recover them. If your keys are compromised, your assets may be irretrievably lost. Never share your private key or seed phrase with anyone. ### Protocol and market risks Interactions with on-chain protocols carry inherent risks, including but not limited to liquidity risk and network congestion. --- ## Support We are always here to help. Reach out anytime! ### Partnership and business enquiries For partnerships and business development conversations, please contact the Treasures team via email at [hello@treasures.io](mailto:hello@treasures.io). ### Integration and technical support For any technical or integration support, please join our Treasures telegram support group at [https://t.me/treasuresfinance](https://t.me/treasuresfinance) or contact the Treasures team via email at [hello@treasures.io](mailto:hello@treasures.io). --- ## Supported Services Here is a quick overview of what you can do through Treasures. Everything below is available to any API caller unless it says otherwise; [Compare Access Paths](/overview/compare-access-paths) shows the same list by audience. ### Discover assets Treasures allows users and integrations to discover a [full list of supported tokenized assets](/api/list-stock-tickers), including asset symbols, names, supported networks, [indicative pricing](/api/get-stock-prices) availability and trading availability. A single ticker may be listed by more than one infrastructure partner, each on its own network, and availability is reported per listing rather than per symbol. Read the listing response rather than hardcoding a set. Partners bring assets online over time, and a listing can also carry a warning that it is currently thin or untradable. Need everything the catalog knows about a single name? [Company and ticker details](/api/get-stock-detail) returns the profile (description, sector, industry, website, logo) alongside every listing, the traditional-market snapshot, the pre- and post-market print, market session, analyst consensus and grades, next earnings and the latest news, in one call. It requires an [integrator API key](/enterprises/integrator-api-keys), and every block is best-effort: anything the upstream cannot supply comes back `null` rather than failing the call. For per-protocol on-chain prices keep using [prices](/api/get-stock-prices); this route deliberately does not carry them. ### Wallet infrastructure Create or connect a [self-custodial wallet](https://treasures.io) and use it as your identity and permission layer across all Treasures services. Wallet access can be embedded into the user experience or connected through an external supported wallet provider. ### Get quotes and execute trades Get live, time-limited execution quotes for any supported tokenized stock, then [submit your transaction request](/api/submit-trade) for routing and execution. Treasures handles the routing to on-chain infrastructure automatically. Supports both [buy](/api/quote-buy) and [sell](/api/quote-sell) flows. Each chain has its own stablecoin, approvals and gas rules; [Chains and Venues](/overview/chains-and-venues) lists them. Pricing a trade you don't intend to execute (a screener, a widget, a what-if)? Use the [price preview](/api/quote-preview). It returns the same legs a buy quote would, with no wallet and no ownership proof, and nothing is persisted: there is no quote to submit and no status to poll. It requires an [integrator API key](/enterprises/integrator-api-keys) precisely because it binds no wallet; the key is what identifies the caller. Previews are capped at 1,000,000 USDC and draw on a rate limit shared by every caller of the route, so honour `Retry-After` rather than retrying immediately. Re-quote through [buy](/api/quote-buy) for anything you intend to sign. Two chains also offer a **speed route**: a single on-chain swap that settles in one block instead of a relayed order. Ask for it with `priority: "speed"` on a buy or sell quote and you get back a complete unsigned transaction to sign, which Treasures broadcasts against your own wallet's native gas. It is available on Robinhood Chain and Base, and on Base it can be made gasless again through a sponsored user operation if you run an ERC-4337 stack. Under speed, a buy of a listing on a chain the wallet is not funded on can also come back as a single cross-chain leg, paid from the chain your stablecoin is on. A Solana wallet holding no SOL can still trade when you pay its fees: send `sol_fee_payer`, a Solana wallet you fund, on buy and sell quotes, and sign each Solana leg that carries it with both wallets. See [Buying and Selling](/overview/buying-and-selling#paying-solana-fees-for-your-users). A sell can pay its USDC out on another chain: send `payout_chain` (`sol`, `eth` or `base`) on a [sell quote](/api/quote-sell) and the proceeds of every position that can pay out there land in your own wallet on that chain, with no separate bridge step. The full tradeoff table and both cross-chain flows are in [Routing and Priority Mode](/overview/routing-and-priority-mode). ### Portfolio and trade history Read your [current holdings](/api/get-portfolio) and [trade history](/api/list-trades) via the [web app](https://treasures.io) or API. Useful for building dashboards, reconciliation workflows or agent memory. Portfolio snapshots refresh every 30 seconds (`as_of`, `is_cached`), so polling faster returns the same snapshot. Under heavy load the route can answer `503 portfolio_busy` with a `Retry-After` header in seconds; sleep that long and retry the same request. A cached snapshot is never refused. Positions on Robinhood Chain, Base, Arbitrum and BNB Smart Chain are read for every wallet when you send an [integrator API key](/enterprises/integrator-api-keys), and otherwise only for wallets Treasures already knows. ### Settlement reporting Integrators holding an API key can read [their organisation's settled trades](/api/list-settlements), newest first, with cursor pagination. Only trades submitted with the API key presented are attributed to the organisation and appear here. A submit sent without the header is attributed to no one and cannot be recovered afterwards. Keys come in two kinds, issued per organisation by the Treasures team. - A general `tik_` key reaches every route on the API. - A read-only `trk_` reporting key reaches the reporting routes and nothing else (today that is exactly this one) and answers `insufficient_scope` everywhere else, which is what makes it safe to hand to a third-party reporting partner. These routes require a key: this one, [company and ticker details](/api/get-stock-detail), the [price preview](/api/quote-preview), the [payout routes](/enterprises/integrator-fees-and-payouts), the [strategy signals](/enterprises/strategy-signals) routes and [batch trade submission](/api/submit-trade-batch), all but this one taking a `tik_` key only. Every other route may be called anonymously, but a key you send is still verified and still earns your organisation attribution and its own rate bucket. The route-by-route table is on [Integrator API Keys](/enterprises/integrator-api-keys). ### Strategy signals Integrators holding a general key can read the [target-weight books](/enterprises/strategy-signals) of the copy-trading strategies Treasures publishes to them: the current book, its history, and a hash that changes only when the weights move. Four more routes turn a book into orders for one of your users' wallets, either the sells that exit it or the sells and buys that rebalance to it: all four for a Solana wallet, and the two plan routes for a wallet on BNB Smart Chain. The wallet's owner signs and submits them like any other trade. ### Deposits and withdrawals [Move USDC](/api/quote-bridge) between any two supported chains: Solana, Ethereum, Robinhood Chain, Base, Arbitrum and, where supported, BNB Smart Chain. Broadcast the deposit yourself, or quote with `delivery: "submit"` and hand Treasures the signature to [submit](/api/submit-bridge), which from Ethereum, Base or Arbitrum needs no native gas. Deposit and withdrawal availability may depend on the asset, network, wallet type, integration channel and applicable compliance controls. --- ## Using the Web App The Treasures web app at [https://treasures.io](https://treasures.io) is the way individuals access tokenized stocks. There is nothing to install and no code to write: connect a wallet, browse, and trade. This page covers what to expect. If you are building software rather than trading yourself, the [For AI Agents](/agents/integrating-your-agent) and [For Enterprises](/enterprises/enterprise-integration) sections are for you. ### Getting in Go to [treasures.io](https://treasures.io) and connect a wallet. You can create a new self-custodial wallet through the Treasures onboarding flow, or connect a wallet you already hold. The wallet is yours. Treasures is non-custodial: it never holds, controls or can recover your keys or your assets, and every trade you make is authorized by your wallet. See [Your Wallet, Your Assets](/overview/how-treasures-works#your-wallet-your-assets) for how that works. ### What you can do - **Browse supported tokenized stocks.** US and Hong Kong names, listed by selected infrastructure partners across Solana, Ethereum, Base, Robinhood Chain and BNB Smart Chain, subject to availability. A name can be listed by more than one partner, and availability is shown per listing. A listing can also carry a warning that it is currently thin or untradable. - **See the company behind a ticker.** Profile, sector, market data and related information alongside the on-chain listings. - **Buy and sell.** Get a live, time-limited quote and confirm it. Treasures routes the trade to the best available on-chain venue for you; there are no liquidity sources or execution venues to choose. - **Track your holdings and history.** Your positions, idle cash and past trades, in one place. - **Move USDC in and out.** Deposit USDC to fund trades and withdraw it when you want, where supported. ### Units you will see Traditional brokers deal in shares. A tokenized stock may not map to the underlying shares exactly one to one, because dividends and corporate events change the number of shares held in custody behind each token. Treasures handles that conversion for you: quantities, quotes and transaction amounts are always shown in units of underlying shares, so what you see is what you are buying or selling. The full explanation is in [Intuitive Units of Measurement](/overview/how-treasures-works#intuitive-units-of-measurement). ### Fees Treasures charges a flat fee of 0.1% on all trading activity. Additional gas or network fees may apply depending on the chain and transaction type; the quote you confirm shows what you will pay. ### Deposits and withdrawals You fund trades with USDC and can withdraw USDC where supported. Deposit and withdrawal availability may depend on the asset, network, wallet type and applicable compliance controls. ### Where you can use Treasures Treasures and the tokenized stocks accessible through it are not available in the U.S. or in other restricted jurisdictions; see the [Terms of Use](https://treasures.io/legal/terms-of-use) for the full list. All wallets are screened against applicable sanctions lists. The detail is in [Security and Compliance](/overview/security-and-compliance). ### Keep your keys safe Your private keys are yours, and Treasures cannot recover them. If they are compromised, your assets may be lost for good. Never share your private key or seed phrase with anyone. ### Getting help Join the Treasures Telegram group at [https://t.me/treasuresfinance](https://t.me/treasuresfinance) or email [hello@treasures.io](mailto:hello@treasures.io). See [Support](/overview/support). --- ## Agent Skills Pre-built skills that teach an AI coding agent to use the Treasures APIs correctly. Treasures' [agent skills repository](https://github.com/treasures-io/treasures-finance-agent-skills) provides structured context that AI coding agents load when building on Treasures. Each skill is a `SKILL.md` file plus a set of reference documents: endpoint playbooks, signing code, first-time traps, error tables and rate limits, all written to be consumed by an agent rather than read by a person. Install a skill and your agent knows how to discover tokenized stocks, quote, sign, submit, poll and read holdings without you pasting API docs into a prompt. The skills are the deep end of the Treasures documentation for agents. This site is the human-readable layer; the skills carry the detail an agent needs to execute. ### Available skills #### treasures-b2b-api Build an agent on the public B2B API for a single end-user wallet pair. This is the starting point for any agent that holds or is granted the user's own wallet keys. | Area | What the skill covers | | --- | --- | | Discover | `GET /stocks/tickers` and `GET /stocks/prices`: listings per chain, tradability warnings, live tradfi and on-chain prices, share multipliers | | Quote | `POST /quote/buy` and `POST /quote/sell`: chain and protocol selection, `priority: "speed"`, `origin_chain` ranking, `sol_fee_payer` for Solana wallets holding no SOL, `warnings[]` and the acknowledgement token, per-leg quote TTLs | | Sign and submit | Every signable payload type, the one-time ERC-20 approvals, `POST /trade/submit`, buy-one-leg versus sell-all-legs, `broadcast_unknown` handling | | Bridge | `POST /bridge/quote` between any two supported chains and status polling, EVM and Solana sign-and-broadcast with the `nonce=0` trap, and `delivery: "submit"` with `POST /bridge/{bridge_quote_id}/submit` | | Read | `GET /portfolio`, `GET /trades`, `GET /settlements` and `GET /stocks/{ticker}` with their semantics and caching | | Ownership proof | The canonical challenge, base64 Ed25519 and EIP-191 signing, embedded-wallet pitfalls, test vectors | | Errors and limits | The HTTP error matrix with backoff policies, rate limits per endpoint, native gas floors, simulate-before-broadcast | | Venues | Backpack Securities on Solana (a third Solana protocol, bare tickers), Robinhood Chain (USDG-priced, sign-only), Base (supply-gated B20 tokens), Arbitrum (Reality, supply-gated), BNB Smart Chain (three issuers on one chain), the speed route with its cross-chain legs, sells that pay out on another chain (`payout_chain`), and the sponsored user-operation lane | The `openapi.yaml` published with the skill carries the [strategy signals](/enterprises/strategy-signals) routes and [`POST /trade/submit/batch`](/api/submit-trade-batch), both of which need an integrator key, but the skill's own guidance does not walk through the signals routes; read that page and the [API Reference](/api/signals) directly. Install: ```bash npx skills add treasures-io/treasures-finance-agent-skills --skill treasures-b2b-api ``` #### treasures-wallet Operate a Treasures delegated wallet over HTTPS with only an API key. The agent never signs: Treasures signs as a delegated signer scoped strictly to tokenized-stock trades. No web3 libraries, no private keys, no RPC. | Area | What the skill covers | | --- | --- | | Onboard | Provision a wallet and mint a scoped `twk_` API key in one call; store the key once, it is never shown again | | Quote | Buy and sell previews, including multi-leg sells split across venues | | Trade | Async buys and sells with an `Idempotency-Key`, per-leg job polling, partial fills as a real outcome | | Read | Balances, portfolio, trade history and P&L for the wallet | | Keys | Scopes, caps, and what a revoked key looks like | Install: ```bash npx skills add treasures-io/treasures-finance-agent-skills --skill treasures-wallet ``` Not sure which one you need? If the user brings their own wallet and your agent will sign with it, use `treasures-b2b-api`. If you want Treasures to hold and operate a wallet on the user's behalf behind an API key, use `treasures-wallet`. ### How skills work Skills use the open Agent Skills format that the [`skills` CLI](https://github.com/vercel-labs/skills) installs for 70+ coding agents. Each skill is a `SKILL.md` file with structured frontmatter (`name`, `description`, `metadata.version`, `tags`) and Markdown content the agent loads as context, with longer reference files it reads on demand. Every skill is a plain folder you can read yourself. When you install a skill it is added to your project or your agent's global skills directory, so your coding agent (Claude Code, Codex, Cursor, Copilot, Windsurf and others) can reference it when writing or running code. The agent uses the skill to pick the right endpoint, build correct requests, sign correctly and handle errors the way the API expects. ```bash # Install both Treasures skills (requires Node.js) npx skills add treasures-io/treasures-finance-agent-skills # Target specific agents npx skills add treasures-io/treasures-finance-agent-skills -a claude-code -a codex -a cursor ``` Claude Code users can also install the repo as a plugin marketplace: ```text /plugin marketplace add treasures-io/treasures-finance-agent-skills /plugin install treasures-finance-agent-skills@treasures-finance-agent-skills ``` Prefer a manual copy? Clone the repo and drop `skills/` into your agent's skills directory (for example `~/.claude/skills/`). ### skill.md This site also serves a machine-readable navigator at [docs.treasures.io/skill.md](https://docs.treasures.io/skill.md). It is a short file that points an agent at the available skills and what each one does, for agents that discover capabilities from a docs URL rather than a package. The docs themselves follow the [llms.txt](https://llmstxt.org/) convention: [docs.treasures.io/llms.txt](https://docs.treasures.io/llms.txt) indexes every guide as plain Markdown (append `.md` to a page URL for its Markdown copy) and lists every endpoint, [docs.treasures.io/llms-full.txt](https://docs.treasures.io/llms-full.txt) holds every guide in one file, and the specs are at [docs.treasures.io/openapi.json](https://docs.treasures.io/openapi.json) and [docs.treasures.io/manager-openapi.json](https://docs.treasures.io/manager-openapi.json). ### Versioning Each skill declares a `metadata.version`, and the API can read it. The `treasures-b2b-api` skill sends two request headers on every call: ```http X-Treasures-Skill: treasures-b2b-api X-Treasures-Skill-Version: 1.23.0 ``` They are **optional on every route**. A caller that omits them (a direct REST integration, an enterprise backend, a hand-written script) is a generic client: never gated, never blocked, never warned. Sending them opts the agent into early warning as the API evolves: | Signal | Meaning | What the skill does | | --- | --- | --- | | `X-Treasures-Skill-Latest` response header, on every quote, trade and bridge response | The published version of each skill | Tells the user once that an update exists. Never blocks or changes a trade decision | | `Deprecation`, `Sunset`, `Warning`, `Link` response headers | Your skill is ageing; `Sunset` is the date it stops working when one is published | Finishes the current operation, then tells the user to update | | `426 skill_version_unsupported`, before any fund moves | Your skill is past its sunset | Stops. Surfaces the response's `upgrade` command and does not retry or trade | No version is gated today; every release so far has been additive on the request, so an older skill keeps working. Releases are listed newest first in the repo's [CHANGELOG](https://github.com/treasures-io/treasures-finance-agent-skills/blob/main/CHANGELOG.md), with entries that need action marked **Action**. The [API Changelog](/changelog) on this site tracks the same surface from the API's side. To update an installed skill, run the install command again, or `/plugin marketplace update` in Claude Code. ### Contributing The skills repository is open source under the MIT licence. Open an issue or a pull request at [treasures-io/treasures-finance-agent-skills](https://github.com/treasures-io/treasures-finance-agent-skills) to report a gap, improve a reference, or adapt a skill for your own use. --- ## Integrating Your Agent Building an AI agent that can trade tokenized stocks on behalf of users? Here is everything you need. ### Agent integration overview At a high level, integrating an agent with Treasures involves two steps: connect a wallet to your agent so it can act on behalf of its user, then enable the agent to call the relevant endpoints to query assets, get quotes and submit trades. No API key is needed for any of that. Every route an agent needs for a single wallet pair is open, and the only credential involved is the wallet's own signature. If your agent later needs company research data, wallet-less previews or reporting, those routes take an [integrator API key](/enterprises/integrator-api-keys); see [Compare Access Paths](/overview/compare-access-paths) for what the key adds. ### Channels of access There are two ways to give your agent access to Treasures: - **Via the Skill (recommended)**: the fastest way to get an agent working. Install the Treasures skill with `npx skills add treasures-io/treasures-finance-agent-skills`, or as a Claude Code plugin, and your agent gets structured instructions for calling our API correctly, including the signing details and first-time traps that are easy to get wrong. [Agent Skills](/agents/agent-skills) covers what is in it and how to install it. The skill also sends the optional [skill version headers](/agents/agent-skills#versioning) so your agent is told when it is out of date. - **Direct API Integration**: call the Treasures REST API directly as documented in the [API Reference](/api/treasures-finance-b-2-b-public-api). Nothing about the API changes when you skip the skill; you simply do not get the version warnings. ### What your agent can do - Discover the list of available assets and where each one is listed - Retrieve real-time prices and execution quotes - Submit buy and sell trade requests, including sells whose USDC is [paid out on another chain](/overview/routing-and-priority-mode#paying-out-a-sell-on-another-chain-payout_chain) - Choose the [speed route](/overview/routing-and-priority-mode) on Robinhood Chain and Base when one-block settlement matters more than gasless execution - Monitor trade and transaction status - Bridge USDC between any two supported chains Before your agent trades on a chain, give it the rules in [Chains and Venues](/overview/chains-and-venues): what the wallet must hold there, which approvals to send, and who pays the gas. - View current holdings and trade history - With an integrator key: look up company profiles, analyst views, earnings and news for a ticker, price a trade with no wallet attached, read the target-weight books of Treasures [copy-trading strategies](/enterprises/strategy-signals), and get the orders that exit one or rebalance a Solana or BNB Smart Chain wallet to it ### User authorization and wallet control Your agent must operate within explicit permissions granted by the wallet owner. Before taking any action, the user must authorize the agent to act on their behalf and connect the relevant wallet. Agents cannot initiate transactions outside of what the user has approved. ### Transaction request flow Here is how a typical buy comes together: - The agent looks up the target asset with [`GET /public/v1/stocks/tickers`](/api/list-stock-tickers) and confirms it is available to trade on the chain the user holds USDC on. - It then pulls live pricing from [`GET /public/v1/stocks/prices?tickers={ticker}`](/api/get-stock-prices): tradfi and on-chain prices, plus the on-chain address, token ticker and share multiplier it needs downstream. - With pricing in hand, the agent signs an [ownership proof](/overview/ownership-proof) and requests an executable quote from [`POST /public/v1/quote/buy`](/api/quote-buy). - Adding `priority: "speed"` here opts into the [speed route](/overview/routing-and-priority-mode): a single-block on-chain swap on Robinhood Chain and Base, returned as a complete unsigned transaction and paid for with the wallet's own native gas, instead of the default relayed order that costs the wallet no gas. - Under speed, a listing on a chain the wallet is not funded on can come back as a [cross-chain leg](/overview/routing-and-priority-mode#cross-chain-legs), marked by `origin_chain`. - It reads `warnings[]` on the quote and surfaces anything relevant to the user, then signs the returned trade payloads and submits them through [`POST /public/v1/trade/submit`](/api/submit-trade), which broadcasts them. [Buying and Selling](/overview/buying-and-selling) shows how to sign each kind of leg, whichever options the quote was requested with. - The agent polls [`GET /public/v1/quote/{quote_id}/status`](/api/get-quote-status) until the transaction reaches a terminal state. - Once it settles, the agent reads back the latest holdings from [`GET /public/v1/portfolio?sol_wallet={sol_wallet}ð_wallet={eth_wallet}`](/api/get-portfolio). - At any point, it can review past activity with [`GET /public/v1/trades?sol_wallet={sol_wallet}ð_wallet={eth_wallet}`](/api/list-trades). Two optional detours sit off that path, both behind an [integrator key](/enterprises/integrator-api-keys). [`GET /public/v1/stocks/{ticker}`](/api/get-stock-detail) returns the company profile, analyst view, earnings date and latest news behind a ticker, and [`POST /public/v1/quote/preview`](/api/quote-preview) prices a trade before any wallet is in play. Neither produces anything you can submit; re-quote through `/quote/buy` for that. ### Monitoring transaction status After submitting a trade, poll [`GET /quote/{quote_id}/status`](/api/get-quote-status) until a terminal status is returned. Every response carries `poll_after_ms`, the shortest useful interval before the next poll: short while a speed-route leg is in flight (it settles within a block or two), longer when only relayed or Solana legs remain, and `null` once the aggregate is terminal. Poll at that interval and never faster than once per second; polling faster only returns the same cached view and spends your rate limit. Portfolio reads are snapshotted for 30 seconds (`as_of`, `is_cached` in the response), so polling [`GET /portfolio`](/api/get-portfolio) faster than that returns the same snapshot. Under heavy load the route can answer `503 portfolio_busy` with a `Retry-After` header in seconds; sleep that long and retry the same request. A cached snapshot is never refused. --- ## Copying a Strategy on BNB Smart Chain This guide shows how to follow a Treasures strategy from a wallet on BNB Smart Chain: ask for a plan, then quote, sign and submit each order, one at a time. Treasures never holds the key and never signs for you. It is the worked example for [Strategy Signals: On BNB Smart Chain](/enterprises/strategy-signals#on-bnb-smart-chain), which lists every rule. ### The flow 1. **Plan.** [`POST /signals-orders/rebalance/plan`](/api/plan-signal-orders-rebalance) with `chain: "bnb"` compares what your wallet holds with the strategy's book and returns the orders that close the gap. Nothing is quoted and nothing expires. 2. **Execute each order.** For every order in the plan: quote it, sign the quote within about 14 seconds, submit it, and poll it until it settles. Then move to the next order. 3. **Plan again.** Buys spend only the `amount_usdc` you sent, never the proceeds of sells in the same plan. Once your sells have settled, call the plan again with the USDC now committed to the strategy (`funding.next_amount_usdc` when every order filled) to place the buys that were deferred. Repeat until the plan returns no orders. To leave a strategy, use [`POST /signals-orders/exit/plan`](/api/plan-signal-orders-exit) the same way: it returns one full sell per name you hold. ### Before your first order - **A general [integrator API key](/enterprises/integrator-api-keys)**, sent as `X-API-Key` on every call. - **Binance-Peg USDC on BNB Smart Chain** in the wallet. It is an 18-decimal token and is not the same asset as USDC on other chains. - **Token approvals.** A buy needs the wallet's Binance-Peg USDC approved to the router; a sell needs the stock token approved. The plan tells you which are missing in `approvals` (see below). Sending an approval is an ordinary transaction, so keep a small amount of BNB for gas. Trades themselves cost no gas. ### What the plan returns ```json { "strategy_id": "cst_...", "book_hash": "9f2c...", // send back as expected_book_hash to detect a changed book "signal_id": "...", "as_of": 1794900000, "nav_usdc": "512.40", // what you hold in the strategy's names, plus amount_usdc "usdc_available": "140.250000", // Binance-Peg USDC in the wallet "funding": { "usdc_spendable": "100", "buys_required_usdc": "180", "buys_scaled": true, // buys were scaled down to fit amount_usdc "buys_deferred_usdc": "80", "buys_deferred_until_sells_settle": true, "next_amount_usdc": "161.20" // the next call's amount_usdc, if every order here fills }, "orders": [ { "ticker": "NVDA", "side": "sell", "shares": "0.412", "notional_usdc": "61.20" }, { "ticker": "AAPL", "side": "buy", "shares": null, "notional_usdc": "42.500000" } ], "skipped": [ { "ticker": "TSLA", "side": "buy", "reason": "below_min_notional", "detail": null } ], "approvals": [ { "token": "0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d", "spender": "0x...", "approval_required": true } ] } ``` - **A sell is exact in shares.** Send `shares` as `amount_shares` on [`POST /quote/sell`](/api/quote-sell). Its `notional_usdc` is an estimate of the position's value. - **A buy is exact in USDC.** Send `notional_usdc` as `amount_usdc` on [`POST /quote/buy`](/api/quote-buy). `shares` is `null` because the share count depends on the price when you quote. - **`skipped`** lists every name that was not ordered, and why: for example `below_min_notional` (under the venue minimum), `not_tradable` (no BNB listing), `awaiting_sell_proceeds` or `insufficient_balance` (not enough `amount_usdc` this round). - **`approvals`**: `spender` is the router contract that settles your orders (`0x111111125421cA6dc452d289314280a0f8842A65`). `true` means approve that token to `spender` before you trade it, or the order is refused at submit. `false` means the allowance is enough. `null` means it could not be read: check the allowance yourself before signing. Minimums: an order for a name that only lists as xStocks on BNB Smart Chain must be at least $10; other names $1. When `amount_usdc` is short, every buy is scaled down in proportion, and a buy that falls under its minimum is skipped, so a small amount spread over many names can place no buys at all. The shortfall stays in `funding.buys_deferred_usdc`. ### Sample: plan, then execute one order at a time TypeScript with [viem](https://viem.sh). The sample is sequential on purpose: each quote must be signed within about 14 seconds, so quote an order only when you are ready to sign it. ```ts import { privateKeyToAccount } from "viem/accounts"; const API = "https://api.treasures.io/public/v1"; const account = privateKeyToAccount(process.env.ETH_PRIVATE_KEY as `0x${string}`); const headers = { "content-type": "application/json", "x-api-key": process.env.TREASURES_API_KEY ?? "", }; // The only contract an order from this guide is signed for: the router your approvals name as `spender`. const ROUTER = "0x111111125421ca6dc452d289314280a0f8842a65"; const POLL_LIMIT_MS = 5 * 60_000; type Json = Record; type Order = { ticker: string; side: "buy" | "sell"; shares: string | null; notional_usdc: string | null }; // usdcDelta: USDC this order added to (a sell) or took from (a buy) the wallet, in micro-units. type Outcome = { ticker: string; side: string; result: string; usdcDelta: bigint; detail?: unknown }; async function call(method: "GET" | "POST", path: string, body?: unknown): Promise<{ status: number; body: Json }> { const res = await fetch(`${API}${path}`, { method, headers, body: body === undefined ? undefined : JSON.stringify(body), }); return { status: res.status, body: (await res.json()) as Json }; } const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms)); // USDC amounts are decimal strings: handle them as integer micro-units, never as floats. const toMicro = (usdc: string) => { const [whole, fraction = ""] = usdc.split("."); return BigInt(whole) * 1_000_000n + BigInt(`${fraction}000000`.slice(0, 6)); // rounds down }; const fromMicro = (micro: bigint) => `${micro / 1_000_000n}.${String(micro % 1_000_000n).padStart(6, "0")}`; // A fresh proof per call: it is valid for about five minutes. async function ownershipProof() { const issuedAt = Math.floor(Date.now() / 1000); const challenge = ["treasures-finance-quote-v1", String(issuedAt), "", account.address.toLowerCase()].join("\n"); return { issued_at: issuedAt, eth_signature: await account.signMessage({ message: challenge }) }; } // 1. Plan. Omit amountUsdc to only reshuffle what the wallet already holds. async function plan(strategyId: string, amountUsdc?: string, expectedBookHash?: string) { const res = await call("POST", "/signals-orders/rebalance/plan", { strategy_id: strategyId, chain: "bnb", eth_wallet: account.address, ownership_proof: await ownershipProof(), amount_usdc: amountUsdc, expected_book_hash: expectedBookHash, }); // 409 book_changed carries the new book_hash: read the book again, then re-plan. if (res.status !== 200) throw new Error(`plan refused: ${res.status} ${res.body.error}`); return res.body; } // Sign only the gasless order payload. Never sign anything else from this loop: a token permit is // typed data too, so check the type, the chain and the contract, not just the payload kind. async function signPayload(payload: Json) { if (payload.type !== "evm_eip712_typed_data") throw new Error(`unexpected payload ${payload.type}`); const { domain, types, primaryType, message } = payload.typed_data; if (primaryType !== "Order") throw new Error(`unexpected typed data ${primaryType}`); if (domain.chainId !== 56) throw new Error(`unexpected chain ${domain.chainId}`); if (String(domain.verifyingContract).toLowerCase() !== ROUTER) { throw new Error(`unexpected contract ${domain.verifyingContract}`); } const { EIP712Domain: _omit, ...typesNoDomain } = types; // viem adds the domain type itself const signature = await account.signTypedData({ domain, types: typesNoDomain, primaryType, message }); return { type: "evm_eip712_signature" as const, signature }; } // 2. One order: quote, sign, submit, poll to a final status. async function executeOrder(order: Order, maxSlippageBps: number): Promise { const nothing = { ticker: order.ticker, side: order.side, usdcDelta: 0n }; const common = { ticker: order.ticker, chain: "bnb", protocol: ["ondo", "xstocks"], // the venues the plan read; do not leave this unpinned eth_wallet: account.address, ownership_proof: await ownershipProof(), max_slippage_bps: maxSlippageBps, }; const quote = order.side === "sell" ? await call("POST", "/quote/sell", { ...common, amount_shares: order.shares }) : await call("POST", "/quote/buy", { ...common, amount_usdc: order.notional_usdc }); // Typical refusals: no_routes, slippage_exceeded, amount_too_small, market_closed. if (quote.status !== 200) return { ...nothing, result: "quote_refused", detail: quote.body }; // Sign every leg of this quote straight away. A sell can return more than one leg. const signed = []; for (const leg of quote.body.quotes as Json[]) { const signedPayloads = []; for (const payload of leg.signable_payloads as Json[]) signedPayloads.push(await signPayload(payload)); signed.push({ quote_index: leg.quote_index, signed_payloads: signedPayloads }); } const submit = await call("POST", "/trade/submit", { quote_id: quote.body.quote_id, signed }); if (submit.status !== 200) return { ...nothing, result: "submit_refused", detail: submit.body }; const results = submit.body.results as Json[]; // not_enough_balance_or_allowance here means a missing approval or too little balance. if (results.every((leg) => leg.status === "broadcast_failed")) { return { ...nothing, result: "broadcast_failed", detail: results }; } // `broadcast` and `broadcast_unknown` both mean: poll, never re-submit. const deadline = Date.now() + POLL_LIMIT_MS; while (Date.now() < deadline) { const status = await call("GET", `/quote/${quote.body.quote_id}/status`); if (status.status === 200 && status.body.aggregate_status !== "in_progress") { const filled = (status.body.legs as Json[]).filter((leg) => leg.status === "completed"); const usdcDelta = order.side === "sell" ? filled.reduce((sum, leg) => sum + toMicro(leg.filled_usdc), 0n) // proceeds received : filled.length > 0 ? -toMicro(order.notional_usdc ?? "0") // a filled buy spent what it was quoted for : 0n; return { ...nothing, usdcDelta, result: status.body.aggregate_status, detail: status.body.legs }; } await sleep(status.body.poll_after_ms ?? 3250); } // Still open: the order may yet fill. Stop the whole run rather than open a second order or // size the next round without it; check the status by hand before running again. throw new Error(`${order.side} ${order.ticker}: quote ${quote.body.quote_id} not final after ${POLL_LIMIT_MS / 1000}s`); } // 3. One round: plan, stop on a missing approval, then run the orders in the order given. async function runRound(strategyId: string, amountUsdc: string | undefined, maxSlippageBps: number) { const planned = await plan(strategyId, amountUsdc); const blocked = (planned.approvals as Json[]).filter((row) => row.approval_required !== false); if (blocked.length > 0) { throw new Error(`approve or check these tokens first: ${blocked.map((row) => row.token).join(", ")}`); } const outcomes: Outcome[] = []; for (const order of planned.orders as Order[]) { outcomes.push(await executeOrder(order, maxSlippageBps)); // one at a time, sells first } return { planned, outcomes }; } // Never above what the wallet holds: an amount_usdc over the balance is refused. async function capAtWalletCash(budget: bigint): Promise { const wallet = await call("GET", `/portfolio?eth_wallet=${account.address}`); if (wallet.status !== 200) throw new Error(`portfolio refused: ${wallet.status}`); const cash = toMicro(wallet.body.usdc.bnb); return cash < budget ? cash : budget; } // Round 1 places the sells and the buys the budget covers. Later rounds place the deferred buys. // The budget is what you committed, plus what sells actually paid, minus what buys actually spent. // funding.next_amount_usdc is the same sum assuming every planned order fills, so it is only right // when they all do. async function copyStrategy(strategyId: string, amountUsdc: string | undefined, maxSlippageBps = 300) { let budget = amountUsdc === undefined ? 0n : toMicro(amountUsdc); for (let round = 1; round <= 4; round += 1) { // "0" is refused: omit amount_usdc instead. const amount = budget === 0n ? undefined : fromMicro(budget); const { planned, outcomes } = await runRound(strategyId, amount, maxSlippageBps); console.log(`round ${round}`, outcomes.map((o) => `${o.side} ${o.ticker}: ${o.result}`)); if (planned.orders.length === 0) return; // Nothing filled this round: stop instead of repeating the same refusals. if (outcomes.every((o) => o.usdcDelta === 0n)) return; budget = await capAtWalletCash(outcomes.reduce((sum, o) => sum + o.usdcDelta, budget)); } } await copyStrategy("example-13f", "100"); ``` ### Things to get right - **Sign fast.** A quote on BNB Smart Chain must be signed and submitted within about 14 seconds. If you miss it, quote the order again; never re-submit an old quote. - **Check what you sign.** Sign a payload only when its `primaryType` is `Order`, its `domain.chainId` is 56 and its `domain.verifyingContract` is the router above. Compare against an address you hold in your own code, not one read from a response. - **Always pin `protocol` to `["ondo","xstocks"]`** on the per-order quotes. The plan only reads those venues, so an unpinned quote could trade a token the plan did not count. - **bStocks holdings are not counted.** The plan reads only the Ondo and xStocks tokens in the wallet. A strategy name you hold as bStocks reads as not held: a rebalance buys its full target again, an exit leaves it in the wallet, and it is not part of `nav_usdc`. Sell it yourself first if you do not want both. - **The quote is the firm price, not the plan.** Prices move between the two. If a quote is refused, skip that name for this round and let the next plan pick it up. - **Slippage.** During the US session a `max_slippage_bps` of 100 is enough for most names; outside it, xStocks often need about 300. - **`broadcast_unknown` is not a failure.** The order may be live. Poll its status; do not quote the same order again until the status is final. If it is still not final after a few minutes, stop, as the sample does: do not start the next order or plan again while one may still fill. - **Size the next round from what actually filled.** `funding.next_amount_usdc` assumes every planned order fills. If a sell failed or a buy was refused, it is wrong: compute the next `amount_usdc` as what you sent, plus the USDC your sells paid (`filled_usdc` on their completed status legs), minus what your filled buys spent, as the sample does. Never send more than the wallet's Binance-Peg USDC (`usdc.bnb` on `GET /portfolio`): an amount above the balance is refused with `422 insufficient_balance`. `"0"` is refused too, so omit `amount_usdc` instead. - **Rate limits.** The rebalance plan route allows 12 calls a minute per wallet. Wait for a round to settle before planning the next. ### Where to go next - [Strategy Signals](/enterprises/strategy-signals): the books, the plan routes, every skip reason and refusal. - [Chains and Venues](/overview/chains-and-venues#bnb-smart-chain-bnb): BNB Smart Chain's stablecoin, approvals and signing window. - [Ownership Proof](/overview/ownership-proof): the signature each plan and quote call carries. - [API Reference](/api/signals): every field on the signals routes. --- ## Enterprise Integration This section is for partners, platforms and applications integrating the Treasures API into their own product, typically for many end users at once. It assumes you will call the REST API from your own backend and hold an integrator API key issued to your organisation. Enterprises and AI agents share the same public API. What sets an enterprise integration apart is the key, and this page is about what the key gives you and how to build around it. ### What you get with an integrator key - **Routes that only open with a key.** - [`GET /stocks/{ticker}`](/api/get-stock-detail) for company research data - [`POST /quote/preview`](/api/quote-preview) to price a trade with no wallet attached - [`GET /settlements`](/api/list-settlements) for your organisation's settled trades - the [`/payouts`](/enterprises/integrator-fees-and-payouts) routes to claim your integrator fees - the [strategy signals](/enterprises/strategy-signals) routes for the target-weight books of the copy-trading strategies published to integrators and the orders that act on them - [`POST /trade/submit/batch`](/api/submit-trade-batch) to submit up to 25 signed quotes in one request. - **Your own fee on your users' trades.** Quotes requested with your key charge your [integrator fee](/enterprises/integrator-fees-and-payouts), which you claim in USDC whenever you choose. - **Attribution.** A trade submitted with your key on [`POST /trade/submit`](/api/submit-trade) is recorded against your organisation and appears in your settlement reporting. Without the key it is attributed to no one and cannot be claimed afterwards. - **Complete portfolio reads for your end users.** With your key, [`GET /portfolio`](/api/get-portfolio) reads Robinhood Chain, Base, Arbitrum and BNB Smart Chain positions for any wallet you ask about, including wallets that hold tokens they never traded through Treasures. Anonymous reads only cover wallets Treasures already knows. - **A rate-limit bucket sized for your organisation.** Presenting a valid key adds a per-organisation budget shared by all of your keys, and `/portfolio` is bound by that budget instead of your IP addresses. - **Read-only reporting keys** you can hand to a third party. A `trk_` key reaches `GET /settlements` and nothing else. Everything else on the API works exactly as it does for an anonymous caller. The full route-by-route breakdown is on [Integrator API Keys](/enterprises/integrator-api-keys), and [Compare Access Paths](/overview/compare-access-paths) shows the three tiers side by side. ### Getting a key Integrator keys are issued per organisation by the Treasures team, out of band. Contact [hello@treasures.io](mailto:hello@treasures.io) to set up your organisation. You will receive a general `tik_` key for API access; ask for a `trk_` reporting key as well if a third party needs read access to your settlements. ### Integration flow The endpoints are the same ones an agent uses. The difference is where the signing happens and that every call carries your key. Two headers are all you need: `Content-Type: application/json` on any request with a body, and `X-API-Key` on every request. The `X-Treasures-Skill` headers you may notice in the agent skill are optional and only matter to skill users ([details](/agents/agent-skills#versioning)). 1. **Discover.** [`GET /stocks/tickers`](/api/list-stock-tickers) for the catalog with per-listing availability and warnings, [`GET /stocks/prices`](/api/get-stock-prices) for live tradfi and on-chain prices. Add [`GET /stocks/{ticker}`](/api/get-stock-detail) when you need the profile, analyst view, earnings or news behind a name. 2. **Preview, if you need a price before a wallet is involved.** [`POST /quote/preview`](/api/quote-preview) returns the same legs a buy quote would, with nothing persisted and nothing to submit. Useful for screeners, widgets and what-if displays. Re-quote through `/quote/buy` for anything you intend to execute. 3. **Quote.** [`POST /quote/buy`](/api/quote-buy) or [`POST /quote/sell`](/api/quote-sell) with an [ownership proof](/overview/ownership-proof) signed by the end user's wallet key. The proof is per request and per wallet; your key identifies your organisation, and the proof proves control of the wallet. Both go on the request. Read `warnings[]` and decide what to surface to your user. 4. **Sign and submit.** Sign each returned payload with the end user's wallet key, through whatever key management you run, then [`POST /trade/submit`](/api/submit-trade) with your `X-API-Key`. That header is what attributes the trade to you. 5. **Track.** Poll [`GET /quote/{quote_id}/status`](/api/get-quote-status) at the response's `poll_after_ms` until the aggregate is terminal. 6. **Read holdings.** [`GET /portfolio`](/api/get-portfolio) and [`GET /trades`](/api/list-trades) per end-user wallet pair, always with your key so that holdings on Robinhood Chain, Base, Arbitrum and BNB Smart Chain are read for every wallet. 7. **Reconcile.** [`GET /settlements`](/api/list-settlements), newest first, cursor-paginated. Only settled fills appear, which on Ethereum and Robinhood Chain can be minutes after submission. If your totals must be exact, re-scan roughly the last two hours on each pass rather than trusting the cursor alone: a small number of Solana trades are settled by a recovery job that records the on-chain block time, so a row can land behind a cursor you have already paged past. `trade_id` is stable, so re-scanned rows deduplicate cleanly. Bridging USDC between any two supported chains works the same way as for any caller: [`POST /bridge/quote`](/api/quote-bridge) with an ownership proof (both wallets when either side is Solana), sign and broadcast the returned transaction yourself, then poll [`GET /bridge/{bridge_quote_id}/status`](/api/get-bridge-status). Quote with `delivery: "submit"` instead and you hand the signature to [`POST /bridge/{bridge_quote_id}/submit`](/api/submit-bridge), and Treasures sends the deposit; from Ethereum, Base or Arbitrum that is one or two typed-data signatures and no native gas (this mode leaves from Solana, Ethereum, Base or Arbitrum only, for now). ### Routing choices Each chain has its own stablecoin, approval address and gas rules, and a quote can mix chains. Read [Chains and Venues](/overview/chains-and-venues) before you go live on a chain. By default Treasures routes each trade automatically and relayed orders on Ethereum, Robinhood Chain, Base, Arbitrum and BNB Smart Chain (`ondo`, `xstocks`) cost the wallet no gas beyond its one-time approvals on each chain. On Solana the wallet pays its own fees unless a market maker fills the trade, and a wallet holding almost no SOL is refused there; if your end users' wallets hold none, send [`sol_fee_payer`](/overview/buying-and-selling#paying-solana-fees-for-your-users) on every buy and sell quote and pay those fees from one Solana wallet you fund (a first buy of an `ondo` token still needs about 0.01 SOL in the user's wallet). You can pin or restrict `chain` and `protocol`, prefer a chain with `preferred_chain`, or opt into the speed route with `priority: "speed"` on Robinhood Chain and Base when one-block settlement matters more than gasless execution. Under speed a buy can also come back as a cross-chain leg, and on a sell `payout_chain` pays the USDC out on another chain. The speed route puts gas, nonces and an unlimited token allowance on your side of the ledger, so read [Routing and Priority Mode](/overview/routing-and-priority-mode) before turning it on for end users. [Buying and Selling](/overview/buying-and-selling) maps every combination of these options to the legs it returns and how to sign each one. ### Rate limits Three layers apply to a keyed caller: - **Per IP and per (IP, wallet)** buckets on each endpoint, as for any caller. - **Per organisation**, shared by all of your keys, added whenever a valid key is presented. It is a cross-IP aggregate, additive to the per-IP limits rather than a raised ceiling. `/portfolio` is the exception: with a general key it is not bucketed by IP at all, and the organisation bucket is sized for one request every 5 seconds per active end user. Portfolio snapshots refresh every 30 seconds, so polling faster returns the same snapshot, and under load the route can answer `503 portfolio_busy` with a `Retry-After` header; sleep that long and retry. - **A shared ceiling on `POST /quote/preview`** that every caller of that route draws on together, because a preview needs no wallet and is the cheapest request to make in bulk. A `429` there may be someone else's traffic. Honour `Retry-After` and retry rather than backing off for a whole minute, and read the `X-RateLimit-*` headers on that route as the shared bucket, not as your own. The inline [strategy signals](/enterprises/strategy-signals#limits-on-the-inline-routes) order routes have a shared ceiling of their own, counted in upstream quote calls. Every `429` carries `Retry-After` in seconds. Sleep exactly that long. ### Fees Treasures charges a flat 0.1% on trading activity, shown on every quote leg as `treasures_fee_bps` alongside the venue's own fee and the estimated slippage. Custom fee arrangements may be available for enterprise integrations; ask at [hello@treasures.io](mailto:hello@treasures.io). You can also charge your own fee on the trades your users make through you. It is set per key, can be overridden per quote with `integrator_fee_bps`, shows on each leg as `cost_breakdown_bps.integrator_fee_bps`, and pays out to you on demand. [Integrator Fees and Payouts](/enterprises/integrator-fees-and-payouts) covers setting it, reconciling it and claiming it. ### Where to go next - [Integrator API Keys](/enterprises/integrator-api-keys): key kinds, the per-route table, what each key-gated route returns, error codes. - [Integrator Fees and Payouts](/enterprises/integrator-fees-and-payouts): your own fee on your users' trades, and claiming it. - [Strategy Signals](/enterprises/strategy-signals): the target-weight books of the copy-trading strategies published to integrators, and the orders that exit or rebalance a wallet to one. - [Ownership Proof](/overview/ownership-proof): the signature your end user's wallet makes on every quote. - [Buying and Selling](/overview/buying-and-selling): quote options, what each combination returns, and how to sign every kind of leg. - [Routing and Priority Mode](/overview/routing-and-priority-mode): the speed-route tradeoffs. - [API Reference](/api/treasures-finance-b-2-b-public-api): every field on every route, key-gated ones included. - [Support](/overview/support): partnerships and technical contact. --- ## Integrator API Keys An integrator API key identifies your organisation to the Treasures API. It goes in the `X-API-Key` header. This page lists the two kinds of key, what each route does with one, exactly what the key-gated routes return, and the errors a key can produce. A key and an [ownership proof](/overview/ownership-proof) are independent credentials. The proof is per request and per wallet: it proves control of the wallet. The key is per organisation: it identifies the caller. A route can want neither, either or both. The [strategy signals](/enterprises/strategy-signals) order routes want both. ### Two kinds of key | Prefix | Name | Reaches | Purpose | | --- | --- | --- | --- | | `tik_` | General key | Every route | API access. Use this for your integration | | `trk_` | Reporting key | `GET /settlements` only | Read-only. Safe to hand to an accountant, an auditor or a reporting partner: everywhere else it answers `403 insufficient_scope` | Both kinds are issued per organisation by the Treasures team; see [Getting a key](/enterprises/enterprise-integration#getting-a-key). A credential for a different Treasures product (for example a `twk_` wallet key) is not addressed to this API and is ignored, so such requests are served anonymously. ### What a key does on each route "Optional" means the route can be called without a key. It does not mean a key you send is ignored: every key is verified, and a bad one is rejected rather than quietly downgraded to an anonymous call. | Route | Key | What changes when you send one | | --- | --- | --- | | [`GET /stocks/{ticker}`](/api/get-stock-detail) | **Required**, `tik_` only | The whole route. Company profile, listings, tradfi snapshot, extended hours, market session, analyst consensus and grades, next earnings, latest news | | [`POST /quote/preview`](/api/quote-preview) | **Required**, `tik_` only | The whole route. Prices a trade with no wallet and no ownership proof | | [`GET /settlements`](/api/list-settlements) | **Required**, `tik_` or `trk_` | The whole route. Your organisation's settled trades | | [`GET /payouts/accrued`](/api/get-accrued-integrator-fees), [`POST /payouts`](/api/request-payout), [`GET /payouts`](/api/list-payouts), [`GET /payouts/{payoutId}`](/api/get-payout) | **Required**, `tik_` only | The whole routes. What you are owed in [integrator fees](/enterprises/integrator-fees-and-payouts), claiming it, and your payout history | | [`GET /signals/strategies`](/api/list-signal-strategies), [`GET /signals/strategies/{id}`](/api/get-signal-strategy), [`GET /signals/strategies/{id}/history`](/api/list-signal-strategy-history) | **Required**, `tik_` only | The whole routes. The target-weight books of the [copy-trading strategies published to integrators](/enterprises/strategy-signals) | | [`POST /signals-orders/exit/plan`](/api/plan-signal-orders-exit), [`POST /signals-orders/exit`](/api/quote-signal-orders-exit), [`POST /signals-orders/rebalance/plan`](/api/plan-signal-orders-rebalance), [`POST /signals-orders/rebalance`](/api/quote-signal-orders-rebalance) | **Required**, `tik_` only, plus an ownership proof for the wallet | The whole routes. The orders that [exit a strategy book or rebalance a wallet to it](/enterprises/strategy-signals#acting-on-a-book-from-a-wallet) | | [`POST /trade/submit/batch`](/api/submit-trade-batch) | **Required**, `tik_` only | The whole route. Up to 25 signed quotes submitted in one request, each answered as `POST /trade/submit` would | | [`POST /trade/submit`](/api/submit-trade) | Optional, but send it; **required** for a quote that carries your fee | The trade is attributed to your organisation and appears in `GET /settlements`. A submit without the key is attributed to no one and cannot be recovered afterwards. A quote carrying your integrator fee must be submitted with the key that quoted it (`403 quote_integrator_mismatch`) | | [`GET /portfolio`](/api/get-portfolio) | Optional, but send it | Positions on Robinhood Chain, Base, Arbitrum and BNB Smart Chain are read for **any** `eth_wallet`, not only wallets Treasures already knows. Rate limiting moves from your IP to your organisation bucket | | [`POST /quote/buy`](/api/quote-buy), [`POST /quote/sell`](/api/quote-sell) | Optional | Your [integrator fee](/enterprises/integrator-fees-and-payouts) is charged: your configured default, or the `integrator_fee_bps` you send, reported on each leg as `cost_breakdown_bps.integrator_fee_bps`. The key is verified and your organisation bucket applies. Company details are not part of a quote; they come from `GET /stocks/{ticker}` | | `GET /stocks`, `GET /stocks/tickers`, `GET /stocks/prices`, `GET /quote/{quote_id}/status`, `POST /bridge/quote`, `POST /bridge/{bridge_quote_id}/submit`, `GET /bridge/{bridge_quote_id}/status`, `GET /trades` | Optional | The key is verified and your organisation bucket applies. Nothing else | The portfolio row deserves a sentence more. Treasures reads positions on Robinhood Chain, Base, Arbitrum and BNB Smart Chain only for wallets it has a reason to know about, which bounds address enumeration by anonymous callers. Your end users' wallets are not Treasures wallets, and a wallet that merely holds a token there (an airdrop, a transfer in) has no record anywhere until it trades. Without your key such a wallet comes back with an empty `positions` list and is not flagged `partial`. With your key, every wallet you ask about is read. Idle cash on those chains (`usdc.base`, `usdg.robinhood`) is never gated either way. ### What the key-gated routes return #### `GET /stocks/{ticker}` Everything the catalog knows about one ticker, in one call and cached for 60 seconds: - **Profile**: `name`, `description`, `sector`, `industry`, `website`, `logo_url`, `display_ticker`, `exchange`, `exchange_country`, `data_delay` - **Listings**: `available_chains` and a `listings` array with one entry per (protocol, chain), each carrying its own availability and any tradability warning - **Market data**: the `tradfi` snapshot, the `extended_hours` (pre- and post-market) print, `market_session`, and `is_holiday` / `holiday_name` - **Research**: `analyst` consensus, `analyst_grades`, the next `earnings` date and the latest `news` Every block is best-effort and degrades to `null` on its own, so a missing analyst block never fails the call. The route deliberately carries no on-chain price block; for per-protocol on-chain prices keep using [`GET /stocks/prices`](/api/get-stock-prices). It takes no query parameters. #### `POST /quote/preview` The buy-quote shape with no wallet and no ownership proof. It prices every chain the ticker lists (or those your `chain` and `protocol` filters allow) and returns the same legs [`POST /quote/buy`](/api/quote-buy) would, minus `quote_id`, `expires_at`, every leg's `signable_payloads` and `warnings_ack_token`. Nothing is persisted: there is no status to poll and nothing to submit. Re-quote through `/quote/buy` for anything you intend to sign. It reads no balance. Send [`origin_chain`](/overview/routing-and-priority-mode#ranking-by-where-your-money-is-origin_chain) to rank the legs for money held on one chain; under `priority: "speed"` the preview prices as if the whole amount sits there (`sol` when you omit it). Two things to know about its limits. `amount_usdc` is capped at 1,000,000 on this route. And on top of your per-IP and per-organisation budgets, the route has one ceiling shared by every caller, because a preview needs no wallet and is the cheapest request to make in bulk. A `429` here can be someone else's traffic: honour `Retry-After` and retry, and read `X-RateLimit-*` on this route as the shared bucket rather than your own. Identical requests inside a 10-second window are answered from one price lookup. #### `GET /settlements` Every trade submitted through `POST /trade/submit` with your key presented, newest first. Only settled fills appear: a trade is listed once it reaches `completed`, which on Ethereum and Robinhood Chain can be minutes after submission. Until then the amounts on record are quote-time expectations, so they are withheld rather than reported as fact. Each row carries `trade_id`, `status`, `side`, `ticker`, `protocol`, `chain`, the addresses involved, `timestamp`, `tx_hash`, `token_out_address`, `amount`, `amount_usd`, `shares`, the `sending` and `receiving` legs and the `fee_costs` breakdown, which includes an `integrator_fee` entry on a trade that carried your fee. Filter with `chain`, `protocol`, `ticker`, `side`, `token_out_address`, `settled_from`, `settled_to`, and, to reconcile [payouts](/enterprises/integrator-fees-and-payouts#what-you-have-earned), `payout_id` and `payout_status`; page with `limit` and `cursor`, reading `next_cursor` and `has_more` from each response. `data` may be shorter than `limit` while `has_more` is still `true`. A sell quoted with [`payout_chain`](/overview/routing-and-priority-mode#paying-out-a-sell-on-another-chain-payout_chain) is the one row whose legs differ: `sending` is the sale on the row's `chain`, and `receiving` is the payout, its own transaction on the chain the USDC landed on. The row's `chain` and `tx_hash` stay the sale's. The `chain` filter therefore matches the stock's chain, not the payout's; to select sells by where their USDC landed, filter `token_out_address` on that chain's USDC. If you reconcile exactly, re-scan roughly the last two hours on each pass rather than relying on the cursor alone. A small number of Solana trades are settled by a recovery job that records the on-chain block time, which is earlier than when the row appeared, so such a row lands behind a cursor you have already paged past. `trade_id` is stable, so re-scanned rows deduplicate cleanly. Trades that predate this endpoint are absent. #### The `/signals` and `/signals-orders` routes The target-weight books of the copy-trading strategies Treasures publishes to integrators (the catalog, one strategy with its current book, and its history), and four routes that turn a book into orders for one of your users' wallets (Solana, or BNB Smart Chain on the two plan routes): the sells that exit it, or the sells and buys that rebalance to it, each as a plan or with its signable quote. The orders routes also take an ownership proof for the wallet. [Strategy Signals](/enterprises/strategy-signals) covers the whole flow. #### `POST /trade/submit/batch` Up to 25 `POST /trade/submit` bodies in one request, each run exactly as the single route would and answered in request order with the `http_status` and body it would have given. Same-chain Solana legs only, and no `quote_id` twice. The batch's own `200` says nothing about any item: read each `http_status`. See [`POST /trade/submit/batch`](/api/submit-trade-batch). ### Rate limits with a key Presenting a valid key adds a per-organisation bucket shared by all of your keys. It is a cross-IP aggregate bound, additive to the per-IP limits rather than a raised ceiling. On `GET /portfolio` the organisation bucket replaces the per-IP row entirely and is sized for one request every 5 seconds per active end user. See [Enterprise Integration](/enterprises/enterprise-integration#rate-limits) for the full picture. Three key-only surfaces have buckets of their own. - The `/signals` reads allow 1,200 calls a minute per organisation and 600 a minute per key, with no per-IP bucket. - The inline order routes, `POST /signals-orders/exit` and `POST /signals-orders/rebalance`, count upstream quote calls rather than requests: 30 a minute per organisation, then 90 a minute shared by every caller, so a `429` there can be someone else's traffic; the [limits section](/enterprises/strategy-signals#limits-on-the-inline-routes) of Strategy Signals explains the points. - On `POST /trade/submit/batch` every submission counts once against a per-organisation budget of 600 a minute and a per-IP budget of 300 a minute, on top of the per-request limits of the trade routes. ### Errors a key can produce | Response | Meaning | What to do | | --- | --- | --- | | `401 invalid_api_key` | Missing, malformed or unknown key on a route that requires one, or a malformed key on any route | Check the header value. The message is deliberately generic | | `403 key_revoked` | The key was retired | Use a current key; contact Treasures if you have none | | `403 integrator_suspended` | Your organisation is suspended, so every one of your keys is affected | Contact Treasures | | `403 insufficient_scope` | A read-only `trk_` reporting key on a non-reporting route | Use your `tik_` key for API access | A key is verified on every route it is sent to, including the optional ones. Sending a bad key to `GET /stocks/prices` fails the request; it is not silently treated as anonymous. --- ## Integrator Fees and Payouts With an [integrator key](/enterprises/integrator-api-keys) you can charge your own fee on the trades your users make through you, then claim what you have earned. The fee is taken inside the trade, every settled trade records it, and you pay yourself out in USDC, on demand, to an address Treasures registers for you. ### How it works 1. **Treasures configures your fee.** Your key carries a default fee and a ceiling, both agreed with your Treasures contact. 2. **You quote with your key.** Every quote you request with `X-API-Key` charges your default fee. Send `integrator_fee_bps` to use a different fee on one quote. 3. **The trade pays it.** The fee is stacked into the same on-chain fee as Treasures' own, so the quoted output already allows for it. Nothing extra is signed. 4. **You submit with the same key.** A quote that carries your fee can only be submitted with the key that requested it. 5. **Settled trades record it.** Each trade's fee appears in [`GET /settlements`](/api/list-settlements) as an `integrator_fee` entry. 6. **You claim it.** [`POST /payouts`](/api/request-payout) sends everything you are owed to your registered address. ### Setting your fee `integrator_fee_bps` is accepted on [`POST /quote/buy`](/api/quote-buy), [`POST /quote/sell`](/api/quote-sell) and [`POST /quote/preview`](/api/quote-preview). It is your fee on that quote in net basis points (`0` to `10000`), up to your ceiling. - **Omit it** to charge your configured default. **Send `0`** to charge nothing on that quote. - **It needs your key.** A non-zero value without `X-API-Key` is refused. - **It is net.** On Solana the execution venue keeps half of the fee it collects, so the trader is charged twice your figure there and you net the figure you sent. - **The quote shows it.** Every leg reports `cost_breakdown_bps.integrator_fee_bps` beside `treasures_fee_bps`, and `estimated_output_*` is already net of both. It reads `0` on an anonymous quote, and on a leg whose venue could not collect a fee. - **Submit with the same key.** A quote with a non-zero fee on any leg must be submitted to [`POST /trade/submit`](/api/submit-trade) with the key that quoted it. Anything else is refused and nothing is broadcast. Zero-fee quotes have no such rule. | Response | When | What to do | | --- | --- | --- | | `400 invalid_integrator_fee` | The fee is above your ceiling (`max_bps` says what it is), or a venue on the route cannot carry it; `reason` is then `fee_above_maximum`, `fee_below_minimum` or `fee_unavailable` | Lower the fee, send `0`, or omit the field. Treat `reason` as an open set | | `400 integrator_fee_requires_api_key` | A non-zero `integrator_fee_bps` without `X-API-Key` | Send your `tik_` key, or drop the field | | `403 quote_integrator_mismatch` | A fee-carrying quote submitted without the key that quoted it, or with a different key | Resubmit with the key that quoted it | | `503 integrator_fee_misconfigured` | Your configured fee no longer fits a venue Treasures routes through. A Treasures-side issue that retrying soon will not clear | Contact Treasures, or send `integrator_fee_bps: 0` to quote without your fee | ### What you have earned Every settled trade that carried your fee has an `integrator_fee` entry in its `fee_costs` on [`GET /settlements`](/api/list-settlements): ```json { "name": "integrator_fee", "percentage": "0.0020", "amount_usd": "0.500840", "included": true, "payout_id": null } ``` `payout_id` is `null` while the fee is still owed to you, and names the payout it went out in once one claims it. Two filters on the same route reconcile the two sides: - `payout_status=unpaid` lists exactly the fees no payout has claimed yet. They sum to `amount_usd` on [`GET /payouts/accrued`](/api/get-accrued-integrator-fees). - `payout_id=ipo_…` lists exactly the trades one payout covered. Their `integrator_fee` amounts sum to that payout's `amount_usd`. `payout_status=processing` and `payout_status=paid` follow the status of the payout that claimed each fee. A read-only `trk_` reporting key can use these filters, which makes `/settlements` the place to hand an accountant; the payout routes themselves need your general `tik_` key. ### Claiming a payout #### Check what is owed [`GET /payouts/accrued`](/api/get-accrued-integrator-fees) returns what you are owed right now and whether you can claim it: | Field | Meaning | | --- | --- | | `amount_usd`, `trade_count` | What you are owed now and how many trades it came from. Fees earned on every chain are pooled into one USD figure (USDC and USDG count 1:1) | | `payout_chain`, `payout_address` | Where payouts go: USDC on Solana (`sol`) or Base (`base`). `null` until Treasures registers an address for you | | `previous_payout_address`, `payout_address_updated_at` | The address the last change replaced and when, so an unexpected change is visible to you | | `payouts_enabled` | Whether `POST /payouts` is open | | `minimum_usd`, `maximum_usd` | The smallest and largest payout the route makes. Above the maximum, Treasures pays on request | | `next_eligible_at` | Unix seconds before which a claim is refused (a cooldown after your last payout, or a hold after an address change); `null` when nothing is waiting | Only Treasures can set or change your payout address; ask your contact. There is no API to change it, by design. #### Claim it [`POST /payouts`](/api/request-payout) sends **all** of what you are owed to your registered address. You choose nothing: the body is empty (or `{}`), the amount is your accrued balance, and the destination is your registered address. - **`Idempotency-Key` is required**, and a key is yours forever. Repeating one returns the payout it first created (`200`), whatever its status, including `failed`. To try again after a failure, send a new key. - **One payout at a time**, at least `minimum_usd`, at most `maximum_usd`, one per cooldown window, and none for a while after your address changes. - **`202`** means the transfer was sent or is being sent. Poll [`GET /payouts/{payoutId}`](/api/get-payout) until it is final. | Payout `status` | Meaning | | --- | --- | | `processing` | Created or sent, not yet final. On Solana `tx_hash` is known as soon as the transfer is sent; on Base, once it lands | | `paid` | Final. `tx_hash` is the transfer and `paid_at` is set | | `failed` | The transfer did not happen. Its fees are owed to you again; claim with a new `Idempotency-Key` | | `cancelled` | Withdrawn before sending. Its fees went back into what you are owed | [`GET /payouts`](/api/list-payouts) lists every payout, newest first; page with `cursor`, reading `next_cursor` and `has_more`. To see the trades one payout covered, call `GET /settlements?payout_id=…`. #### When a claim is refused | Response | Meaning | What to do | | --- | --- | --- | | `409 payout_in_progress` | Another payout is still in flight; `payout_id` names it | Wait for it to finish | | `409 payout_cooldown`, `409 address_hold` | Too soon after your last payout, or after an address change | Retry after `retry_after` (Unix seconds; also a `Retry-After` header) | | `409 payout_address_missing` | No payout address is registered | Ask Treasures to register one | | `409 nothing_to_pay` | Nothing is owed right now | Nothing to do | | `422 below_minimum` | What you are owed is under `minimum_usd` | Wait until it grows | | `422 requires_review` | What you are owed is over `maximum_usd` | Ask Treasures, who pays balances this large on request | | `503 payouts_unavailable` | Payouts are paused or cannot be made right now | Retry later | | `403 insufficient_scope` | A `trk_` reporting key on a payout route | Use your `tik_` key | | `404 payout_not_found` | No such payout of yours. Another organisation's payout id answers the same way | Check the id | Every field is in the [API Reference](/api/get-accrued-integrator-fees). --- ## Strategy Signals With a general [integrator key](/enterprises/integrator-api-keys) you can read the target-weight books of the copy-trading strategies Treasures publishes to integrators, and ask Treasures for the orders that bring one of your users' wallets, on Solana or BNB Smart Chain, to a book, or out of it. Treasures never signs for you: every order is a normal quote, signed by the wallet's owner and submitted through [`POST /trade/submit`](/api/submit-trade) like any other trade. ### How it works 1. **Read the catalog.** [`GET /signals/strategies`](/api/list-signal-strategies) lists the strategies you may read, each with the identity of its latest book. One call tells you which books changed since you last looked. 2. **Read a book.** [`GET /signals/strategies/{id}`](/api/get-signal-strategy) returns the strategy and its current book: every ticker it holds and the fraction of the portfolio each should be. [`GET /signals/strategies/{id}/history`](/api/list-signal-strategy-history) pages through the past books. 3. **Plan the orders.** [`POST /signals-orders/rebalance/plan`](/api/plan-signal-orders-rebalance) returns the sells and buys that move a wallet's positions to the book; [`POST /signals-orders/exit/plan`](/api/plan-signal-orders-exit) returns the sells that leave it. Both read the wallet and return orders only: nothing is quoted and nothing expires. 4. **Quote, sign and submit.** Quote each order through [`POST /quote/sell`](/api/quote-sell) or [`POST /quote/buy`](/api/quote-buy) when the signer is ready, then submit the signed quotes, one at a time through `POST /trade/submit` or together through [`POST /trade/submit/batch`](/api/submit-trade-batch). 5. **Wait for every order to finish.** Poll [`GET /quote/{quote_id}/status`](/api/get-quote-status) until each is final before you plan again. The two inline routes, [`POST /signals-orders/rebalance`](/api/quote-signal-orders-rebalance) and [`POST /signals-orders/exit`](/api/quote-signal-orders-exit), fold steps 3 and the quoting half of step 4 into one call: the same orders, each already carrying its signable quote. They are for programmatic signers only; see [Plan first, or quote inline](#plan-first-or-quote-inline). Every route on this page requires your general `tik_` key. A read-only `trk_` reporting key is refused with `403 insufficient_scope`, because the books are the product and that key is made to be forwarded. ### What a book is A **book** is a strategy's complete target portfolio: one weight per ticker, as decimal strings that sum to at most one. It is a snapshot, never a change. `deployed_weight` is the sum of the weights and `cash_weight` the remainder, which the strategy holds as USDC. A book is the **replicated** book, not the source filing. The source portfolio (a quarterly 13F, a legislator's transaction reports, a manager's published weights) is cut down to the names Treasures can trade on chain and renormalised to them. Each strategy carries a `replication` block so you can see how partial the result is: `names_total` positions in the source, `names_replicated` carried into the book, `skipped_source_weight` the share of the source's weight left out, and `universe` the chains the book was cut against with how many names each could buy. Three fields identify a book: | Field | Meaning | | --- | --- | | `signal_id` | One publication of a book. A source that restates an unchanged portfolio daily produces a new `signal_id` each day | | `book_hash` | A SHA-256 over the book's contents. Two books with the same weights have the same hash whatever their `signal_id`, so compare hashes to know whether the weights moved | | `as_of` | Unix seconds. When Treasures ingested the book, **not** the date of the underlying filing or disclosure | `source_kind` says what the book is derived from. Treat an unknown value as opaque; new ones may be added. | `source_kind` | Derived from | | --- | --- | | `institutional_13f` | An institution's quarterly 13F holdings | | `congressional_disclosure` | A legislator's periodic transaction reports | | `media_inverse` | The inverse of a broadcast pundit's calls | | `social_account` | A public social-media account's posts | | `manager_published` | A fund manager publishes the book to Treasures directly, through the [Manager API](/managers/managing-a-strategy) | A strategy's `status` is `active` (new books are expected), `paused` or `halted` (no new books for now; the last one stays readable). The catalog lists `active` and `paused` strategies only. A `halted` strategy leaves the catalog but stays readable by id or slug on the detail and history routes, and the exit routes still serve it; the rebalance routes refuse it. `strategy_id` is the stable key. `slug` is a convenience that may be renamed; every route that takes an id accepts either, and every response carries the canonical id. ### Reading books #### The catalog [`GET /signals/strategies`](/api/list-signal-strategies) returns one page, newest first, of the strategies published to you. Only strategies published to integrators appear, so a strategy you can see in the Treasures app may be absent here. `truncated` says whether the page cap of 100 cut it short. ```bash curl https://api.treasures.io/public/v1/signals/strategies \ -H "X-API-Key: tik_..." ``` ```json { "data": [ { "strategy_id": "cst_01J7W3M9P2K5R8XV6T4H0B1C7D", "slug": "example-13f", "name": "Example 13F", "tagline": "A large institution's quarterly holdings, replicated on chain", "description": "Follows the institution's 13F filing, cut to the names tradable on Solana.", "portrait_url": "https://treasures.io/strategies/example-13f.png", "status": "active", "source_kind": "institutional_13f", "listed_at": 1759795200, "replication": { "as_of": 1760947200, "names_total": 41, "names_replicated": 18, "skipped_source_weight": "0.31280000", "universe": { "chains": ["sol"], "buyable_by_chain": { "sol": 18 } } }, "book_hash": "3f2a9c1e5b7d4a6f8e0c2b4d6f8a1c3e5b7d9f1a3c5e7b9d1f3a5c7e9b1d3f5a", "book_as_of": 1760947200, "signal_id": "csg_01J8ZK6Q2M7R4XW9V3T5H2B6NE" } ], "truncated": false } ``` Each row carries its latest book's `book_hash`, `book_as_of` and `signal_id` (all `null` while the strategy has no book yet), the same values the detail route serves. Keep the hash you last acted on per strategy and re-read a book only when it differs. #### One strategy and its book [`GET /signals/strategies/{id}`](/api/get-signal-strategy) returns the strategy and `book`: the newest book the source produced that Treasures has finished acting on, or `null` when there is none yet. An older book is never substituted for a newer one that cannot be read. ```bash curl https://api.treasures.io/public/v1/signals/strategies/example-13f \ -H "X-API-Key: tik_..." ``` ```json { "strategy": { "strategy_id": "cst_01J7W3M9P2K5R8XV6T4H0B1C7D", "slug": "example-13f", "name": "Example 13F", "tagline": "A large institution's quarterly holdings, replicated on chain", "description": "Follows the institution's 13F filing, cut to the names tradable on Solana.", "portrait_url": "https://treasures.io/strategies/example-13f.png", "status": "active", "source_kind": "institutional_13f", "listed_at": 1759795200, "replication": { "as_of": 1760947200, "names_total": 41, "names_replicated": 18, "skipped_source_weight": "0.31280000", "universe": { "chains": ["sol"], "buyable_by_chain": { "sol": 18 } } } }, "book": { "signal_id": "csg_01J8ZK6Q2M7R4XW9V3T5H2B6NE", "as_of": 1760947200, "book_hash": "3f2a9c1e5b7d4a6f8e0c2b4d6f8a1c3e5b7d9f1a3c5e7b9d1f3a5c7e9b1d3f5a", "position_count": 3, "deployed_weight": "0.85", "cash_weight": "0.15", "weights": [ { "ticker": "AAPL", "weight": "0.45" }, { "ticker": "MSFT", "weight": "0.25" }, { "ticker": "NVDA", "weight": "0.15" } ] } } ``` The example is shortened; a real book carries every replicated name. #### History [`GET /signals/strategies/{id}/history`](/api/list-signal-strategy-history) returns every book the source produced that Treasures finished acting on, as full weight vectors, newest first. Each entry is a book plus `trading_day`, the US trading day (`YYYY-MM-DD`) it was acted on. Treasures' own weekly restatements of an unchanged book are not rows here; a source that re-publishes an unchanged portfolio daily is, so consecutive rows often share a `book_hash`. Page with `limit` (1 to 100, default 20) and `cursor`: pass each response's `next_cursor` back as `cursor` while `has_more` is `true`. `data` may be shorter than `limit` while `has_more` is still `true`. #### Caching, limits and refusals - The catalog's `book_hash` per row is the change signal: keep the last hash you acted on per strategy and re-read a book only when it differs. - The three read routes share two buckets: 1,200 calls a minute per organisation (all of your keys together) and 600 a minute per key. There is no per-IP bucket. A `429` carries `Retry-After` in seconds. - An unknown id, a strategy that is not published to integrators and a typo all answer the same `404 strategy_not_found`, so a response never reveals whether an id exists. ### Acting on a book from a wallet Four routes turn a book into orders for one of your users' wallets. Each takes the same core body: the strategy (`strategy_id`, as id or slug), the wallet (`sol_wallet`) and an [ownership proof](/overview/ownership-proof) with `sol_signature`. The two plan routes also take a BNB Smart Chain wallet with `chain: "bnb"`; what differs there is in [On BNB Smart Chain](#on-bnb-smart-chain), and the rest of this section describes Solana. The orders come back ranked and sized; you quote, sign and submit them. | Route | Returns | Quotes anything? | | --- | --- | --- | | [`POST /signals-orders/exit/plan`](/api/plan-signal-orders-exit) | One full-share sell per name the wallet holds in the book | No | | [`POST /signals-orders/exit`](/api/quote-signal-orders-exit) | The same sells, each with its signable `/quote/sell` answer | Yes | | [`POST /signals-orders/rebalance/plan`](/api/plan-signal-orders-rebalance) | The sells and buys that bring the wallet's positions in the book's names to the book, plus a `funding` block | No | | [`POST /signals-orders/rebalance`](/api/quote-signal-orders-rebalance) | The same orders, each with its signable `/quote/sell` or `/quote/buy` answer | Yes | Every response carries the book it planned against (`book_hash`, `signal_id`, `as_of`), `nav_usdc` (the value of what the wallet holds in scope), `usdc_available` (the wallet's whole Solana USDC balance), `orders[]` and `skipped[]`. An order is `{ticker, side, shares, notional_usdc}`: a sell carries `shares` (floored to 18 decimal places, never rounded up) and its USD value; a buy carries `shares: null` and the USDC it spends in `notional_usdc` (floored to 6 decimal places). At most 25 orders come back per call, largest notional first, sells before buys on a rebalance. #### Plan first, or quote inline **The plan routes are the default.** They read the wallet and return orders only. Nothing is quoted and nothing expires, so a human can review the orders and a hardware wallet can sign each one when ready. Quote each order yourself when the signer is ready, with the same wallet and a fresh proof: - A sell is [`POST /quote/sell`](/api/quote-sell) with `{ "ticker", "amount_shares": , "chain": "sol", "sol_wallet", "ownership_proof", "max_slippage_bps" }`. - A buy is [`POST /quote/buy`](/api/quote-buy) with `{ "ticker", "amount_usdc": , "chain": "sol", "sol_wallet", "ownership_proof", "max_slippage_bps" }`. **The inline routes are for programmatic signers only.** They return the same orders, each with `quote`: exactly the `/quote/sell` or `/quote/buy` answer for that order, signable payloads included, to sign and submit through `POST /trade/submit` unchanged. A Solana leg is signable for about 45 seconds after the response; each quote's own `expires_at` binds, the top-level `expires_at` is the earliest of them and `signing_window_sec` the seconds left until it. `max_slippage_bps` is required on the inline routes (nothing is quoted without it) and optional on the plan routes. Three rules apply to every call: - **Solana unless you say otherwise.** Without `chain: "bnb"`, a body carrying `eth_wallet` is refused with `400 invalid_request`. The inline routes are Solana only. - **One wallet per strategy.** Holdings are not tracked per strategy: every name of the book the wallet holds counts, whichever strategy (or none) it was bought for. Two strategies sharing a name in one wallet would sell or resize each other's position, so give each strategy its own wallet. - **Pin the book you planned against.** Send `expected_book_hash` and the call is refused with `409 book_changed` (carrying the hash served now) if the book moved, before the wallet is read or anything is quoted. Re-read the book and decide again. On the inline routes, **one call at a time per wallet and strategy**: while a quote from an earlier call for the same wallet and strategy is neither final nor five minutes past its `expires_at`, a new call is refused with `409 orders_in_flight` naming those `quote_ids` (an empty list while the earlier call is still quoting) and `Retry-After` in seconds. A submitted quote counts as final once its status has been read as final, so poll every quote you submit. The plan routes are never refused this way; wait for every order yourself before planning again. #### Exiting a book [`POST /signals-orders/exit/plan`](/api/plan-signal-orders-exit) returns one full-share sell per name the wallet holds in the strategy's current book. Add `tickers` (up to 25) for positions you hold that have since left the book; each is sold only if held. `protocol` narrows which Solana venues are read and sold, as on `/quote/sell`, and must include a Solana protocol; a pinned exit covers the pinned venues only, so repeat the call per venue to exit fully. ```bash curl -X POST https://api.treasures.io/public/v1/signals-orders/exit/plan \ -H "X-API-Key: tik_..." \ -H "Content-Type: application/json" \ -d '{ "strategy_id": "example-13f", "sol_wallet": "7xKXtg2C…", "ownership_proof": { "issued_at": 1760947200, "sol_signature": "" }, "expected_book_hash": "3f2a9c1e5b7d4a6f8e0c2b4d6f8a1c3e5b7d9f1a3c5e7b9d1f3a5c7e9b1d3f5a" }' ``` ```json { "strategy_id": "cst_01J7W3M9P2K5R8XV6T4H0B1C7D", "book_hash": "3f2a9c1e5b7d4a6f8e0c2b4d6f8a1c3e5b7d9f1a3c5e7b9d1f3a5c7e9b1d3f5a", "signal_id": "csg_01J8ZK6Q2M7R4XW9V3T5H2B6NE", "as_of": 1760947200, "nav_usdc": "1250.40", "usdc_available": "310.25", "orders": [ { "ticker": "AAPL", "side": "sell", "shares": "2.5", "notional_usdc": "612.50" }, { "ticker": "MSFT", "side": "sell", "shares": "1.25", "notional_usdc": "520.00" }, { "ticker": "NVDA", "side": "sell", "shares": "0.9", "notional_usdc": "117.90" } ], "skipped": [] } ``` `nav_usdc` counts the priced names held in scope only; an unpriced holding is still an order, with `notional_usdc: null`, ranked after the priced ones. A holding worth under $0.01 reads as not held. A holding that could not be read is skipped as `holdings_unknown`, never assumed absent. The plan applies no minimum size, but a sell too small to route can still be refused at quote time as `no_routes`. #### Rebalancing to a book [`POST /signals-orders/rebalance/plan`](/api/plan-signal-orders-rebalance) returns the sells and buys that move the wallet's positions in the book's names to the book. It takes the exit body minus `protocol` (every Solana venue counts), plus an optional `amount_usdc`. **Scoped nav.** Every order is sized against `nav_usdc`: the value of what the wallet holds in the book's names (plus any `tickers` you add), plus `amount_usdc`. Each name's target is its book weight times that nav. The book's `cash_weight` stays as USDC and is never ordered; a `tickers` name outside the book has weight zero and is sold in full. Holdings outside the scope and the rest of the wallet's USDC are never touched. **Funding.** Buys spend only `amount_usdc`, never the rest of the wallet's USDC, and are never larger than it. When the buys need more than that, each is scaled down pro rata and rounded down, and a scaled buy under $1 is skipped. A buy that cannot be funded is skipped as `awaiting_sell_proceeds` when the plan also sells, or `insufficient_balance` when it does not. The `funding` block says what happened: | Field | Meaning | | --- | --- | | `usdc_spendable` | `amount_usdc`, or `"0"` when omitted: the only USDC this plan's buys spend | | `buys_required_usdc` | Every buy the book asks for, ordered or not, excluding gaps under $1 and names that cannot be bought | | `buys_scaled` | `true` when the buys were scaled down to fit `usdc_spendable` | | `buys_deferred_usdc` | `buys_required_usdc` less the buys in `orders`. Not the next round's `amount_usdc` | | `buys_deferred_until_sells_settle` | `true` when buys are deferred and this plan sells: submit the sells, wait, call again | | `next_amount_usdc` | The next call's `amount_usdc`: `usdc_spendable` plus the sells ordered, less the buys ordered. Send the smaller of it and `usdc_available` | A rebalance that only reshuffles what the wallet holds is therefore **two rounds**: 1. Call with `amount_usdc` omitted. Submit the sells. 2. Once every sell is final, call again with `amount_usdc` set to the smaller of `funding.next_amount_usdc` and `usdc_available` (proceeds land net of fees and slippage). Omit `amount_usdc` when that is zero: `"0"` is refused with `400`. Submit the buys. Use `next_amount_usdc`, not `buys_deferred_usdc`: it is the strategy's cash after the round, so it keeps the book's `cash_weight` and the weight of any name that cannot be bought inside nav. **Without `amount_usdc`, the book's cash weight is sold on every call**: nav is then only what the wallet holds, and the targets sum to the book's deployed share of it, so a book that is 15% cash sells about 15% of the held value each time it is planned without `amount_usdc`. Carry `next_amount_usdc` forward to keep that cash in nav. **Buying in from cash.** Call with `amount_usdc` on a wallet that holds none of the book's names: every order is a buy, sized by its book weight of `amount_usdc`. A book with many names may take more than one round under the 25-order cap; submit the buys, wait for them to settle, and call again with `next_amount_usdc`. ```bash curl -X POST https://api.treasures.io/public/v1/signals-orders/rebalance/plan \ -H "X-API-Key: tik_..." \ -H "Content-Type: application/json" \ -d '{ "strategy_id": "example-13f", "sol_wallet": "7xKXtg2C…", "ownership_proof": { "issued_at": 1760947200, "sol_signature": "" }, "expected_book_hash": "3f2a9c1e5b7d4a6f8e0c2b4d6f8a1c3e5b7d9f1a3c5e7b9d1f3a5c7e9b1d3f5a" }' ``` ```json { "strategy_id": "cst_01J7W3M9P2K5R8XV6T4H0B1C7D", "book_hash": "3f2a9c1e5b7d4a6f8e0c2b4d6f8a1c3e5b7d9f1a3c5e7b9d1f3a5c7e9b1d3f5a", "signal_id": "csg_01J8ZK6Q2M7R4XW9V3T5H2B6NE", "as_of": 1760947200, "nav_usdc": "1250.40", "usdc_available": "310.25", "funding": { "usdc_spendable": "0", "buys_required_usdc": "187.56", "buys_scaled": true, "buys_deferred_usdc": "187.56", "buys_deferred_until_sells_settle": true, "next_amount_usdc": "187.50" }, "orders": [ { "ticker": "AAPL", "side": "sell", "shares": "0.765306", "notional_usdc": "187.50" } ], "skipped": [ { "ticker": "MSFT", "side": "buy", "reason": "awaiting_sell_proceeds", "detail": null }, { "ticker": "NVDA", "side": "buy", "reason": "awaiting_sell_proceeds", "detail": null } ] } ``` This is round one of a reshuffle: the wallet is overweight AAPL, so it sells down to the target, and the two buys wait for the proceeds. Round two sends `amount_usdc: "187.50"` and orders the buys. Unlike an exit, which skips a name it cannot read, a rebalance refuses the whole request when any name in scope cannot be read (`422 holdings_unknown`) or a held one cannot be priced (`422 price_unavailable`), because one mis-sized name would mis-size every other order. The refusal lists the `tickers` to retry or remove. A book name Treasures cannot buy on Solana is skipped as `not_tradable` and its weight stays in USDC; a gap under $1 is skipped as `below_min_notional`. A `halted` strategy answers `422 strategy_halted` on both rebalance routes before anything is read, while the exit routes still serve it. **Wait for every order to finish before calling again.** The plan reads holdings as they stand, and the plan route never refuses an early or repeated call, so it would return the same sells again and both sets could execute. Each order from the previous round must have reached a final status on [`GET /quote/{quote_id}/status`](/api/get-quote-status) first. The inline route refuses such a call with `409 orders_in_flight`. #### Quoting and submitting the orders Each order becomes one quote: a sell through `/quote/sell` with `shares` sent as `amount_shares`, a buy through `/quote/buy` with `notional_usdc` sent as `amount_usdc`, both with `chain: "sol"`, the same wallet and a fresh proof. On a rebalance send no `protocol`. The inline routes return these quotes for you. Submit each signed quote through [`POST /trade/submit`](/api/submit-trade), or up to 25 at once through [`POST /trade/submit/batch`](/api/submit-trade-batch): one `/trade/submit` body per submission, same-chain Solana legs only, no `quote_id` twice. The batch answers every submission in request order with the `http_status` and body the single route would have given, so the batch's own `200` says nothing about any item. A submission the batch could not start in time answers `503 batch_deadline_exceeded`: submit it again while its quote is live. On the inline routes a partial result is normal. An order whose quote is refused moves to `skipped` with the error code its quote route would have answered (for example `no_routes` or `holdings_insufficient`), `detail` carrying the rest of that error body, and the response is still `200`. An order whose quote expired before the response was sent is skipped as `quote_stale`. A buy skipped at quote time is counted in `buys_deferred_usdc` and spends nothing from `next_amount_usdc`; a sell skipped at quote time adds nothing to it. When no sell is quoted, a buy held as `awaiting_sell_proceeds` is relabelled `insufficient_balance`, since no proceeds are coming. #### On BNB Smart Chain The two plan routes take `chain: "bnb"` and plan the orders for a wallet on BNB Smart Chain. The inline routes do not: `POST /signals-orders/exit` and `POST /signals-orders/rebalance` refuse `chain: "bnb"` with `400 invalid_request`, because a quote there must be signed within about 14 seconds, too short to quote a whole plan at once. Plan once, then quote, sign and submit each order on its own. [Copying a Strategy on BNB Smart Chain](/enterprises/copying-a-strategy-on-bnb) walks through it with sample code. ```bash curl -X POST https://api.treasures.io/public/v1/signals-orders/rebalance/plan \ -H "X-API-Key: tik_..." \ -H "Content-Type: application/json" \ -d '{ "strategy_id": "example-13f", "chain": "bnb", "eth_wallet": "0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed", "ownership_proof": { "issued_at": 1760947200, "eth_signature": "0x" }, "amount_usdc": "100" }' ``` **The body.** Send `chain: "bnb"`, `eth_wallet` in place of `sol_wallet`, and a proof carrying `eth_signature`. A `sol_wallet` in a bnb body is refused. On an exit, a `protocol` pin must include `ondo` or `xstocks`. **What the plan reads.** The wallet's `ondo` and `xstocks` tokens on BNB Smart Chain, read live, and its Binance-Peg USDC, served as `usdc_available` floored to 6 decimal places. `amount_usdc` is in that USDC. - **bStocks is never read or planned.** A book name the wallet holds as bStocks reads as `not_held`: a rebalance buys its full target again, an exit leaves it in the wallet, and its value is not in `nav_usdc`. Sell it yourself first if you do not want both. - **A book name with no `ondo` or `xstocks` listing on BNB Smart Chain** is skipped as `not_tradable` and its weight stays in USDC. **Quoting each order.** Use the same quote routes as on Solana, pinned to the venues the plan read: - A sell is [`POST /quote/sell`](/api/quote-sell) with `{ "ticker", "amount_shares": , "chain": "bnb", "protocol": ["ondo", "xstocks"], "eth_wallet", "ownership_proof", "max_slippage_bps" }`. - A buy is [`POST /quote/buy`](/api/quote-buy) with `{ "ticker", "amount_usdc": , "chain": "bnb", "protocol": ["ondo", "xstocks"], "eth_wallet", "ownership_proof", "max_slippage_bps" }`. - **Always send `protocol`:** `["ondo", "xstocks"]`, or the pin you sent on the exit plan. An unpinned `bnb` quote can route to bStocks, a listing the plan never read. - **Submit each quote on its own** [`POST /trade/submit`](/api/submit-trade). The batch route takes same-chain Solana legs only. - **Slippage.** Outside the US session, xStocks quotes on BNB Smart Chain often need a `max_slippage_bps` near 300; Ondo quotes measured under 100. **Venue minimums.** On bnb the plan applies each name's venue floor: $10 for a name buyable (or, on a sell, held) on xStocks alone, $1 otherwise. - A rebalance gap under the floor is skipped as `below_min_notional`. So is a held name worth less than its floor on an exit plan, which applies no minimum on Solana. - On an exit plan, a held name with no price is skipped as `price_unavailable`, since its floor cannot be checked. On Solana it is still an order. - **A plan can order no buys, with no error.** When `amount_usdc` is short, each buy is scaled down and a scaled buy under its floor is skipped; the USDC that frees is not spread over the others. $30 over five xStocks-only names scales each to $6 and buys nothing. The shortfall stays in `funding.buys_deferred_usdc`. **No quote-call cap.** The 25-order cap applies; the quote-call budget does not, so `leg_cap` on bnb means past 25 orders. **`approvals`.** A bnb plan carries `approvals[]`, absent on Solana: one row for USDC when the plan buys, then one per token a planned sell spends. | Field | Meaning | | --- | --- | | `token` | The token's address on BNB Smart Chain: Binance-Peg USDC on the USDC row, otherwise the held stock token | | `spender` | The settlement contract a gasless order pulls the token through, the same address as in [Approvals by chain](/overview/chains-and-venues#approvals-by-chain) | | `approval_required` | `true` when the wallet's allowance falls short (of `amount_usdc` for USDC, of the balance for a held token): approve before submitting, or the order cannot fill. `false` when it covers. `null` when it could not be read: unknown, never approved, so check the allowance yourself | It is advisory: no approval is built for you, and the plan is served either way. Approvals are ordinary transactions paid in BNB; the trades themselves are gasless. #### Skip reasons `skipped[]` entries are `{ticker, side, reason, detail}`. The plan-time reasons: | `reason` | Meaning | | --- | --- | | `leg_cap` | More orders than fit in one call: past 25 orders, or on Solana past the quote-call budget (below). On an exit the smallest by notional go first, unpriced first; on a rebalance sells are admitted before buys. Call again once these have executed | | `not_held` | No position in the name on the venue, or one worth under $0.01, or one that floors to zero shares. On bnb, a name held only as bStocks | | `holdings_unknown` | The holding could not be read, so it is never assumed absent. Exit only; a rebalance refuses the whole request instead | | `below_min_notional` | A rebalance gap under $1. On bnb, a gap or an exit sell under the name's [venue floor](#on-bnb-smart-chain) | | `awaiting_sell_proceeds` | A rebalance buy that `amount_usdc` cannot fund while the plan also sells. Call again with the proceeds once the sells settle | | `not_tradable` | A book name Treasures cannot buy on the venue: Solana, or `ondo` and `xstocks` on BNB Smart Chain. Its weight stays in USDC | | `insufficient_balance` | A rebalance buy that `amount_usdc` cannot fund, with no sell to wait on | | `price_unavailable` | Bnb exit plans only: a held name with no price, so its venue floor cannot be checked | On the inline routes `reason` can also be `quote_stale` or any error code `/quote/sell` or `/quote/buy` answers. #### Refusals | Response | Meaning | What to do | | --- | --- | --- | | `400 invalid_request` | `eth_wallet` without `chain: "bnb"`, `sol_wallet` with it, `chain: "bnb"` on an inline route, `protocol` on a rebalance or naming no protocol the venue reads on an exit, `amount_usdc: "0"`, a missing `max_slippage_bps` on an inline route, or a malformed body | Fix the body | | `400 invalid_slippage` | `max_slippage_bps` out of range | Send a value in range | | `401` | A missing, malformed or unknown key, or an [ownership proof](/overview/ownership-proof) failure | Check the key and sign a fresh proof | | `403 address_blocked` | Sanctions screening flagged the wallet | Nothing to retry | | `403 insufficient_scope` | A `trk_` reporting key | Use your `tik_` key | | `404 strategy_not_found` | Unknown, unpublished, or a typo | Read the catalog | | `409 book_changed` | `expected_book_hash` is not the book served now; the response carries the current `book_hash`. Nothing was read or quoted | Re-read the book and plan again | | `409 orders_in_flight` | Inline routes only: an earlier call's quotes for this wallet and strategy are neither final nor five minutes past expiry; `quote_ids` lists them | Poll those quotes, then retry after `Retry-After` seconds | | `422 book_unavailable` | The strategy has no book yet | Wait for its first book | | `422 holdings_unknown`, `422 price_unavailable` | Rebalance only: the listed `tickers` could not be read or priced, so no plan is offered. Usually transient, but a book name that is no longer tradable refuses every rebalance until the next book | Retry, or exit instead | | `422 insufficient_balance` | `amount_usdc` is more than the wallet's USDC on the venue | Send at most `usdc_available` | | `422 strategy_halted` | Rebalance only: the strategy is halted | Use the exit routes if you want out | | `429` | A bucket is spent; see below | Sleep `Retry-After` seconds | | `503 holdings_unavailable`, `503 balance_unavailable`, `503 screening_unavailable` | The wallet's holdings, its USDC balance or the screening check could not be read. A balance is never reported as zero when it could not be read. When the reads behind the plan did not answer within 15 seconds the call answers this way with `Retry-After: 15` | Retry after `Retry-After` | #### Limits on the inline routes The inline routes, which are Solana only, count **upstream quote calls**, not requests. A sell held on one Solana venue costs 1 point, on two venues 3, on three 6; a buy costs at most 1 point per Solana venue it can buy on. Points are charged only after the wallet is admitted and only when there is something to quote, from a per-organisation bucket of 30 a minute and then a bucket of 90 a minute shared by every caller. A Solana plan never costs more than 30 points: orders past that are skipped as `leg_cap`, so the plan route and its inline twin always answer the same split and a large exit or buy-in completes over a few calls. A plan costing more than the points left this minute is refused whole with `429` before any order is quoted. A `429` from the shared bucket can be another integrator's traffic and spends none of your own points; the `X-RateLimit-*` headers on these routes describe the shared bucket. ### For fund managers A strategy run through the [Manager API](/managers/managing-a-strategy) can be published to integrators as well, in which case its books are served here with `source_kind: manager_published`. Whether a strategy is published to integrators is decided by Treasures per strategy, not by the manager key. ### Where to go next - [Copying a Strategy on BNB Smart Chain](/enterprises/copying-a-strategy-on-bnb): a worked example with sample code. - [Integrator API Keys](/enterprises/integrator-api-keys): the per-route key table and what each key-gated route returns. - [Ownership Proof](/overview/ownership-proof): the signature the wallet makes on every orders call and every quote. - [Buying and Selling](/overview/buying-and-selling): how to sign and submit the quotes the orders become. - [API Reference](/api/signals): every field on the seven routes. --- ## Managing a Strategy This section is for fund managers who run a strategy that Treasures users can follow. You publish the target weights of your book; Treasures rebalances every follower's wallet towards them and pays you a share of the fees those followers pay. You never hold, see or touch a follower's funds. The Manager API is a separate API from the [B2B Public API](/api/treasures-finance-b-2-b-public-api), with its own base URL and its own credentials. It publishes your book, reads your strategies, their performance and your fee ledger, shows the accounts of an SMA strategy, and, from a signed-in dashboard session, mints and revokes your keys. The full field-by-field reference is in the [Manager API reference](/manager-api/treasures-finance-manager-api), and the spec is published as [OpenAPI JSON](https://docs.treasures.io/manager-openapi.json). - **Base URL:** `https://api.treasures.io/manager/v1` - **Auth:** your manager API key in `X-API-Key`, or a signed-in dashboard session, on every request (see [Your credentials](#your-credentials)) - **Bodies:** JSON, with `Content-Type: application/json` ### How it works 1. **Treasures onboards you.** Your Treasures contact creates your manager account, creates the strategy that followers will see, assigns it to you, registers the address your fees are paid to, and hands you your first manager API key or the link to your dashboard sign-in. None of these steps can be done through the API; after onboarding you mint and revoke your own keys. 2. **You publish a book.** [`POST /strategies/{strategyId}/signals`](/manager-api/publish-signal) with the tickers you want held and the fraction of the portfolio each should be. 3. **Treasures rebalances followers.** Every live follower's wallet is moved from what it holds towards what you published, during the market session the response names. You place no orders. 4. **Fees accrue and are collected.** Treasures charges followers management and performance fees under the strategy's terms. A share of every collection is yours, at the rate in your agreement with Treasures. 5. **You read what reached you.** Your share of a collection can be paid to your registered fee address on-chain, inside the transaction that collects the fee. [`GET /fees`](/manager-api/get-fees) shows what has been charged, what has been collected and how much of your share reached your address that way. ### Your credentials Two credentials are accepted, and every route needs one. **Manager API key.** Your key starts with `cmk_`, goes in `X-API-Key`, and is shown to you **once**, when it is issued. Store it in a secrets manager when you receive it. Your first key comes from Treasures; after that you mint and revoke keys yourself from a signed-in dashboard session ([`POST /keys`](/manager-api/create-key), [`DELETE /keys/{keyId}`](/manager-api/revoke-key)). Rotating is mint-new, switch, revoke-old. - You may hold 10 active keys (`409 key_limit` past that) and make 20 self-service mints in any 24 hours (`429 key_mint_limit`). - A mint whose response you lost still created a key. List your keys ([`GET /keys`](/manager-api/list-keys)) and revoke the one you never received. - A key can never manage keys: the three `/keys` routes answer a key `403 session_required`. **Dashboard session.** Your own login on the Treasures dashboard, as a Member of the Organization your manager account belongs to. It is accepted on every route, and the headers it sends are in the [reference](/manager-api/treasures-finance-manager-api). - **Recent sign-in.** Publishing a book and minting a key from a session need a sign-in made in the last 15 minutes, or are refused `403 reauth_required`: sign out and in again, then retry. Linking a new login method to a signed-in session does not count, and neither does signing in with one first linked in the last 15 minutes. If Treasures cannot confirm the sign-in, the request is refused `503 sign_in_check_unavailable` and nothing is written. Revoking a key needs no recent sign-in. - **Organizations.** A login that belongs to more than one Organization with a manager account names the one it acts for in `X-Organization-Id` (`400 organization_required` without it). - **Permissions.** A Member who is not an Admin can do only what its permissions grant, or is refused `403 permission_denied`. The permission each route needs is listed in the reference. Permissions never apply to a key. - When a request carries a key, only the key is checked, even if a valid session is sent with it. | Response | Meaning | What to do | | --- | --- | --- | | `401 unauthorized` | No credential was sent at all, or a dashboard session failed verification | Send your key, or sign in again | | `401 invalid_api_key` | Malformed or unknown key, or a key for a different Treasures API | Check the header value | | `401 key_revoked` | This key was revoked | Use a current key, or mint one from the dashboard | | `403 manager_suspended` | Your account is suspended, so every key you hold and your dashboard session are refused | Contact Treasures | | `403 manager_not_linked` | A valid dashboard login that is a Member of no Organization with a manager account | Ask your Treasures contact | | `403 organization_suspended` | Your Organization is suspended, so every Member session is refused; your keys keep working | Contact Treasures | | `403 permission_denied` | Your Member permissions do not grant this route | Ask an Admin of your Organization | **Rate limit:** 60 requests per minute per manager, shared by every key you hold, and a separate 120 per minute for your dashboard sessions; neither can use up the other. A `429` carries `Retry-After` in seconds; sleep exactly that long. Publishing is a few requests a day, so this is headroom for a retry loop, not a throughput target. ### Publishing a book A signal is the whole book, not a change to it. Send every ticker you want held with its target weight; a ticker you leave out is sold. ```bash curl -X POST https://api.treasures.io/manager/v1/strategies/cst_01J7W3M9P2K5R8XV6T4H0B1C7D/signals \ -H "X-API-Key: cmk_..." \ -H "Content-Type: application/json" \ -d '{ "dedupe_key": "2026-09-28-r1", "target_weights": [ { "ticker": "AAPL", "weight": "0.35" }, { "ticker": "NVDA", "weight": "0.25" }, { "ticker": "MSFT", "weight": "0.20" } ] }' ``` ```json { "signal_id": "csg_01J8ZK6Q2M7R4XW9V3T5H2B6NE", "outcome": "ingested", "urgency": "fresh", "trading_day": "2026-09-28", "ttl_at": "2026-09-28T19:30:00.000Z", "follower_count": 42, "superseded_signal_ids": [] } ``` #### The rules of a book - **Weights are decimal strings**, greater than zero, at most `1`, with up to 8 fractional digits. Never a JSON number. - **Weights sum to at most `1`.** Whatever is left is held as cash: the example above is a 20% cash position, on purpose. A book that sums past `1` is refused. - **Omit a position to sell it.** A weight of `0` is refused; leave the ticker out instead. - **Each ticker once.** 1 to 200 positions per book. - **Tickers are uppercase**, in the notation the Treasures catalog uses (`BRK.B`, not `BRK-B`). - The catalog is [`GET /stocks/tickers`](/api/list-stock-tickers) on the public API. A ticker that is not on it is refused `422 unknown_tickers`, naming the offenders, and nothing is published. - A ticker that is on the catalog but not listed on the venues Treasures buys on for followers is refused `422 unavailable_tickers` the same way. That is a listing check: a halted or thinly traded ticker is still accepted, and the `tradability` warning on the tickers endpoint plays no part. - Both checks apply to a new `dedupe_key` only. #### `dedupe_key`: your idempotency key `dedupe_key` is required, and you choose it: a date and revision, your own book id, any string up to 200 characters that is unique per book you intend to publish. Repeating one returns `200` with the original signal and rebalances nothing, which is what makes a retry after a timeout safe. The flip side: publishing the **same** book on a later day needs a **new** key, or nothing happens. Keys starting with `replan:` or `catchup:` (any case) are reserved for the platform and refused with `400 invalid_request`. #### When your book executes You cannot choose the execution window; Treasures decides it from the market calendar and tells you in the response. Sending `urgency` or `kind` in the body is a `400`, and so is any query parameter on the URL. | `urgency` | When | Window | | --- | --- | --- | | `fresh` | The US market is open with more than 30 minutes left | Starts now, ends at `ttl_at`: up to 4 hours, never past the close | | `stale` | The market is closed, or closes within 30 minutes | Starts 30 minutes after the next session's open; `ttl_at` is that session's close | `trading_day` is the date of the session the book targets. **A book not filled by `ttl_at` lapses and is not retried.** If you need it done, publish again with a new `dedupe_key`. Publishing a new book on a day that already has one queued replaces the queued one; `superseded_signal_ids` lists what this publish retired. #### What you see, and what you do not `follower_count` is how many live followers the book was fanned out to when it was accepted. Each follower is rebalanced within their own limits (minimum trade sizes, cash available, position caps); a follower who cannot take a position is skipped rather than blocking the book, and you are not told which. On a retail strategy, nothing on this API names a follower, a wallet or an individual order. An SMA strategy is the exception: you see each account by its wallet addresses, with its holdings and every order that filled for it (see [Reading your strategies](#reading-your-strategies)), but never the client behind it. Treasures can also publish a strategy to integrators, who then read its books through the [strategy signals](/enterprises/strategy-signals) routes of the B2B API, marked `source_kind: manager_published`. That is a per-strategy decision made by Treasures, not something your credentials control; ask your Treasures contact if you want your strategy published or kept private. #### Errors when publishing | Response | Meaning | What to do | | --- | --- | --- | | `400 invalid_request` | The body failed validation, or the URL carried a query parameter; `message` names the field | Fix the book; send nothing in the query string | | `400 invalid_strategy_id` | The path segment is empty or over 64 characters | Check the id | | `403 reauth_required` | Dashboard session only: your last sign-in was more than 15 minutes ago. Answered even when you repeat a `dedupe_key` | Sign out and in again, then retry | | `403 strategy_forbidden` | This strategy is not assigned to you. A strategy id that does not exist gets the same answer | Check the id with your Treasures contact | | `409 strategy_not_accepting_signals` | The strategy is not active (Treasures has paused or halted it); positions are held | Contact Treasures | | `415` | The body was not sent as `application/json` | Set the header | | `422 unknown_tickers` | Tickers not in the catalog, listed in `unknown_tickers` | Fix or remove them | | `422 unavailable_tickers` | Tickers on the catalog but not listed on the venues followers buy on, listed in `unavailable_tickers`. Returned only when there are no `unknown_tickers` | Resend the book without them; leaving a held ticker out sells it from followers | | `422 unsupported_signal_kind` | The strategy is not configured to take a weights book | Contact Treasures | | `429` | Over 60 requests this minute from your keys, or 120 from your dashboard sessions | Sleep `Retry-After` | | `503 sign_in_check_unavailable` | Dashboard session only: your sign-in could not be confirmed, so nothing was published | Retry shortly | The credential refusals in [Your credentials](#your-credentials) apply here too. ### Reading your strategies Every read takes your key or a dashboard session, and every `{strategyId}` on this API accepts the strategy's `cst_` id or its slug. | Route | What it returns | | --- | --- | | [`GET /strategies`](/manager-api/list-strategies) | Every strategy assigned to you, `draft` included, with its newest book, live follower count, `audience` (`retail` or `sma`) and the total value of its followers' portfolios | | [`GET /strategies/{strategyId}/signals`](/manager-api/list-strategy-signals) | Every book published into the strategy at every status, newest first, with why planning gave up and, once a book is final, its order counts by state | | [`GET /strategies/{strategyId}/performance`](/manager-api/get-strategy-performance) | The strategy's daily performance line: a backtest where one was published, then the live model | On a retail strategy, follower totals (the value of your followers' portfolios, a signal's order counts) are withheld until at least three followers contribute to them, so that no figure describes one follower. #### SMA accounts An SMA strategy (`audience: sma`) is followed by separately managed accounts only, and is never listed publicly. The three-follower minimum does not apply to it, and it has five more reads; a retail strategy answers them `404 strategy_not_sma`. Name an account by either of the addresses the accounts list serves. | Route | What it returns | | --- | --- | | [`GET /strategies/{strategyId}/accounts`](/manager-api/list-strategy-accounts) | Every account assigned to the strategy, named by its wallet addresses, with its state and latest daily valuation, plus totals across the accounts | | [`GET /strategies/{strategyId}/accounts/{address}/fills`](/manager-api/list-account-fills) | Every order that filled for one account, newest first, with its USDC amount and each leg's chain and transaction hash | | [`GET /strategies/{strategyId}/accounts/{address}/holdings`](/manager-api/get-account-holdings) | A live read of one account's positions, stablecoins and gas | | [`GET /strategies/{strategyId}/accounts/{address}/performance`](/manager-api/get-account-performance) | Every daily valuation of one account, oldest first | | [`GET /strategies/{strategyId}/orders`](/manager-api/list-strategy-orders) | Every fill across the strategy's accounts, newest first, optionally for one `signal_id` | - **Assignments.** An account that was closed and later assigned to the strategy again is listed once per assignment, numbered from 1. The fills read takes `assignment` to show one alone, and the performance read never chains value per unit across two. - **Holdings is a live read with its own budget:** 20 calls a minute per credential kind. A balance or price read that does not complete answers `503`, never a partial figure; retry shortly. From 00:03 to 00:40 UTC, around the daily valuation, it answers `503 portfolio_busy` with `Retry-After`. - **An address that is not an account of the strategy** answers `404 account_not_found`, whoever's address it is. - **Mixed strategies.** If anyone other than a separately managed account has ever followed an SMA strategy, its totals are withheld on every read. ### Your fees Treasures collects management and performance fees from the followers of your strategy, and a share of every collection is yours. [`GET /fees`](/manager-api/get-fees) is the ledger of that share. There is no manager id in the path: the ledger is the one belonging to the key or session. ```bash curl https://api.treasures.io/manager/v1/fees \ -H "X-API-Key: cmk_..." ``` The response has five totals, your `fee_addresses` and a paged list of `collections[]`. | Field | What it is | | --- | --- | | `uncollected_usdc` | Fees charged to your followers and not yet recorded as collected. Collection runs weekly, when a follower exits, and on demand by Treasures, so it has no fixed date | | `collected_usdc` | The whole fee of every collection, all time | | `received_usdc` | Your share paid to your fee address on-chain, inside the transaction that collected the fee | | `platform_usdc` | `collected_usdc` minus `received_usdc`. It includes any part of your share that was not paid to your fee address on-chain | | `lifetime_usdc` | `uncollected_usdc` plus `collected_usdc` | | `fee_addresses` | The fee address registered for you on each address family (`sol`, `evm`), `null` where none is | - **Only `received_usdc` is a figure of your share.** Every other total is a whole fee, what your followers pay. A collection can show a `manager_share_usdc` above its `received_usdc`: the difference was not paid to your fee address on-chain and is counted in `platform_usdc`. Your share of a fee is fixed when it is collected, so an uncollected fee has none yet. - **`collections[]`** lists every collection from a follower of your strategy, newest first: `amount_usdc` is the whole fee, `manager_share_usdc` the part that is yours, and `received_usdc` the part of that paid to your fee address. For a separately managed account it also carries the account's address and the transactions that collected the fee. Page with `cursor` and `next_cursor`. - **`lifetime_usdc` can fall:** a fee waived when a follower closes, a strategy moving to another manager, or Treasures cancelling uncollected fees. The cases are listed in the [reference](/manager-api/get-fees). **Where the money goes is not yours to change here.** Your fee addresses are registered and changed by Treasures only, so a leaked key or session can read the ledger but cannot redirect a fee. To change an address, contact Treasures. If a key may have leaked, revoke it from your dashboard ([`DELETE /keys/{keyId}`](/manager-api/revoke-key)), which needs no recent sign-in, and mint a replacement, or ask Treasures to. ### Where to go next - [Manager API reference](/manager-api/treasures-finance-manager-api): every field on every route. - [Supported Services](/overview/supported-services): the assets your followers can hold. - [Strategy Signals](/enterprises/strategy-signals): how integrators read a published strategy's books. - [Support](/overview/support): partnerships and technical contact. --- ## Before this changelog Changes to the API before this changelog existed are recorded from the agent skill's point of view in the skills repo [CHANGELOG](https://github.com/treasures-io/treasures-finance-agent-skills/blob/main/CHANGELOG.md). That file covers every release from the API's launch, newest first: the Robinhood Chain and Base venues, tradability advisories, the `chain` set, foreign listings, quote warnings and the acknowledgement token, priority mode and the speed route, the wallet-less preview, ticker details, the sponsored user-operation lane, and the `/portfolio` identity gate. Entries that needed action from an integration are marked **Action** there, the same convention this changelog uses. From 2026-09-19 onward, every change to the public API surface gets its own entry here. --- ## Docs reorganised by audience This site is now organised into Users, AI Agents and Enterprises tabs, with the API Reference and this changelog as tabs of their own. ### What changed - Each audience has its own tab with a short sidebar: [Users](/users/using-the-web-app), [AI Agents](/agents/agent-skills) and [Enterprises](/enterprises/enterprise-integration). - New reference pages: [Compare Access Paths](/overview/compare-access-paths), [Routing and Priority Mode](/overview/routing-and-priority-mode) and [Integrator API Keys](/enterprises/integrator-api-keys). - The AI Agents tab points at the agent skills rather than mirroring them: [Agent Skills](/agents/agent-skills) covers what each skill does, how to install it and how versioning works. A machine-readable navigator is served at `/skill.md`. - Search is available from the header. ### URLs The agent guide moved from `/overview/integrating-your-agent` to `/agents/integrating-your-agent`. Every other page keeps its URL. --- ## GET /portfolio: portfolio_busy and the rewritten rate limits `GET /portfolio` can now answer `503 portfolio_busy` with a `Retry-After` header, and its rate limits changed for anonymous and keyed callers alike. ### What changed - [`GET /portfolio`](/api/get-portfolio) can answer **`503 portfolio_busy`** with a `Retry-After` header (delta-seconds) when the server is already computing as many fresh snapshots as it safely can and yours was not cached. Sleep `Retry-After` and retry the same request. A cached snapshot is never refused. - **Rate limits on `GET /portfolio`.** Anonymous calls have their own per-IP row (600 per minute). With a general `tik_` key the route is not bucketed by IP at all; the per-organisation bucket is the bound, sized for one request every 5 seconds per active end user. - **The blanket per-IP ceiling** across all endpoints is now set per environment, always at or above the per-endpoint limits, and no longer covers `/portfolio`. - **Portfolio snapshots refresh on a 30-second cadence** (`as_of`, `is_cached`). Polling faster returns the same snapshot. ### What to do Nothing is required. If your client has a generic transient-error branch, add `503 portfolio_busy` to it and honour `Retry-After`. Keyed integrators polling many end-user wallets should pace to the organisation bucket rather than spreading across IPs. Details: [Integrator API Keys](/enterprises/integrator-api-keys) and the [API Reference](/api/get-portfolio). --- ## Manager API: publish a strategy's target weights, read your fee ledger A new API for fund managers who run a strategy on Treasures: publish the target weights of your book and read the ledger of your share of follower fees. Separate base URL, separate credential. ### What changed - **New API surface at `https://api.treasures.io/manager/v1`**, documented in the [Manager API reference](/manager-api/treasures-finance-manager-api) with a guide at [Managing a Strategy](/managers/managing-a-strategy). - [`POST /strategies/{strategyId}/signals`](/manager-api/publish-signal) publishes the whole book you want followers to hold: 1 to 200 tickers with decimal-string weights summing to at most `1`, the remainder held as cash. A required, caller-chosen `dedupe_key` makes retries safe: a repeat returns `200` with the original signal and rebalances nothing. The response tells you which session the book executes in (`urgency`, `trading_day`, `ttl_at`). - [`GET /fees`](/manager-api/get-fees) returns what you are owed, what is pending and what has been paid, your recent payouts and a paged list of the collections behind them. - **Credential:** a manager API key (`cmk_…`) in `X-API-Key`, mandatory on every route, issued once by Treasures and not retrievable afterwards. 60 requests per minute per manager. ### What to do Nothing changes for callers of the B2B Public API or the delegated wallet API. If you manage a strategy on Treasures, ask your Treasures contact for a key and a strategy assignment, then start from [Managing a Strategy](/managers/managing-a-strategy). --- ## Cross-chain speed buys, and sells that pay out USDC on another chain Under `priority: "speed"` a buy can now reach a stock on a chain you are not funded on, in one signature set. A sell can pay its USDC out on another chain with the new `payout_chain` field. Both are opt-in; a request that sends neither gets the same routing as before. ### What changed **Sells: `payout_chain`** - [`POST /quote/sell`](/api/quote-sell) accepts `payout_chain` (`"sol"`, `"eth"` or `"base"`; absent or `null` keeps the old behaviour). The sale's USDC lands on that chain, in your own wallet there. A `sol/xstocks`, `base/coinbase` or `eth/ondo` position held on another chain sells cross-chain as one leg, marked by `payout_chain` on the leg, whatever the `priority`. A position that cannot pay out there is left out with a `cross_chain_route_unavailable` warning and is never sold on its own chain instead. - You fund the network gas for a cross-chain sell leg on the position's own chain (`gasless: false`), unless your paymaster sponsors it on the `execution: "user_operation"` lane. On Ethereum and Base it is two signed transactions, an exact-amount `approve` then a `deposit`, or one `evm_calls` payload under `execution: "user_operation"`. On Solana it is one versioned transaction. - [`GET /quote/{quote_id}/status`](/api/get-quote-status) legs gain `payout_chain` and `payout_tx_hash`. On `completed`, `payout_chain` names where the USDC actually landed, which is the sale's own chain if the payout was returned there. - [`GET /settlements`](/api/list-settlements) reports such a sale as two transactions: the sale (`sending`) and the payout (`receiving`). - New refusals: `400 invalid_request` with a `payout_chain: ` message prefix, and `422 no_routes` with `reason: "payout_route_unavailable"`. **Buys: cross-chain speed legs** - Under `priority: "speed"`, [`POST /quote/buy`](/api/quote-buy) and [`POST /quote/preview`](/api/quote-preview) may quote a stock you are not funded on as a cross-chain leg instead of dropping it. The leg carries `origin_chain` (where your stablecoin leaves from; `chain` stays the destination), `cross_chain_cost_bps` and `cross_chain_cost_usdc`, and `base_asset` names the origin's currency. - `chain: ["eth"]` with `"speed"` on a buy or preview now returns a cross-chain leg or `422 no_routes` instead of an unconditional `400`. - New `warnings[]` codes `cross_chain_route_unavailable` and `cross_chain_price_deviation`, a new `no_routes` reason `cross_chain_wallet_missing`, and new per-leg `error_code`s `refunded`, `deposit_reverted`, `delivered_other_currency`, `cross_chain_unsettled` and a per-leg `quote_stale`. **Also** - `cost_breakdown_bps.dex_swap_fee_bps` is nullable: `null` only on a cross-chain leg. - `Chain` gains `arbitrum` and `Protocol` gains `reality`, for an upcoming venue; the `reality` listings block on [`GET /stocks`](/api/list-stocks) and [`GET /stocks/tickers`](/api/list-stock-tickers) is `null` until it opens. - `GET /quote/{quote_id}/status` asks for `poll_after_ms: 3250` (was `10250`) when only gasless or Solana legs remain. - An on-chain venue price more than 1.5x away from the reference market price reads `share_price_usd: null` on [`GET /stocks/{ticker}`](/api/get-stock-detail). ### What to do **Action (strict response parsers only):** accept `null` for `cost_breakdown_bps.dex_swap_fee_bps`. A caller that sends neither `priority: "speed"` nor `payout_chain` never receives it. Nothing else is required. [Buying and Selling](/overview/buying-and-selling) maps every combination of `priority`, `execution` and `payout_chain` to the legs it returns and how to sign each one. To use the new routes, update to skill `1.16.0` ([Agent Skills](/agents/agent-skills)) or read the [API Reference](/api/quote-sell). Routing rules: [Routing and Priority Mode](/overview/routing-and-priority-mode). --- ## Integrator fees and payouts (Changelog) Integrators can now charge their own fee on the trades their users make through them, see it on every quote and settled trade, and claim it in USDC through four new routes under `/payouts`. All of it needs an integrator key. ### What changed - **Your fee on every quote made with your key.** Treasures configures a default fee and a ceiling for your key; send `integrator_fee_bps` on [`POST /quote/buy`](/api/quote-buy), [`POST /quote/sell`](/api/quote-sell) or [`POST /quote/preview`](/api/quote-preview) to use a different fee on one quote. Each leg reports it as `cost_breakdown_bps.integrator_fee_bps`, and `estimated_output_*` already allows for it. - **Submit with the key that quoted.** A quote that carries your fee is refused at [`POST /trade/submit`](/api/submit-trade) with `403 quote_integrator_mismatch` if it arrives without that key. - **New quote refusals:** `400 invalid_integrator_fee`, `400 integrator_fee_requires_api_key` and `503 integrator_fee_misconfigured`. - **Settlements:** [`GET /settlements`](/api/list-settlements) gains an `integrator_fee` entry in `fee_costs`, with the `payout_id` it went out in, and two filters, `payout_id` and `payout_status`. - **Payouts**, general `tik_` key only: [`GET /payouts/accrued`](/api/get-accrued-integrator-fees) (what you are owed and whether you can claim it), [`POST /payouts`](/api/request-payout) (claim all of it to your registered address; `Idempotency-Key` required), [`GET /payouts`](/api/list-payouts) and [`GET /payouts/{payoutId}`](/api/get-payout). ### What to do Nothing, if you do not charge a fee: a quote without your key is unchanged, and with it your configured default applies. To charge or claim fees, read [Integrator Fees and Payouts](/enterprises/integrator-fees-and-payouts), and always submit fee-carrying quotes with the key that requested them. --- ## Manager API: replan: and catchup: dedupe_key prefixes are reserved `POST /strategies/{strategyId}/signals` now refuses a `dedupe_key` that starts with `replan:` or `catchup:` (any case). Those prefixes are reserved for signals the platform generates itself. ### What changed - A `dedupe_key` beginning with `replan:` or `catchup:`, in any letter case, is refused with `400 invalid_request` and the `message` names the field. Every other key up to 200 characters is accepted as before. - Documented on the [`dedupe_key`](/manager-api/publish-signal) request field and in [Managing a Strategy](/managers/managing-a-strategy#dedupe_key-your-idempotency-key). ### What to do **Action:** if any key you publish starts with `replan:` or `catchup:`, rename it. Keys that never used those prefixes need no change. --- ## Manager API: books naming a ticker off the followers' venues are refused `POST /strategies/{strategyId}/signals` now refuses a ticker that is on the Treasures catalog but not listed on the venues Treasures buys on for followers, with `422 unavailable_tickers`. Live since 2026-09-30; documented on 2026-10-06. ### What changed - A book naming such a ticker is refused with `422 unavailable_tickers`, which lists the tickers in the order you sent them. Nothing is published. - It is a listing check, not a tradability check. A ticker listed on those venues is accepted even while it is halted or thinly traded, and the `tradability` field on [`GET /stocks/tickers`](/api/list-stock-tickers) plays no part. - When a book has both kinds of ticker, only `422 unknown_tickers` is returned; fix those first. - Both checks apply to a new `dedupe_key` only. Repeating a key you already used returns the original signal. - Documented on [`POST /strategies/{strategyId}/signals`](/manager-api/publish-signal) and in [Managing a Strategy](/managers/managing-a-strategy#errors-when-publishing). ### What to do **Action:** handle `422 unavailable_tickers` by resending the book without the listed tickers. Leaving a ticker out sells it from followers' portfolios, so check that is what you want before you resend. --- ## Backpack Securities on Solana, and buy quotes ranked by where your money is Backpack Securities tokenized stocks now trade as a third stock protocol on Solana, beside `ondo` and `xstocks`. Buy quotes and previews also take an optional `origin_chain`, which ranks the legs for money held on one chain. Both are additive on the request; strict response parsers have one thing to check. ### What changed **Backpack Securities (`protocol: "backpack"`)** - [`POST /quote/buy`](/api/quote-buy), [`POST /quote/sell`](/api/quote-sell) and [`POST /quote/preview`](/api/quote-preview) accept `protocol: "backpack"`, alone or in a `protocol` array (arrays now take one to six values). It is Solana only: it pairs with `chain: "sol"`, and there is no Ethereum cell. - It is co-ranked, not opt-in. An unpinned Solana buy ranks a listed `backpack` cell against `ondo` and `xstocks`, and an unpinned sell fills from a held Backpack position like any other. - [`GET /stocks`](/api/list-stocks) and [`GET /stocks/tickers`](/api/list-stock-tickers) gain an optional `backpack` listing block, the same shape as `ondo` and `xstocks`, with `eth_address` always `null`. The key is absent, not `null`, while the venue is switched off, and a cell is listed only once its token has supply. [`GET /stocks/{ticker}`](/api/get-stock-detail) lists a `backpack` entry in `listings[]` on the same terms. [`GET /stocks/prices`](/api/get-stock-prices) carries no `onchain.backpack`: compare a Backpack leg against `tradfi`. - A buy pinned to a `backpack` cell that is not listed is `422 no_routes`. Sells are never gated this way. - Backpack positions report the plain stock symbol as `token_ticker` (`"MU"`, no suffix) on [`GET /portfolio`](/api/get-portfolio), [`GET /trades`](/api/list-trades) and [`GET /settlements`](/api/list-settlements), with `protocol: "backpack"` and `chain: "sol"`. - Under `priority: "speed"`, `sol/backpack` is reachable as a cross-chain buy, and a held Backpack position sells cross-chain with `payout_chain`. - The [`GET /settlements`](/api/list-settlements) filters now list every value: `chain` adds `arbitrum`, and `protocol` adds `reality` and `backpack`. **`origin_chain` on buy quotes and previews** - [`POST /quote/buy`](/api/quote-buy) and [`POST /quote/preview`](/api/quote-preview) accept `origin_chain` (`"sol"`, `"eth"`, `"robinhood"` or `"base"`), the chain your stablecoin sits on. Omit it and nothing changes. - On the default route it changes the ranking only. Every leg on another chain ranks as if it also paid the measured cost of moving the money there, so `quotes[0]` is the cheapest leg for money held on that chain. No leg is added, dropped or repriced, and a leg on another chain is still a same-chain leg: fund that chain before you submit it. - Under `priority: "speed"` it is the only chain a cross-chain leg may spend from, so the leg's `origin_chain` always equals the value you sent. `/quote/preview` prices as if the whole amount sits there (`sol` when you omit it, as before). - New refusal: `400 invalid_request` when `/quote/buy` names an `origin_chain` whose wallet the request does not carry (`sol_wallet` for `sol`, `eth_wallet` otherwise). `/quote/sell` rejects the field as unknown. ### What to do **Action (strict response parsers only):** `backpack` can appear as a `protocol` on response rows for any wallet that holds the tokens, whatever you send. Treat `chain` and `protocol` as open vocabularies and never fail a parse on an unlisted value. Branch on `protocol` and `chain`, not on the shape of `token_ticker`. **Action (only if you depend on today's Solana routing):** an unpinned Solana buy can now route to a Backpack cell. To keep the old routing, send `protocol` as an array of the protocols you want. Nothing else is required. To use the new fields, update to skill `1.17.0` (and the wallet skill to `1.4.0`) from [Agent Skills](/agents/agent-skills), or read the [API Reference](/api/quote-buy). The routing rules are in [Routing and Priority Mode](/overview/routing-and-priority-mode), and every combination of options is mapped in [Buying and Selling](/overview/buying-and-selling). --- ## Strategy signals for integrators, and batch trade submission Integrators holding a general key can now read the target-weight books of the copy-trading strategies Treasures publishes to them, ask for the orders that exit a book from one of their users' Solana wallets or rebalance it to the book, and submit up to 25 signed quotes in one request. Eight new routes, all additive; nothing changes for existing callers. ### What changed **Strategy books**, under a new `Signals` tag, general `tik_` key only: - [`GET /signals/strategies`](/api/list-signal-strategies): the catalog of strategies published to integrators, newest first, each with its latest book's `book_hash`, `book_as_of` and `signal_id`, so one call says which books changed. - [`GET /signals/strategies/{id}`](/api/get-signal-strategy): one strategy (id or slug) with its current book: every ticker and its weight, `deployed_weight`, `cash_weight` and a `book_hash` that changes only when the weights move. `as_of` is when Treasures ingested the book, not the filing date. - [`GET /signals/strategies/{id}/history`](/api/list-signal-strategy-history): past books as full weight vectors, newest first, with cursor paging. **Orders from a book**, general key plus an [ownership proof](/overview/ownership-proof) for the Solana wallet: - [`POST /signals-orders/exit/plan`](/api/plan-signal-orders-exit) and [`POST /signals-orders/rebalance/plan`](/api/plan-signal-orders-rebalance) return the orders only, nothing quoted: the full-share sells that leave a book, or the sells and buys that bring the wallet's positions to it, with a `funding` block that drives the two-round reshuffle. These are the default for human and hardware-wallet flows. - [`POST /signals-orders/exit`](/api/quote-signal-orders-exit) and [`POST /signals-orders/rebalance`](/api/quote-signal-orders-rebalance) return the same orders, each with its signable `/quote/sell` or `/quote/buy` answer, for programmatic signers who can sign inside a Solana quote's window. They refuse a second call for the same wallet and strategy while an earlier call's quotes are live (`409 orders_in_flight`, with `Retry-After`). - Every orders route takes `expected_book_hash` and refuses with `409 book_changed` when the book moved. Treasures never signs: each order is submitted through `POST /trade/submit` by the wallet's owner, as any trade is. **Batch submission**, general key only: - [`POST /trade/submit/batch`](/api/submit-trade-batch) takes up to 25 `POST /trade/submit` bodies and answers each in request order with the `http_status` and body the single route would have given. Same-chain Solana legs only, no `quote_id` twice, and a body cap of 100 KB. ### What to do Nothing, unless you want the new routes: existing routes, bodies and responses are unchanged. The signals routes need a general integrator key; a read-only `trk_` reporting key is refused. The agent skill does not cover these routes yet, so read [Strategy Signals](/enterprises/strategy-signals) and the [API Reference](/api/signals) directly. The per-route key table on [Integrator API Keys](/enterprises/integrator-api-keys) and the proof table on [Ownership Proof](/overview/ownership-proof) list the new routes. --- ## A per-chain guide, and the Robinhood Chain approval address [Chains and Venues](/overview/chains-and-venues) is a new page with each chain's rules in one place: the stablecoin it trades in, who pays gas, which approvals to send and to which address, which quote options it takes, its sessions and minimums, and the mistakes integrators hit most. It also corrects one rule: a Robinhood Chain trade needs a one-time approval, to an address of its own. ### What changed - **Robinhood Chain approvals.** A gasless order on Robinhood Chain needs the wallet's one-time ERC-20 approval, like every other EVM chain: USDG to buy, the stock token to sell, sent with a little ETH on Robinhood Chain. The spender is `0x5A705DE8982235a7fa45bB83dCaCf03a211389C7`, not the `0x111111125421ca6dc452d289314280a0f8842a65` used on Ethereum, Base and Arbitrum. Earlier guidance said Robinhood Chain needed no native gas at all; that was wrong for the approval. - **Arbitrum is documented as open.** Reality's tokenized stocks trade on Arbitrum One, listed per ticker once minted, in Arbitrum-native USDC, with approvals to `0x1111…0a65` on Arbitrum and no speed route, cross-chain leg, `origin_chain` or `payout_chain`. - **Robinhood Chain liquidity.** Listed names are no longer described as four fillable tickers. Read `tradability` and `min_trade_size_usd` on the `robinhood` listing block instead. ### What to do - **Action, if you trade on Robinhood Chain:** approve USDG (and, before a sell, the stock token) to `0x5A705DE8982235a7fa45bB83dCaCf03a211389C7` on Robinhood Chain, and keep a little ETH there to send it. Without it the order cannot fill (`not_enough_balance_or_allowance`). - **Action, if you use `priority: "speed"` on Robinhood Chain:** hold USDG on Robinhood Chain first. The speed leg spends the wallet's own USDG and is dropped (`insufficient_balance`) when it is short; no other chain's USDC can fund it. - Nothing else changed in the API. --- ## Pay Solana fees for your users, bridge between any two chains A Solana wallet holding no SOL can now trade: send `sol_fee_payer`, a Solana wallet you fund, on buy and sell quotes and it pays the fees (a first buy of an `ondo` token is the exception). Bridging takes any two supported chains, with an optional mode where Treasures submits the deposit, and every quote leg carries its own `expires_at`. The reference also documents BNB Smart Chain, which is not open yet. The new fields are additive. Two things change for every caller: each quote leg now carries its own `expires_at`, enforced at submit, and a buy alternative that had already expired is left out, so `quote_index` values can skip. ### What changed **Paying Solana fees for your users.** A wallet holding almost no SOL (under about 0.003) is refused on Solana with `422 no_routes`, because the quote itself needs the SOL. [`POST /quote/buy`](/api/quote-buy) and [`POST /quote/sell`](/api/quote-sell) now take `sol_fee_payer`: one fixed Solana address you fund. Each Solana leg then comes back either carrying `sol_fee_payer` (your wallet pays the network fees and the rent of any token account the trade opens; the leg reads `gasless: false` with `estimated_gas_usd`) or as a market-maker fill without it, which pays its own fee. Every `ondo` leg is a market-maker fill, so the field never pays for one, and a first buy of an `ondo` token still opens the user's token account at the wallet's own cost (about 0.01 SOL). Sign a leg that carries it as issued, with both your `sol_fee_payer` and the user's `sol_wallet`. The field needs `sol_wallet`, must differ from it, is refused beside `quote_only: true` and on `/quote/preview`, and is screened like your other wallets. Details: [Paying Solana fees for your users](/overview/buying-and-selling#paying-solana-fees-for-your-users). **Bridging between any two chains.** [`POST /bridge/quote`](/api/quote-bridge) takes any two distinct chains among `sol`, `eth`, `robinhood`, `base`, `arbitrum` and `bnb`, each side in its own base currency (USDG on Robinhood Chain). `sol_wallet` and `sol_signature` are optional when neither side is Solana. An optional `delivery: "submit"` returns a payload you sign and send to the new [`POST /bridge/{bridge_quote_id}/submit`](/api/submit-bridge), and Treasures sends the deposit: from Ethereum, Base or Arbitrum that is one or two typed-data signatures with no approval, no native gas and no nonce, and from Solana a transaction Treasures broadcasts. Other origins answer `400 unsupported_route` for now. Resubmitting the same body is safe for an hour. **A deadline on every leg.** Each executable leg in `quotes[]` now carries its own `expires_at`. The top-level `expires_at` keeps its meaning (the earliest leg's), and [`POST /trade/submit`](/api/submit-trade) enforces the deadline of the leg you signed; a sell signs every leg, so it is bound by the earliest. A buy alternative that had already expired when the quote was built is left out, so `quote_index` values can skip. **BNB Smart Chain, documented ahead of opening.** The reference lists `chain: "bnb"` and `protocol: "bstocks"`. The venue is not open yet: its listings stay hidden and a buy there is `422 no_routes`. See [Routing and Priority Mode](/overview/routing-and-priority-mode) for what will differ there, and read the [listings](/api/list-stock-tickers) rather than assuming it is available. ### What to do - **Action, if your users' Solana wallets hold no SOL:** send `sol_fee_payer` on every buy **and** sell quote. It covers only the quote it rides on: a wallet still short of SOL is refused on the sell (`422 no_routes`) unless the sell carries it too. Keep about 0.01 SOL in wallets that buy `ondo` tokens they do not hold yet. - **Action, if you index legs by array position:** echo each leg's `quote_index` instead, because the values can now skip. - **Strict response parsers:** accept the new per-leg `expires_at` and `sol_fee_payer` keys, and treat `chain` and `protocol` as open vocabularies. - Nothing else: bridges quoted without `delivery` behave exactly as before. --- ## Search, sort and paging on GET /stocks [`GET /stocks`](/api/list-stocks) can now search, sort and page the catalog through four optional query parameters. Without them the response is unchanged: the whole catalog, in ticker order. ### What changed - `q`: a case-insensitive substring of the ticker, the company name or any venue's `token_ticker` (`apple`, `TSLA`, `AAPLx`), 1 to 100 characters. - `sort`: `market_cap`, `volume_1d`, `change_24h`, `price`, `pe` or `ticker`. A stock missing the metric sorts last in both directions, and ties break by ticker. - `order`: `asc` or `desc`. It defaults to `asc` for `ticker` and `desc` for every metric; sent without `sort`, it orders by ticker. - `page`: 1-based pages of 25 rows. Only `page` changes the response: it adds `page`, `next_page` (`null` on the last page) and `total` (the rows matching `q` across all pages). Without it, every matching row comes back. Search, sort and paging run over the same cached snapshot as the plain read. ### What to do Nothing, unless you want the new parameters. Any other query parameter on `/stocks` is still `400 invalid_request`. --- ## Sponsored lane: a wallet's first trade can delegate it On the sponsored lane (`priority: "speed"` with `execution: "user_operation"`), a wallet that has never been delegated on Robinhood Chain or Base can now trade from its very first operation there. The quote is served, and that first UserOperation carries the wallet's EIP-7702 authorization as `eip7702Auth`, so the delegation and the trade land in the same transaction. A caller whose wallet is already delegated sees no change. ### What changed **A wallet with no code is quoted.** [`POST /quote/buy`](/api/quote-buy) and [`POST /quote/sell`](/api/quote-sell) used to refuse any wallet not yet delegated to Modular Account v2 on the chain with `400 wallet_not_delegated`. A wallet with no code there is now quoted like a delegated one. `wallet_not_delegated` (the `400` when pinned, the `speed_route_unavailable` reason when not) now means only a wallet delegated to some other code. **`eip7702Auth` on the first operation.** [`POST /trade/submit`](/api/submit-trade) takes an optional `user_operation.eip7702Auth`: `{ address, chainId, nonce, r, s, yParity }`, spelled as your account SDK's bundler call spells it. Treasures passes it to the bundler, which applies the delegation in the same transaction as the operation. It must name a Modular Account v2 implementation, carry the leg's `chain_id` (never `0`, which would delegate the wallet on every chain), be a low-s signature and be signed by `sender`; anything else is `invalid_signature` and nothing is sent. It does not change the operation's hash. An authorization the chain skips (a stale `nonce`) leaves the wallet without code, and the operation is refused as `swap_reverted`. Details: [Buying and Selling](/overview/buying-and-selling) and [Routing and Priority Mode](/overview/routing-and-priority-mode#the-sponsored-lane-execution-user_operation). ### What to do - **If your wallets delegate on their first operation:** send `eip7702Auth` with that operation on each chain (account SDKs with a 7702 mode attach it on their own), then omit it once the wallet is delegated. - **If you delegated wallets out of band to get past `wallet_not_delegated`:** you no longer need to, though it still works. - Nothing else: an already-delegated wallet's quotes and operations are unchanged. --- ## Refusals that say why, firm Solana minimums, and BNB Smart Chain opens A `422 no_routes` that used to come back with no reason now says what happened, and names a minimum size where one is known. A `priority: "speed"` refusal lists the listings speed skipped, so you know a quote without `priority` may succeed. Solana minimums now come from quotes bound to a wallet, the kind a market maker honours. And BNB Smart Chain (`bnb`) is open for `ondo` and `xstocks`. Everything is additive on the request; the **Action** items matter only if you match `reason` or `error_code` against a fixed list. ### What changed **New `reason` values on `422 no_routes`.** - `no_market_maker_fill`: market makers declined the order at that size. - `insufficient_gas`: the Solana wallet held too little SOL for fees, under 0.002 SOL (0.01 SOL when the trade opens a token account). Never on `quote_only`, [`/quote/preview`](/api/quote-preview) or a request carrying `sol_fee_payer`. - `cross_chain_route_unavailable`: the cross-chain route a speed buy needed could not be used. **A minimum from your own wallet.** A Solana refusal under a market maker's size can carry `min_notional_usdc` with the size a market maker quoted your wallet at refusal time. On [`POST /quote/sell`](/api/quote-sell) it is a USDC value, never a share count. **Speed refusals name what they skipped.** A speed buy or preview that ends in `422 no_routes` lists each listing speed never quotes (an `eth` or `bnb` relayed order, or Reality on `arbitrum`) in `warnings[]` as `speed_route_unavailable` with `reason: "no_speed_venue"`, `chain` and `protocol`. See [Routing and Priority Mode](/overview/routing-and-priority-mode). **Speed never quotes a Solana leg the wallet cannot fund.** Under `priority: "speed"` a buy's Solana leg is dropped when the `sol_wallet` reads short; when that leaves nothing and no other chain's wallet covers the amount, the refusal reads `insufficient_balance`. There is still no general USDC balance check on [`POST /quote/buy`](/api/quote-buy), and nothing is checked at [`POST /trade/submit`](/api/submit-trade). **Specific Solana execution codes.** A failed Solana leg now reports `market_maker_rejected` (the market maker refused the fill when the transaction was sent) or `not_landed` (the transaction was reported as not landing; a leg short of the token it spends also ends here), and keeps the reported signature on `tx_hash`. **Firm Solana minimums.** `sol_min_trade_size_usd` on the `ondo`, `xstocks` and `backpack` listing blocks now comes, where a market maker fills the listing, from a quote bound to a wallet rather than a price-only preview. Expect higher minimums on many Solana xStocks listings, and none published where nothing filled. A market maker that declines a small buy usually declines a small sell too, so a Solana position worth less than its minimum may not be sellable there until topped up. **BNB Smart Chain is open for `ondo` and `xstocks`.** Their legs are gasless relayed orders like Ethereum's, signed within about 14 seconds of the quote, in 18-decimal Binance-Peg USDC with one-time approvals paid in BNB. `bstocks` is not open yet. See [Chains and Venues](/overview/chains-and-venues#bnb-smart-chain-bnb). ### What to do - **Action:** if your client checks `reason` against a closed list, add `no_market_maker_fill`, `insufficient_gas` and `cross_chain_route_unavailable`; if it checks `error_code`, add `market_maker_rejected` and `not_landed`. On `not_landed` with a `tx_hash`, check that transaction on chain before trading the same size again. - On `no_speed_venue`, re-quote without `priority` when a relayed order that can take minutes to fill works for you. - Size Solana orders at or above `min_notional_usdc` or `sol_min_trade_size_usd`, and avoid partial sells that leave a Solana position below its minimum. - To trade on BNB Smart Chain, hold Binance-Peg USDC and a little BNB there, approve `0x111111125421ca6dc452d289314280a0f8842a65` once per token, and sign each leg as soon as it is quoted. - Skill users: update to `treasures-b2b-api` 1.22.0 (`npx skills add treasures-io/treasures-finance-agent-skills`). --- ## A size refusal names its minimum on mixed refusals A `422 no_routes` whose `reason` is `amount_too_small` now carries `min_notional_usdc` whenever a venue that refused for size has a known minimum above your order, even when other venues refused for another reason. Before, such a refusal could come back with the reason and no number. Additive: nothing to change. ### What changed - **`min_notional_usdc` on more refusals.** It applies to [`POST /quote/buy`](/api/quote-buy), [`POST /quote/preview`](/api/quote-preview) and [`POST /quote/sell`](/api/quote-sell). On a sell it is a USDC value, never a share count. - **The number covers only the venues that refused for size.** A venue that refused for another reason, for example `insufficient_gas` on a Solana leg, still needs its own fix: an order at or above the minimum can reach the venues that refused for size, not that one. - **Skill version.** The `treasures-b2b-api` skill is `1.22.1`. ### What to do Nothing. If you already read `min_notional_usdc` when it is present, you now get it on more refusals. --- ## Manager API: dashboard sign-in, strategy and SMA account reads, self-service keys, and a reshaped fee ledger The Manager API reference and guide now cover everything the API serves. It accepts a signed-in session on the Treasures dashboard alongside your manager API key, adds reads for the strategies assigned to you and for the separately managed accounts of an SMA strategy, and lets a dashboard session mint and revoke your keys. Two changes reach existing key callers and are marked **Action**: [`GET /fees`](/manager-api/get-fees) has a new response shape, and a request with no credential now answers `401 unauthorized`. ### What changed **Action: the fee ledger is reshaped.** [`GET /fees`](/manager-api/get-fees) no longer returns `owed_usdc`, `pending_usdc`, `paid_usdc` or `payouts[]`. Payouts are no longer booked through this API. The ledger now reports the part of your share paid to your fee address on-chain, inside the transaction that collects the fee (`received_usdc`); any part not paid that way is counted in `platform_usdc`. - The totals are `uncollected_usdc`, `collected_usdc`, `received_usdc`, `platform_usdc` and `lifetime_usdc`. Only `received_usdc` is your share; the others are whole fees, what your followers pay. - `fee_addresses` is the fee address registered for you on each address family (`sol`, `evm`), or `null`. - In each row of `collections[]`, `leader_share_usdc` is renamed `manager_share_usdc`. The row gains `received_usdc`, and for a separately managed account its `account` address and the `transactions` that collected the fee. **Action: no credential is `401 unauthorized`.** A request that carries no credential at all used to answer `401 invalid_api_key`. A key that is present but malformed, unknown or revoked still answers `invalid_api_key` or `key_revoked`, so a system that always sends its key sees no change. **A second credential: the dashboard session.** Your own login on the Treasures dashboard, as a Member of the Organization your manager account belongs to, is accepted on every route. The headers it sends are in the [Manager API reference](/manager-api/treasures-finance-manager-api). - Publishing a book from a session ([`POST /strategies/{strategyId}/signals`](/manager-api/publish-signal)) and minting a key need a sign-in made in the last 15 minutes, or are refused `403 reauth_required`. If Treasures cannot confirm the sign-in, the request is refused `503 sign_in_check_unavailable` and nothing is written. Neither answer is ever given to an API key. - A Member who is not an Admin can do only what its permissions grant (`403 permission_denied` otherwise). A login in more than one Organization names the one it acts for in `X-Organization-Id`. - New refusals on every route: `403 manager_not_linked`, `403 organization_suspended` and `403 permission_denied`. `403 manager_suspended` now refuses your dashboard session as well as your keys. - When `X-API-Key` is present it is the only credential checked. - Sessions have their own budget of 120 requests per minute per manager. The 60 per minute your keys share is unchanged, and neither budget can use up the other. **Reading your strategies**, with a key or a session: - [`GET /strategies`](/manager-api/list-strategies): every strategy assigned to you, at every status including `draft`, with its newest book, its live follower count, its `audience` (`retail` or `sma`) and the total value of its followers' portfolios once at least three followers contribute to it. - [`GET /strategies/{strategyId}/signals`](/manager-api/list-strategy-signals): every book published into the strategy at every status, newest first, with why the last plan attempt gave up and, once a book is final and at least three followers hold orders on it, its order counts by state. - [`GET /strategies/{strategyId}/performance`](/manager-api/get-strategy-performance): the strategy's daily performance line, a backtest where one was published followed by the live model. Served for `draft` strategies too. **SMA accounts**, for a strategy whose `audience` is `sma` (a retail strategy answers `404 strategy_not_sma`). Each account is named by its own wallet addresses, never by the client behind it, and the three-follower minimum does not apply. - [`GET /strategies/{strategyId}/accounts`](/manager-api/list-strategy-accounts): every account assigned to the strategy, with its state and latest daily valuation, plus totals across the accounts. - [`GET /strategies/{strategyId}/accounts/{address}/fills`](/manager-api/list-account-fills): every order that filled for one account, with its USDC amount and each leg's chain and transaction hash. - [`GET /strategies/{strategyId}/accounts/{address}/holdings`](/manager-api/get-account-holdings): a live read of one account's positions, stablecoins and gas, answered `503` instead of a partial figure when a read does not complete. It has its own budget of 20 calls a minute per credential kind, and answers `503 portfolio_busy` with `Retry-After` from 00:03 to 00:40 UTC, around the daily valuation. - [`GET /strategies/{strategyId}/accounts/{address}/performance`](/manager-api/get-account-performance): every daily valuation of one account, oldest first, numbered by assignment. - [`GET /strategies/{strategyId}/orders`](/manager-api/list-strategy-orders): every fill across the strategy's accounts, newest first, optionally narrowed to one `signal_id`. **Keys**, from a dashboard session only (an API key is refused `403 session_required`): - [`GET /keys`](/manager-api/list-keys), [`POST /keys`](/manager-api/create-key) and [`DELETE /keys/{keyId}`](/manager-api/revoke-key) list, mint and revoke your API keys. A minted key is shown once. You may hold 10 active keys and make 20 self-service mints in any 24 hours. Revoking needs no recent sign-in, so a leaked key can always be shut off at once. **Smaller changes.** - Every `{strategyId}` accepts the strategy's slug as well as its `cst_` id. - A query parameter on a route that takes none, publishing included, is refused `400 invalid_request`. - A `stale` book, queued for the next session, starts 30 minutes after that session's open. ### What to do - **Action:** if you read `GET /fees`, move to the new fields. `owed_usdc`, `pending_usdc`, `paid_usdc` and `payouts[]` are gone, and `leader_share_usdc` on a collection is now `manager_share_usdc`. - **Action:** if you match on `401 invalid_api_key` to detect a missing key, match `401 unauthorized` as well. - Otherwise nothing: publishing with a key is unchanged. The guide is [Managing a Strategy](/managers/managing-a-strategy). --- ## Strategy signals: plan a BNB Smart Chain wallet's orders The two strategy signals plan routes, [`POST /signals-orders/exit/plan`](/api/plan-signal-orders-exit) and [`POST /signals-orders/rebalance/plan`](/api/plan-signal-orders-rebalance), now take `chain: "bnb"` and plan the orders for a wallet on BNB Smart Chain. The plan reads the wallet's Ondo and xStocks positions and its Binance-Peg USDC, and tells you which token approvals are missing. Nothing changes for a caller that does not send `chain: "bnb"`. ### What changed **`chain: "bnb"` on the plan routes.** Send `chain: "bnb"`, `eth_wallet` in place of `sol_wallet`, and an ownership proof carrying `eth_signature`. The response has the same shape as on Solana, with `usdc_available` the wallet's Binance-Peg USDC. - **The inline routes stay Solana only.** `POST /signals-orders/exit` and `POST /signals-orders/rebalance` refuse `chain: "bnb"` with `400 invalid_request`. Quote each planned order yourself with `chain: "bnb"` and `protocol: ["ondo", "xstocks"]`, and submit each on its own [`POST /trade/submit`](/api/submit-trade), never as a batch. - **Always pin `protocol` on those quotes.** The plan reads Ondo and xStocks only. An unpinned `bnb` quote can route to bStocks, and a name held as bStocks reads as `not_held`: a rebalance buys its full target again, and an exit leaves it in the wallet. - **`approvals`.** A bnb plan lists one row for USDC when it buys and one per token a planned sell spends, each with `token`, `spender` and `approval_required`. `true` means approve before submitting, `null` that the allowance could not be read. It is advisory: no approval is built for you. - **Venue minimums.** On bnb, `below_min_notional` uses each name's venue floor ($10 for a name on xStocks alone, $1 otherwise) and also applies on an exit plan. A scaled buy is held to its floor, so a small `amount_usdc` over many names can plan no buys, with no error. - **A new skip reason, `price_unavailable`,** on a bnb exit plan only: a held name with no price. - **No quote-call cap on bnb.** The 25-order cap applies. **Smaller changes on Solana.** - The request schemas no longer list `sol_wallet` as required, since a bnb body omits it. A Solana body still needs it. - A body with neither `chain` nor `sol_wallet` is still `400 invalid_request`, with a different `message`. ### What to do - Nothing, if you plan Solana wallets only. - If you model `skipped[].reason` as a closed set and plan to send `chain: "bnb"`, add `price_unavailable`. - The guide is [Strategy Signals: On BNB Smart Chain](/enterprises/strategy-signals#on-bnb-smart-chain), with a worked example in [Copying a Strategy on BNB Smart Chain](/enterprises/copying-a-strategy-on-bnb). --- ## Speed sells fall back to the relayed route, and unlisted tickers leave the stocks reads A `priority: "speed"` sell on Robinhood Chain or Base that the speed route cannot price is now quoted on its relayed route, with a new `speed_route_fallback` warning, where the position used to be left out or the quote refused. One **Action** item, for callers that send `priority: "speed"` on [`POST /quote/sell`](/api/quote-sell). Separately, a ticker that no venue lists a token for is no longer served by the stocks reads. ### What changed **Action: a speed sell can return a relayed leg.** When the speed route answers `no_routes` for a `robinhood` or `base` position on `/quote/sell`, that leg is in `quotes[]` on its relayed route. - The leg has `gasless: true` and one typed-data payload, also when you sent `execution: "user_operation"`. Its fill can take minutes, not one block. - `warnings[]` carries `speed_route_fallback` for it, with `chain`, `protocol`, `reason` (`no_routes`), `approval_needed` and `approval_spender`. - `approval_needed: true` means the order cannot fill until the wallet approves the stock token to `approval_spender`. A relayed order never bundles an approval and this API does not send it for you: [`POST /trade/submit`](/api/submit-trade) may refuse the order as `not_enough_balance_or_allowance`, or it stays pending and expires unfilled. `false` means the allowance covers the sale, and `null` that it could not be read. - The warning is sent only for a leg the response carries. A position the relayed route priced but another leg outranked reads `speed_route_unavailable` with `reason: "no_routes"`. - Buys are unchanged: a leg the speed route cannot serve is still absent, with `speed_route_unavailable`. **`speed_route_unavailable` repeats less.** It is sent once per `chain` and `reason` (once per `chain`/`protocol` pair for `no_speed_venue`, and once in all for `disabled`). **A ticker with no listing is not served.** A ticker that no venue lists a token for is left out of [`GET /stocks`](/api/list-stocks), [`GET /stocks/tickers`](/api/list-stock-tickers) and every other stocks read. **`extension` in the reference.** The typed-data payload schema documents an `extension` field. This API never sends it, so there is nothing to handle. **Skill version.** The `treasures-b2b-api` skill is `1.23.0`. ### What to do - **Action:** if you send `priority: "speed"` on a sell and assume every leg is a transaction to sign whole, branch on `gasless` (or the payload type) per leg, and handle `approval_needed` before you submit a relayed leg. - The guides are [Routing and Priority Mode](/overview/routing-and-priority-mode#what-you-trade-away) and [Buying and Selling](/overview/buying-and-selling#when-a-quote-comes-back-short).