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; see 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 covers what is in it and how to install it. The skill also sends the optional skill version headers 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. 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
• Choose the speed route on Robinhood Chain and Base when one-block settlement matters more than gasless execution
• Monitor trade and transaction status
• Bridge USDC between Solana and Ethereum
• View current holdings and trade history
• With an integrator key: look up company profiles, analyst views, earnings and news for a ticker, and price a trade with no wallet attached

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 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}: 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 and requests an executable quote from POST /public/v1/quote/buy. Adding priority: "speed" here opts into the speed route: 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, 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, which broadcasts them. 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 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}&eth_wallet={eth_wallet}.
• At any point, it can review past activity with GET /public/v1/trades?sol_wallet={sol_wallet}&eth_wallet={eth_wallet}.

Two optional detours sit off that path, both behind an integrator key. GET /public/v1/stocks/{ticker} returns the company profile, analyst view, earnings date and latest news behind a ticker, and POST /public/v1/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 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 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.