Skip to main content

Getting Started

This walkthrough buys a tokenized stock with USDC, end to end. It assumes you control a Solana and/or Ethereum wallet and hold USDC on at least one of them.

For AI agents​

If you're building an AI agent on Treasures, you don't have to wire these calls up by hand. We publish Agent Skills — folders of plain-Markdown instructions (SKILL.md) that a coding agent loads on demand and follows to call the API correctly.

The treasures-b2b-api skill teaches an agent the full flow — discovering tokenized stocks, quoting and executing trades, bridging USDC across Solana and Ethereum, and reading portfolio and trade history for a single end-user wallet pair — including the ownership-proof signing details and the footguns that are easy to get wrong.

Install with npx skills, which sets the skill up for 70+ coding agents (Claude Code, Codex, Cursor, Copilot, Windsurf, Cline, …) and auto-detects which ones you have:

npx skills add treasures-io/treasures-finance-agent-skills

Or, in Claude Code, install it from the plugin marketplace:

/plugin marketplace add treasures-io/treasures-finance-agent-skills
/plugin install treasures-finance-agent-skills@treasures-finance-agent-skills

The rest of this page walks through the same flow by hand — useful background whether you integrate directly or let an agent drive.

1. Discover what's tradable​

curl https://api.treasures.io/public/v1/stocks/tickers

Returns the catalog: each ticker, its available chains, and per-protocol listings (ondo / xstocks token addresses and share multipliers). This endpoint is cached server-side for 5 minutes and is cheap to poll.

For live prices, use GET /stocks (full enrichment, 30 s cache) or GET /stocks/prices?tickers=AAPL,NVDA (per-protocol prices for specific tickers).

2. Build an ownership proof​

Quoting requires proof that you control the wallets you quote for. Sign the canonical challenge with each wallet key and include the signatures plus an issued_at Unix timestamp:

{
  "ownership_proof": {
    "sol_signature": "<base64 Ed25519 signature>",
    "eth_signature": "0x<65-byte EIP-191 personal_sign signature>",
    "issued_at": 1765432100
  }
}

See the API reference for the challenge format and skew window.

3. Request a buy quote​

curl -X POST https://api.treasures.io/public/v1/quote/buy \
  -H 'Content-Type: application/json' \
  -d '{
    "ticker": "AAPL",
    "amount_usdc": "100.50",
    "max_slippage_bps": 100,
    "sol_wallet": "9aJ6jUyG7zG3yfPbsi5tFFqA1cnp7zCfL6pYfqyZP4qE",
    "ownership_proof": {
      "sol_signature": "...",
      "issued_at": 1765432100
    }
  }'

The response contains a quote_id, an expires_at timestamp, and up to two quote legs (one per chain, better-priced first). Each leg carries one or more signable_payloads:

  • solana_versioned_tx — a base64 unsigned Solana VersionedTransaction.
  • evm_eip712_typed_data — EIP-712 typed data for a gasless EVM order; sign with eth_signTypedData_v4.

4. Sign and submit — all legs together​

Every leg returned by the quote must be signed and submitted in a single POST /trade/submit call. Partial submits are rejected with 400 incomplete_submit.

curl -X POST https://api.treasures.io/public/v1/trade/submit \
  -H 'Content-Type: application/json' \
  -d '{
    "quote_id": "<quote_id from step 3>",
    "signed": [
      {
        "quote_index": 0,
        "signed_payloads": [
          { "type": "solana_versioned_tx", "signed_tx_base64": "<base64 signed tx>" }
        ]
      }
    ]
  }'

Submission is idempotent on (quote_id, quote_index) — a retry of an already-submitted leg returns 409 leg_already_submitted with the original tx_hash / order_hash.

If the quote expired between issue and submit you get 410 quote_stale — go back to step 3 and re-quote.

5. Poll status​

curl https://api.treasures.io/public/v1/quote/<quote_id>/status

Returns an aggregate_status (in_progress → completed / partial_failed / all_failed) plus per-leg detail (tx_hash, filled_shares, filled_usdc, …). This endpoint is public read-only — no ownership proof needed. In-progress aggregates are cached for 10 seconds, so poll at that cadence or slower.

6. Read your portfolio​

curl 'https://api.treasures.io/public/v1/portfolio?sol_wallet=9aJ6...P4qE'

Returns reconciled positions (on-chain truth, enriched with prices) and USDC balances per chain. Add source=internal to also populate cost-basis and unrealized P&L columns from your Treasures-executed trades.

Selling​

POST /quote/sell works the same way, except the planner may split the sale across multiple legs over your existing holdings (different chains/protocols). All returned legs must be signed and submitted together — the sale is all-or-nothing at submit time.