Agent API

Swap and bridge

Trade stocks and tokens and move money between chains.

One endpoint trades on one chain and bridges between the two: if from and to are on the same chain it is a swap, otherwise a bridge. It trades the pairs the Swap tab trades, by the same routes and at the same fees. What comes out always goes to your wallet. For the trades themselves in plain words, see Trading and Bridging.

What trades

GET /tokens?chain=base|robinhood&skill=1.3.0

GET https://www.giftedstock.com/api/agent/v1/tokens?chain=base&skill=1.3.0

Read it first: it lists every token a swap on that chain can name.

FieldWhat it is
symbol, name, address, decimalsThe token. ETH has no address.
kindmoney (USDC, USDG and ETH), stock or token (cbBTC, BNKR and others on Base).
chainlinkFeed, priceFromWhether a Chainlink feed prices it and where its price comes from.
inBoxesWhether a mystery box pays it.
priceUsdIts price now, for showing: a plan reads its own when you ask for it.
marketClosedSet on a stock whose price is not usable right now.
ChainPairs
BaseA stock for USDC; a stock with a Chainlink feed also for ETH. USDC for ETH. A token for USDC or ETH.
Robinhood ChainA stock token for USDG or ETH. USDG for ETH.
Between themUSDC or ETH on Base for USDG or ETH on Robinhood Chain and back. Stocks never cross chains.

A stock never swaps for another stock: sell it for money first. Index tokens (AI12, MAG7) do not trade here: the refusal, bankr_only, links to where they do.

Swap or bridge

POST /tx/swap

{ "wallet": "0xYou", "skill": "1.3.0", "from": { "chain": "base", "token": "USDC" }, "to": { "chain": "base", "token": "NVDAc" }, "amount": "2" }
FieldRule
from, to{ chain, token }: token is a symbol from /tokens or its address.
amountA decimal string, in from's units.
acceptPoolPriceBpsYour yes to a pool's own price (below), 0 to 1000.
regularWallettrue: your yes that the wallet is a private key wallet, for a bridge.
FeeRate
A swap with a stock or a token in it1%
A swap of money only (USDC, USDG, ETH)0.75%
A bridge0.75%
  • A stock or token buy is $0.1 at least, a sale $0.05.
  • summary.to.minimumOut is the least you get, after the fee. summary.fee names the fee, its token and the fee wallet. summary.priceCheck shows the quote held against Chainlink's price where there is one; a pool too far off it is refused.
  • Base swaps go through Aerodrome's or Aero's router, whichever pays more; a token through Aero's router or Uniswap's SwapRouter02. Robinhood Chain swaps go through Uniswap's router.
  • On Base an exact approval to the router comes first when needed. On Robinhood Chain a token paid in is approved through Permit2: an exact approval to Permit2, then Permit2's own exact approval for the router, then the swap.
  • A swap plan lasts 10 minutes and the router refuses it after. A bridge lasts 3 minutes: Relay's quote is a price of the moment.

Prices with no outside check

A Base stock with no Chainlink feed trades at what its pool pays, as every token does, with no outside price to check it against. The first answer is confirm_pool_price (409), with how far your size moves the pool. Only with your user's yes, send the same request with acceptPoolPriceBps at least that figure. Past 10% it is refused with pool_too_thin: lower the amount.

Bridges

  • Bridges go through Relay. A bridge needs a regular wallet: a smart contract wallet's address on one chain is not its own on the other.
  • A wallet that has sent nothing on the source chain yet gets confirm_regular_wallet (409). Send "regularWallet": true only if it is a private key wallet. A wallet with contract code is refused with contract_wallet.
  • Money lands on the other chain in seconds to minutes. summary.route.status is the link to follow it by its Relay request id. An order nobody fills is refunded to your wallet.

Refusals

CodeMeaning
unknown_token, bad_tokenNot a token traded on that chain: see /tokens.
same_token, stock_for_stock, token_pair, pool_pricedA pair that does not trade here.
not_bridgeableOnly money crosses chains.
too_smallUnder the minimum buy or sale.
confirm_pool_price, pool_too_thin (409)A pool's own price: confirm it or trade less.
price_off, no_market (409)The market is too far from the reference price or has no pool right now.
no_price (503)No recent price: try again later.
would_fail (409)The swap would fail onchain right now.
confirm_regular_wallet (409), contract_walletA bridge needs a regular wallet.
bridge_unavailable (503), bridge_refused (409)Relay could not quote this bridge or its quote failed our checks.
insufficient_balanceNot enough of the token on that chain.
A swap is one call that carries others. What may sit inside it, call by call, is in SKILL.md and checked by verify.mjs.