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 your wallet to your agent to act on behalf of you and then enabling the agent to call the relevant endpoints to query assets, get quotes and submit trades.

Channels of Access

There are two ways to give your agent access to Treasures:

• Via the Skills Document — the fastest way to get an agent working. Install the Treasures skills document at https://github.com/treasures-io/treasures-finance-agent-skills/ and your agent gets structured instructions for calling our API correctly.
• Direct API Integration. Call the Treasures REST API directly as documented in API Reference section.

What Your Agent Can Do

• Discover the list of available assets
• View current holdings and trade history
• Retrieve real-time prices and execution quotes
• Submit buy and sell trade requests
• Monitor trade and transaction status

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's how a typical buy comes together:

• The agent looks up the target asset with GET /public/v1/stocks/tickers and confirms it's available to trade.
• 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.
• It signs the returned trade payload and broadcasts it through POST /public/v1/trade/submit.
• 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 /portfolio?sol_wallet={sol_wallet}&eth_wallet={eth_wallet}.
• At any point, it can review past activity with GET /trades?sol_wallet={sol_wallet}&eth_wallet={eth_wallet}.

Monitoring Transaction Status

After submitting a trade, agents should poll the Check Transaction Status endpoint at reasonable intervals (we recommend every 2–5 seconds) until a terminal status (executed or failed) is returned. Avoid polling more frequently than once per second to stay within rate limits.