# TickerSpring agent API

> Read-only data, backtests and unsigned transaction bundles for AI agents on Robinhood Chain (chain id 4663). The API never holds keys, never signs and never sends a transaction.

Products agents can use:
- TickerSpring vaults (merged, Up and Stock Token families): deposit USDG, the vault provides liquidity in a range and harvests trading fees; withdraw in USDG, in kind, or through a queue. Every vault is listed with its status (open, full, closed or paused) and the reason; a deposit into a full or closed one is refused with 422 and that reason.
- Limit Orders: single orders and ladders (2-20 orders) on the Limit Orders hook. The hook takes a commission on fills.
- Grid Strategies: a repeating buy line and sell line on the strategy contract.
- Ladder strategies: 1-16 parts on one strategy market, each its own buy line and sell line, opened together after one approval (listed at /v1/agent/products only while they are offered). Not the same as a Limit Orders ladder.
- Swaps: any token for any token through KyberSwap, on the site's own swap router (0.1% swap fee, taken from the output), paid to the signing wallet.
- Baskets: Balancer V3 weighted pools on TickerSpring's own deployment, several tokens at set weights held as one basket token (18 decimals); holders earn the basket's swap fee. Bought and sold through BasketZap (no TickerSpring fee), which trades each token through KyberSwap and joins or exits in proportion.
Not offered: lending, retired vaults.

Amounts are decimal strings; USDG has 6 decimals and vault shares 12 (Stock Token vault shares 18). Addresses are checksummed. Successes answer {"data": ...}; errors answer {"error", "code"} (404 NOT_AGENT_VAULT for any vault agents may not use).

## Read
- [Products](/v1/agent/products): what is available now, the hook and strategy addresses, fees and pauses, and how many baskets are listed.
- [Vaults](/v1/agent/vaults): every agent vault with its family, status and reason, APR, TVL, range, deposit limits, withdrawal modes and fee.
- [Tokens](/v1/tokens?q=&category=&sort=volume): every token TickerSpring charts, busiest first, with price, 24-hour volume, liquidity, category (stock, utility, meme, other), verified (on TickerSpring's own list) and whether its limit-order and grid markets are open (the first order or grid opens one). Limit orders, ladders and grids take any of them by address; an unverified token's symbol is its own, so check the address.
- Vault detail: /v1/agent/vaults/{vault}, with /prices and /earnings.
- Positions: /v1/agent/accounts/{owner} returns a wallet's vault shares, pending deposits, queued withdrawals, limit orders, grids, ladder strategies and basket tokens.
- Baskets: /v1/baskets lists the verified baskets (tokens and weights, TVL, share price, fee APR, 7-day change); /v1/baskets/{pool} one basket (any live one, also a user's unverified one: check its listed and maker fields), /v1/baskets/{pool}/history?days=, /v1/baskets/{pool}/account/{owner} (the holding and fees earned).
- What changed: /v1/agent/accounts/{owner}/activity?cursor= returns {cursor, since, now, changes}. Call it once without a cursor for a baseline, then pass the cursor you got back. Changes include vault share moves, deposit requests settled, refunded or cancelled, queued withdrawals completed or cancelled, orders placed, filled, claimable or closed, grids opened, traded or closed, and ladder strategies opened, traded, with a part finished, or closed, and basket balances that moved. Cursors last 14 days.

## Backtests (estimates, not quotes)
- POST /v1/agent/backtest/grid {token, buyPrice, sellPrice, amountUsd, repeat, days <= 90}: trades, round trips, fees, profit and end value.
- POST /v1/agent/backtest/ladder {token, side, levels: [{price, amountUsd}] (1-20), days}: fills per level.
- GET /v1/agent/ranges?token=&days=: the grid lines that would have made the most round trips or profit.
- Every route is free right now.

## Grid planner (walk-forward, free)
- GET /v1/agent/grid/tokens?limit=&category=&include=: the latest grid scan of every charted token at the live strategy fee: tokens that keep trading a range, good then weak with their reasons, each with today's lines (prepare_grid's buyPrice, sellPrice, amountUsdg) and its weekly results on weeks it never saw.
- GET /v1/agent/grid/plan?token=&amountUsd=&gap=&days=: one token planned now: today's lines, a tighter and a wider choice, the verdict (good, weak or none, with reasons) and the average and worst week.
- GET /v1/agent/ladder/tokens?limit=&include=: the dip ladder (5 buys 10% apart, each selling at +50% after fees) on the scanned tokens, good first: each token's record ($500 started at any midnight in the last 30 days, held a week), today's lines and warnings.
- GET /v1/agent/ladder/plan?token=&amountUsd=: one token's dip ladder now: record, verdict, today's lines and the exact prepares.

## Strategy Finder (past results, walk-forward)
- GET /v1/strategy-finder?budget=&period=&token=&category=&strategy=: how strategies and today's vaults would have done over the last N days (period=Nd, 1d to 30d, 7d by default; 2d, 7d, 14d and 30d are the chips; strategy=vault for vaults), each strategy run from the window's start to now with its standard settings and real fees, a vault as a $500 deposit at the start and its value now after its fees, each beside what just holding the token did (holdReturnPct, holdPnlUsd; no fees); ranked by the window's result, at most 2 per token and 6 per style, each with the chip windows and the one asked for, a walk-forward test on unseen days, run parameters for the prepare routes, the relative shape (dip grids and ladder strategies), next steps and the live track record of the board's past picks. strategy=vault lists every vault with a result, best first. When the slice asked for has nothing positive it widens (the same style on other tokens, other styles, then the best vault by current yield) and says so; when nothing has the window yet it shows the longest shorter one that has results.
- GET /v1/strategy-finder/{token}?period=Nd: every style for one token with the chip windows and the one asked for, each walk-forward start's result and the latest start's trades. GET /v1/strategy-finder/track-record: how the board's daily picks did, followed on paper for 7 days each.
- POST /v1/strategy-finder/backtest {token, strategy, variant? | settings?, budgetUsd?, days? (21-60 days of history), period? (Nd, the window shown beside the chips), identity?}: any token on demand, walk-forward or fixed settings (a published shape too). Every run is logged; GET /v1/strategy-finder/attempts?kind=wallet&value= counts a wallet's runs made with its signed-in owner session.

## Acting
- POST /v1/agent/prepare/{kind} returns unsigned steps (to, data) and a sign link. Kinds: vault-deposit, vault-cancel-deposit, vault-withdraw, vault-cancel-withdraw, limit-order, ladder, order-action, grid, ladder-strategy, swap, basket-buy, basket-sell, basket-make. The vault routes take any agent vault and answer with its family's bundle kind (Up: up-vault-deposit, up-vault-withdraw, up-vault-cancel; Stock Token: stock-vault-deposit, stock-vault-withdraw).
- ladder-strategy {owner, action: open|close|setRepeat|collect, token, legs: [{buyPrice, sellPrice, amount}] (1-16), sellFirst?, repeat?, oneWay?, id?, mask?}: each part's buy price must sit below the price now (a sell-first part's sell price above it), and each part has an exact minimum the refusal names. Backtest the whole ladder with POST /v1/strategy-finder/backtest (strategy ladder-strategy), or each part with /v1/agent/backtest/grid.
- swap {owner, tokenIn, tokenOut, amount, slippageBps?}: tokens are our list's symbols (USDG, NVDA, …; ETH is native ETH, WETH the wrapped token) or addresses; amount is in tokenIn's units. GET /v1/agent/swap/quote?tokenIn=&tokenOut=&amount= first gives the expected and minimum output to repeat back. Swaps from native ETH aren't offered in a sign link (422 NATIVE_ETH_IN): swap from WETH.
- basket-buy {owner, basket (address or a listed symbol), amount, payWith? (USDG default, WETH or one of the basket's tokens), slippageBps?} and basket-sell {owner, basket, amount (basket tokens) | all: true, receive?, slippageBps?}: approve exactly the amount to BasketZap, then its buy or sell, paying the signing wallet at least the minimum. Not native ETH (422 NATIVE_ETH_IN): use WETH, or the basket's page. Sign within the zap's 10-minute deadline. A basket made by a user is unverified until TickerSpring lists it.
- basket-make {owner, name, symbol, tokens: [{token, weightPct}] (2-8, USDG or WETH among them, 100% in all), swapFeePct? (0.3 or 1, default 1), amount (the first deposit, worth at least $25), payWith? (USDG default, or WETH), slippageBps?}: approve exactly the deposit to BasketMaker, then one make that creates the basket, buys each token through KyberSwap and sends the basket tokens to the signing wallet; a deposit whose price impact is over 3% is refused (422 PRICE_IMPACT_TOO_HIGH). Check the mix first with POST /v1/agent/baskets/plan {tokens: [{token, weightPct?}], swapFeePct?, name?, symbol?}: each token's KyberSwap depth, a look-back simulated over past prices (past results, not a forecast), the name check. The name, symbol, tokens, weights and fee are permanent; a basket a user made is unverified until TickerSpring lists it.
- Nothing has been sent until the owner signs, either at the sign link on tickerspring.com or with their own wallet. Receivers and owners are always the signing wallet.
- Bundles expire after 10 minutes; prepare again rather than reusing old calldata.
- Each prepare answer (and GET /v1/agent/sign-requests/{id}) also has walletSendCalls: EIP-5792 wallet_sendCalls params (chainId 0x1237) with the calls in order. Use it with a wallet that supports EIP-5792 (for example viem sendCalls); otherwise send each call with eth_sendTransaction, approvals first, waiting for each receipt.

## Safety
- Give an agent its own wallet with a policy: [Privy policy](/v1/agent/policies/privy) or [Turnkey policies](/v1/agent/policies/turnkey) allow only these actions, only for the wallet itself.
- Vaults can lose value (price moves, impermanent loss); limit orders, grids and ladder strategies can fill at a loss after fees. Past backtests do not predict results.


## Report cards
- Every prepared bundle is filed before it runs, with the price read from the chain; mined transactions are matched to filings by owner, target and exact calldata; executed actions are graded a day later by fixed rules (7 days for deposits and switches).
- GET /v1/agent/report-card/{owner}?agent=: the executed and graded actions and each agent's numbers. No rates until 30 graded actions; a hit rate is the low end of its 90% range, with the raw counts.
- Pass agentTag (the tag your brief gives) in every prepare body: it groups your actions and grants nothing.
- Never-signed actions are on the owner's private view only (a signed sign-in: POST /v1/agent/report-card/session/challenge, then POST /v1/agent/report-card/session; GET /v1/agent/report-card/{owner}/private with the token).

## Optional
- [skill.md](/v1/agent/skill.md): instructions for AI agents (decision guide, confirmation rules, how to sign).
- [OpenAPI](/v1/agent/openapi.json)