Skip to main content

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} for company research data, POST /quote/preview to price a trade with no wallet attached, GET /settlements for your organisation's settled trades, and the /payouts routes to claim your integrator fees.
  • Your own fee on your users' trades. Quotes requested with your key charge your integrator fee, which you claim in USDC whenever you choose.
  • Attribution. A trade submitted with your key on POST /trade/submit 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 reads Robinhood Chain and Base 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, and 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 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).

  1. Discover. GET /stocks/tickers for the catalog with per-listing availability and warnings, GET /stocks/prices for live tradfi and on-chain prices. Add GET /stocks/{ticker} 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 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 or POST /quote/sell with an 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 with your X-API-Key. That header is what attributes the trade to you.
  5. Track. Poll GET /quote/{quote_id}/status at the response's poll_after_ms until the aggregate is terminal.
  6. Read holdings. GET /portfolio and GET /trades per end-user wallet pair, always with your key so that holdings on Robinhood Chain and Base are read for every wallet.
  7. Reconcile. GET /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 Solana and Ethereum works the same way as for any caller: POST /bridge/quote with an ownership proof for both wallets, sign and broadcast the returned transaction yourself, then poll GET /bridge/{bridge_quote_id}/status.

Routing choices​

By default Treasures routes each trade automatically and relayed orders on Ethereum, Robinhood Chain and Base cost the wallet no gas. 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 before turning it on for end users. 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.

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.

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 covers setting it, reconciling it and claiming it.

Where to go next​