Tools reference

Generated from packages/tools (35 tools). Every surface (REST POST /api/v1/tools/:name, MCP, CLI talon tool <name>, and the agent runtime) calls these same implementations.

Risk levels: read never signs; write signs after policy + simulation; sensitive additionally requires user approval by default.

Identity and wallet

agent_get

Get the profile of the current agent: id, name, avatar, wallet address, chain id, status (active / paused / archived), model and provider, a plain-English summary of its spending policy (caps, allowed tokens, approval rules), and a block explorer link for the wallet. Use it to learn your own wallet address and what you are allowed to do before planning trades or transfers.

• Risk: read

No input.

wallet_balances

Get the agent wallet balances on Robinhood Chain: native ETH, USDG, WETH, curated stock tokens, every token the agent has traded or launched, plus any extra tokens you pass. Use it before any trade to check what you can spend. Each entry has amountRaw (base units), amount (human units), priceUsd, usdValue and kind (native / erc20 / stock); zero balances are hidden unless includeZero is true. Sorted by usdValue descending. totalUsd is the sum of priced balances.

• Risk: read

wallet_portfolio

Get the agent portfolio: everything wallet_balances returns plus curvePositions for Pons bonding-curve tokens still pre-graduation. Each curve position is valued by simulating a full sell on the curve (constant-product formula after the 1% curve fee and creator tax), so valueUsd reflects price impact, unlike the spot usdValue in balances. costBasisUsd is the net USD spent on confirmed buys minus sells recorded by TALON (null if the agent never traded it here), pnlUsd = valueUsd minus costBasisUsd, curveProgressBps is 0 to 10000 toward graduation. totalUsd counts curve positions at their sell value.

• Risk: read

wallet_history

List the agent recent transactions recorded by TALON (swaps, curve buys and sells, transfers, launches, approvals, fee claims), newest first. Use it to recall what you already did or to check whether a pending action confirmed. Each entry has action, status (pending / simulated / signed / sent / confirmed / failed / reverted), a one-line summary, tx hash and explorer link, usdValue, error text on failures, and createdAt. limit default 25, max 100; status filters to one status.

• Risk: read

pay_request

Fetch a URL and, if it costs money (HTTP 402 with x402 payment terms), pay for it in USDG from this agent's wallet, then return the response. Use it to buy data, API calls or other services a task needs. Set maxUsd to the most you will pay and purpose to a short reason (shown on the receipt). The owner's payment rules apply: payments must be turned on, stay under the per-payment and daily caps, go to allowed merchants, and larger ones wait for the owner's approval. Free URLs are fetched without paying. Returns the status, the response body (truncated to 20,000 characters), and for paid requests the amount, merchant and receipt.

• Risk: sensitive

payments_list

This agent's payments for services (x402 and other paid requests): totals by merchant and by day for the range (1d, 1w, 1m, all; default 1m), today's spend against the daily payment cap, and the most recent payments with their receipts.

• Risk: read

Market data

token_lookup

Look up a token on Robinhood Chain by address, "ETH", or symbol (USDG, WETH, a stock ticker such as NVDA, or a Pons launch symbol). Use it before trading or when the user mentions a token, to get its address, kind (pons bonding-curve launch, stock token, native ETH, or plain erc20), current price in USD and in its quote asset, market cap, liquidity, 1h/24h volume in USD, holder count, bonding-curve progress in basis points (0 to 10000, null once graduated), creator, launch and graduation timestamps, and explorer / Pons page links. Data comes from the indexer and falls back to live chain reads for unknown tokens.

• Risk: read | public (no agent needed)

token_price

Get the current price of a token with 1 hour and 24 hour percentage changes. Cheaper than token_lookup when you only need price. Returns priceUsd (USD per whole token), priceQuote (price in the quote asset, for example ETH per token on an ETH-quoted Pons curve), quoteSymbol, change1hPct and change24hPct (percent, null when the indexer has no sample that far back).

• Risk: read | public (no agent needed)

token_chart

Get OHLCV price candles for a token, built from the indexer price samples. Use it to describe recent price action or compute indicators. interval is one of 1m, 5m, 15m, 1h, 4h, 1d (default 5m); limit is the number of candles (default 200, max 1000). Returns candles newest first as { t (unix seconds, bucket start), o, h, l, c (USD per whole token), v (USD volume; exact only for 1h and coarser intervals, 0 for sub-hour candles) }. Gaps with no samples are omitted, not filled.

• Risk: read | public (no agent needed)

market_trending

List the most actively traded tokens on Robinhood Chain (Pons launches and graduated tokens) ranked by USD volume over the last 1h or 24h, plus the 10 most recent bonding-curve graduations. Use it to find what is moving right now. window: "1h" (default) or "24h"; limit default 20, max 50; includeGraduated (default true) set false to see only tokens still on their bonding curve. Each entry has the token_lookup shape (address, symbol, priceUsd, mcapUsd, vol1hUsd, vol24hUsd, holders, curveProgressBps, graduated, kind, links).

• Risk: read | public (no agent needed)

market_new_launches

List the newest token launches on Robinhood Chain, newest first. Use it to discover fresh bonding-curve tokens. Filters: limit (default 50, max 200); quote = "ETH", "USDG", "STOCK" (paired against a tokenized stock) or a quote asset address; minMcapUsd; creator (0x address of the deployer); launchedViaTalon (true to see only launches made through TALON agents). Each entry has the token_lookup shape; priceUsd and stats are null until the indexer has sampled the token.

• Risk: read | public (no agent needed)

stock_tokens_list

List tokenized stocks and ETFs tradable on Robinhood Chain (NVDA, AAPL, TSLA, SPY and roughly 190 more), with contract address, decimals, split/dividend multiplier and logo. Use it to find the address of a stock token before quoting or swapping. priceUsd (USD per token) and change24hPct come from the TALON price samples, with a live pool quote for curated names that have no sample yet; pass withPrices: ["SYMBOL", ...] to force a live quote. liquidity (measured every 30 minutes) gives the price impact of a $1,000 and $10,000 buy and a grade: deep, good, thin or very_thin. Prefer deep or good names for portfolios. refresh: true bypasses the 1 hour registry cache. source is "registry" when the live Robinhood asset registry was used, "curated" when it was unreachable and only the built-in list is returned.

• Risk: read | public (no agent needed)

stock_market_status

Whether the US stock market (NYSE / Nasdaq) is open right now, the session (regular, pre_market, after_hours, closed), why it is closed (weekend, holiday, overnight) and the next open time. Stock Tokens trade on-chain 24/7, but their reference price only moves while the US market is open: when it is closed, quote prices may be stale and can gap at the next open. Check this before trading Stock Tokens and tell the user when the market is closed.

• Risk: read | public (no agent needed)

No input.

stock_liquidity

How much it costs to buy a Stock Token with USDG at several trade sizes (default $100, $1,000, $10,000): price impact in percent including the 0.3% pool fee. Liquidity differs a lot between stocks (NVDA, AAPL, SPY are deep; some ETFs are thin), so check it before any trade above a few hundred dollars and prefer smaller trades when impact passes about 1%. A size that cannot be filled is reported as unavailable.

• Risk: read | public (no agent needed)

Trading

swap_quote

Quote a Uniswap v4 exact-input swap on Robinhood Chain without executing it. Finds the best available pool (direct, or two-hop via ETH or USDG), returns expected output, minimum output after slippage, price impact, route and USD value. Use before swap_execute.

• Risk: read

swap_execute

Execute a Uniswap v4 exact-input swap through the Universal Router. Quotes first, applies slippage, checks policy, simulates, signs and sends. ERC-20 inputs must already be approved via approve_token with spender=universal_router (this tool never chains approvals). Returns tx hash and realised output.

• Risk: write

curve_quote

Quote a buy or sell on a pre-graduation Pons bonding curve without executing. For buy, amount is in the quote asset; for sell, amount is in tokens. Returns expected output, fees, USD value and curve progress.

• Risk: read

curve_buy

Buy a pre-graduation Pons token on its bonding curve. amountIn is in the quote asset (ETH for ETH-quoted launches, otherwise USDG or the stock token). For ERC-20 quotes the curve must be approved first via approve_token with spender=curve. Returns tx hash, tokens received and curve progress.

• Risk: write

curve_sell

Sell a pre-graduation Pons token back to its bonding curve for the quote asset. The curve must be approved to spend the token first via approve_token with spender=curve. Returns tx hash and quote received.

• Risk: write

approve_token

Grant a spender permission to move an ERC-20 held by the agent. spender=universal_router performs the two-step Permit2 pattern (ERC-20 approve to Permit2, then Permit2.approve to the router for 30 days), sending only the steps that are missing. spender=curve resolves the Pons bonding curve for the token. Amount defaults to unlimited ("max"). Returns the approval tx hashes, or alreadyApproved when nothing was needed.

• Risk: write

wallet_transfer

Send ETH or an ERC-20 from the agent wallet to an address. Subject to the policy transfer whitelist and, by default, human approval. Returns the tx hash.

• Risk: sensitive

portfolio_set

Create or replace this agent's Stock Token portfolio: target weights in percent that add up to 100 (use USDG for a cash share, e.g. NVDA 40, SPY 40, USDG 20), plus how to keep them. driftThresholdPct (default 5) is how far an asset may drift before a rebalance; minTradeUsd (default 1) skips tiny trades; maxImpactPct (default 1) caps price impact per trade; autoRebalance (default false) lets TALON rebalance on a schedule; tradeWhenMarketClosed (default false) allows automatic rebalances while the US market is closed. recurringBuy { amountUsd, everyDays } (null turns it off) adds amountUsd to the portfolio every everyDays days at the US market open, from USDG waiting in the agent wallet, invested to the targets: dollar-cost averaging. While it is on, cash beyond the portfolio's cash share waits for those buys instead of being invested at once. The owner funds the agent; the agent never pulls money from the owner. Only Stock Tokens and USDG are accepted. This changes settings only, it does not trade: call portfolio_rebalance to act. Confirm the targets with the user before setting them.

• Risk: write

portfolio_get

This agent's Stock Token portfolio: target weights, current value and weight of each holding, drift from target, whether a rebalance is needed and the trades it would make, the rebalancing settings, the last rebalance result, the recurring buy (amount, interval, next buy, cash waiting for it), the US market status, and funding: spare ETH beyond a gas reserve. When the portfolio has little USDG but spare ETH, offer to swap that ETH to USDG (swap_execute) before rebalancing. Returns portfolio: null when no targets are set yet (use portfolio_set).

• Risk: read

No input.

portfolio_rebalance

Bring this agent's Stock Token portfolio back to its target weights. Sells overweight holdings into USDG first, then buys underweight ones; each trade is shrunk to stay within the portfolio's price-impact cap (or skipped when liquidity is too thin) and goes through the agent's policy, so trades above the owner's limits wait for approval. Does nothing when every asset is within the drift threshold unless force is true. dryRun returns the plan without trading. onlyWhenMarketOpen skips the run while the US market is closed. Report the trades and any skipped or approval-pending ones to the user.

• Risk: write

portfolio_performance

How this agent's Stock Token portfolio (every Stock Token and USDG in its wallet) has done: value now against money put in (deposits minus withdrawals), the gain or loss, and for the chosen range (1w, 1m, 3m, 1y, all; default 1m) the money added, the change from prices and trading, and the return excluding deposits. Includes chart points and recent shareable reports. Tracking starts with the first snapshot; the worker records one every hour. Use it when the owner asks how the portfolio or recurring buys are doing.

• Risk: read

portfolio_share

Creates a shareable performance report for this agent's Stock Token portfolio over the last days days (default 7, or since tracking began): value, money put in, return excluding deposits, holdings and trades, with links to each trade's receipt. Returns the report path (/w/<id>) on the TALON site; anyone with the link can view it, so only create one when the owner asks to share. Sends no transaction.

• Risk: write

Launch and earn

launch_quote

Preview the cost and economics of launching a token on Pons V2 before calling launch_token. Returns the launch fee, optional initial buy, estimated gas, totals in ETH and USD, the fee splitter address that will receive creator fees (75% to the agent, 25% to TALON), the graduation threshold and phantom liquidity for the chosen quote asset, and the fixed supply. Nothing is sent on-chain.

• Risk: read | public (no agent needed)

launch_token

Launch a new token on Pons V2 (Robinhood Chain) with a bonding curve that graduates into a locked Uniswap v4 pool. Creator fees are routed to a TALON FeeSplitter (75% to this agent, 25% to the platform), deployed on first use. Pays the Pons launch fee (0.0005 ETH) plus an optional initial buy in the same transaction. Provide imageUrl (already hosted) or imageBase64 (pinned to IPFS when the server has PINATA_JWT). Requires policy approval when the policy says launches need sign-off; call launch_quote first to preview the cost.

• Risk: sensitive

earnings_get

Creator fee earnings for this agent across every token it launched through TALON. Shows, per fee asset (ETH, USDG, ...), what is sitting in the fee splitter ready to claim (75% agent / 25% platform), what Pons has accrued but not yet pushed to the splitter, what was already claimed, and USD totals. Optionally filter by one fee asset.

• Risk: read

earnings_claim

Push accrued creator fees out of this agent's fee splitter: 75% to the agent wallet and 25% to the TALON treasury. Without a token it claims every fee asset with a balance in one transaction (claimMany); with a token it claims just that asset. Recipients are fixed on-chain, so this needs no policy approval, only gas.

• Risk: write

Automation

automation_create

Create a scheduled strategy run by the TALON worker: kind "dca" (buy a USD amount of a token with ETH every N hours) or "limit" (buy or sell once when the token USD price crosses a level). The eventual trade is checked against the policy now so a disallowed strategy fails immediately; approval routing still applies at execution time. Returns the automation row.

• Risk: write | coming soon (switch: automations)

automation_list

List this agent's automations (DCA and limit orders), optionally filtered by status.

• Risk: read | coming soon (switch: automations)

automation_cancel

Cancel an automation so the worker stops running it.

• Risk: write | coming soon (switch: automations)

Control (user side only)

approval_list

List human-in-the-loop approval requests. Scoped to one agent when agentId is given, otherwise to every agent of the authenticated user. Defaults to pending requests. Owner-only: the agent runtime cannot call this.

• Risk: read | public (no agent needed) | not exposed to the agent

approval_resolve

Approve or deny a pending approval request. Approving re-executes the original tool call for that agent with the approval attached, so the transaction pipeline skips policy routing and records the approval as executed once the tx confirms. Denying only records the decision. Expired requests are marked expired and rejected. Owner-only.

• Risk: sensitive | public (no agent needed) | not exposed to the agent