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.0Read it first: it lists every token a swap on that chain can name.
| Field | What it is |
|---|---|
symbol, name, address, decimals | The token. ETH has no address. |
kind | money (USDC, USDG and ETH), stock or token (cbBTC, BNKR and others on Base). |
chainlinkFeed, priceFrom | Whether a Chainlink feed prices it and where its price comes from. |
inBoxes | Whether a mystery box pays it. |
priceUsd | Its price now, for showing: a plan reads its own when you ask for it. |
marketClosed | Set on a stock whose price is not usable right now. |
| Chain | Pairs |
|---|---|
| Base | A stock for USDC; a stock with a Chainlink feed also for ETH. USDC for ETH. A token for USDC or ETH. |
| Robinhood Chain | A stock token for USDG or ETH. USDG for ETH. |
| Between them | USDC 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" }| Field | Rule |
|---|---|
from, to | { chain, token }: token is a symbol from /tokens or its address. |
amount | A decimal string, in from's units. |
acceptPoolPriceBps | Your yes to a pool's own price (below), 0 to 1000. |
regularWallet | true: your yes that the wallet is a private key wallet, for a bridge. |
| Fee | Rate |
|---|---|
| A swap with a stock or a token in it | 1% |
| A swap of money only (USDC, USDG, ETH) | 0.75% |
| A bridge | 0.75% |
- A stock or token buy is $0.1 at least, a sale $0.05.
summary.to.minimumOutis the least you get, after the fee.summary.feenames the fee, its token and the fee wallet.summary.priceCheckshows 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": trueonly if it is a private key wallet. A wallet with contract code is refused withcontract_wallet. - Money lands on the other chain in seconds to minutes.
summary.route.statusis the link to follow it by its Relay request id. An order nobody fills is refunded to your wallet.
Refusals
| Code | Meaning |
|---|---|
| unknown_token, bad_token | Not a token traded on that chain: see /tokens. |
| same_token, stock_for_stock, token_pair, pool_priced | A pair that does not trade here. |
| not_bridgeable | Only money crosses chains. |
| too_small | Under 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_wallet | A bridge needs a regular wallet. |
| bridge_unavailable (503), bridge_refused (409) | Relay could not quote this bridge or its quote failed our checks. |
| insufficient_balance | Not enough of the token on that chain. |