Documentation
How TernAgent works
TernAgent is a market-aware execution agent for Robinhood Chain (chain ID 4663). You give it a bounded instruction, called a mission. It checks live market conditions against your limits on a schedule, tells you whether it would act, wait or cancel and why, and prepares a transaction only for you to approve in your own wallet.
It is an independent application. It is not affiliated with, endorsed by, or operated by Robinhood, and it has nothing to do with a Robinhood brokerage account: it works with wallets and contracts on the chain.
On this page
- What TernAgent supports today
- How missions work
- ACT, WAIT and CANCEL
- Reason codes
- Manual wallet approval
- Quotes and their limits
- Simulation versus real transactions
- Shadow runs
- Portfolio coverage
- Monitoring requirements
- Integrations needed for execution
- Pausing and cancelling
- Decision receipts
- Reference missions
- The optional language assistant
- Stock Tokens
- Accounts and data safety
- What is not built
- The $TERN token
What TernAgent supports today
- One network: Robinhood Chain mainnet, chain ID 4663. Signing is blocked while a wallet is on any other network.
- 38 verified assets: ETH, WETH, USDG and 35 Robinhood Stock Tokens. Each is bound to the chain ID and one contract address. The registry was last verified on 2026-11-18.
- Two execution venues: Uniswap v3 (direct pool) and KyberSwap aggregator. A mission swaps one asset for another through one of them.
- One execution mode: manual wallet approval. There is no automated signing.
- Shadow runs: missions that only record what the checks would decide.
- Decision receipts for every evaluation, with filtering and JSON export.
The Settings page shows the real state of every integration on the deployment you are using. Whatever it says there takes precedence over this page.
How missions work
A mission is a single swap with limits it will not cross:
- Input and output asset, chosen from the verified registry.
- Maximum input amount. A prepared transaction spends exactly this amount, never more.
- Minimum output, or a limit price. A limit price is converted to a minimum output in exact units when the mission is saved, rounded so the bound is never looser than what you typed.
- Maximum slippage (0.01% to 5%). The transaction enforces the higher of your minimum output and the quote less this tolerance.
- Maximum network fee, in ETH (the gas asset of the chain), not in gwei or dollars.
- Maximum quote age (5 to 300 seconds).
- Allowed venue, or any verified venue.
- Deadline, up to 30 days ahead, and a check interval (30 to 3600 seconds).
- Optional: a price-impact ceiling, and for Stock Tokens a rule to act only during the US regular trading session.
A mission’s limits are fixed when it is saved. To change them, cancel it and create a new one. That way every receipt of a mission refers to the same bounds.
Lifecycle
DRAFT → MONITORING → AWAITING_APPROVAL → SUBMITTED → CONFIRMED
↕ PAUSED ↘ FAILED
any open state → CANCELLED (by you) or EXPIRED (deadline)A lifecycle state says where the mission stands. A decision describes one moment. They are stored separately: a mission can be MONITORING with a WAIT decision, or AWAITING_APPROVAL because its last decision was ACT.
ACT, WAIT and CANCEL
- ACT: every required check passed. In manual mode the mission moves to “awaiting wallet approval”. ACT never means a transaction was submitted.
- WAIT: at least one check failed for a temporary reason, or the data it needs was missing. The mission stays open and is checked again on its interval.
- CANCEL: the mission expired, was cancelled, or names a network, asset or venue that is not supported. Terminal.
The decision is made by a deterministic policy engine (version tern-policy/1.0.0). Given the same limits, the same observations and the same time, it always returns the same checks, the same reason codes in the same order, and the same decision. It has four rules it never bends:
- Missing data never passes. A required check without its observation blocks ACT.
- Limits are compared as integers in each asset’s smallest unit. No floating-point arithmetic touches an amount.
- Only an executable quote is compared against a price or output limit.
- A language model, if one is configured, is never asked whether a limit passed.
Checks
Correct network, mission not expired, mission being monitored, supported assets, allowed venue, asset transfers enabled (Stock Tokens), executable quote available, quote fresh enough, input within your maximum, output meets your minimum, price impact (if you set a limit), network fee within your limit, balance sufficient, approval requirement known, market-session rule (if set).
Reason codes
“Wait With Reason” means a waiting mission always names what it is waiting for. Temporary reasons:
| Code | Meaning | What the mission waits for |
|---|---|---|
MISSION_NOT_MONITORING | The mission is not being monitored right now. | Resume monitoring to check its limits again. |
CHAIN_DATA_UNAVAILABLE | The network could not be read. | Waiting for the RPC endpoint to answer before checking your limits again. |
RPC_CHAIN_MISMATCH | The configured RPC endpoint reports a different chain ID than Robinhood Chain. | Waiting until the endpoint configuration is corrected. Nothing can be signed meanwhile. |
CHAIN_HEAD_STALE | The newest block the endpoint returned is too old to treat as current. | Waiting for a current block before checking your limits again. |
VENUE_UNAVAILABLE | The selected venue could not be reached or is not configured. | Waiting for the venue to answer before checking your limits again. |
ASSET_PAUSED | The issuer has paused transfers of an asset in this mission. | Waiting for the issuer to lift the pause. |
ASSET_STATUS_UNAVAILABLE | The transfer status of a Stock Token could not be read. | Waiting for the token contract to answer before checking your limits again. |
NO_EXECUTABLE_ROUTE | The venue has no executable route for this pair and amount right now. | Waiting for a route to become available. |
QUOTE_UNAVAILABLE | An executable quote could not be obtained. | Waiting for a fresh quote before checking your limits again. |
QUOTE_STALE | The executable quote has expired. | Waiting for a fresh quote before checking your limits again. |
AMOUNT_EXCEEDS_BOUND | The quoted input amount is larger than the mission allows. | Waiting for a quote for the exact mission amount. |
OUTPUT_BELOW_MINIMUM | The executable quote returns less than your minimum output. | Waiting for the price to meet your limit. |
PRICE_IMPACT_ABOVE_LIMIT | The estimated price impact of this trade is above your limit. | Waiting for deeper liquidity or a smaller impact. |
PRICE_IMPACT_UNAVAILABLE | You set a price-impact limit, but the venue supplied no estimate for this quote. | Waiting for a quote that includes a price-impact estimate. |
GAS_ABOVE_LIMIT | The estimated network fee is above your maximum. | Waiting for the fee to fall within your limit. |
GAS_ESTIMATE_UNAVAILABLE | The network fee could not be estimated. | Waiting for a fee estimate before checking your limits again. |
TRANSACTION_CHECK_FAILED | The transaction built for this quote did not pass its pre-signing check or its simulation on the network. | Waiting for a fresh quote before building it again. |
INSUFFICIENT_BALANCE | The wallet does not hold enough of the input asset, or enough ETH for the network fee. | Waiting until the wallet holds the required balance. |
BALANCE_UNAVAILABLE | The wallet balance could not be read. | Waiting for the balance to be readable before checking your limits again. |
ALLOWANCE_UNAVAILABLE | The token allowance could not be read, so the approval requirement is unknown. | Waiting for the allowance to be readable before checking your limits again. |
MARKET_SESSION_CLOSED | The underlying US market is not in its regular session, and this mission only acts during it. | Waiting for the next regular session. |
SESSION_DATA_UNAVAILABLE | This mission has a market-session rule, but no verified calendar covers the current date. | Waiting until calendar data is available. Remove the session rule in a new mission to act without it. |
Terminal reasons:
| Code | Meaning | What happens |
|---|---|---|
MISSION_EXPIRED | The mission reached its deadline before its conditions were met. | Create a new mission if you still want this action. |
MISSION_CANCELLED | The mission was cancelled by its owner. | No further evaluations will run. |
MISSION_CLOSED | The mission already reached a final state. | No further evaluations will run. |
UNSUPPORTED_NETWORK | The mission names a network TernAgent does not support. | Create the mission for Robinhood Chain. |
UNSUPPORTED_ASSET | An asset in this mission is not in the verified asset registry for this network. | Create a new mission with supported assets. |
UNSUPPORTED_VENUE | The mission names a venue that has no verified integration. | Create a new mission with a supported venue. |
Manual wallet approval
Nothing is sent without your approval in your own wallet. When you ask to prepare a transaction, the server:
- requests a fresh quote and re-runs every rule;
- validates the transaction it built: the destination must be a verified router, the token approval’s spender must be that router, the recipient must be you, and the amounts, assets, chain ID and value must match the mission;
- simulates it on the real network with
eth_estimateGasfrom your address, and checks the simulated fee against your limit; - shows you the expected input, expected output, minimum received, fees, approval and recipient.
Your browser then runs the same validation again on the exact bytes before your wallet is asked for anything.
If the input is a token and the router is not yet approved, the approval is a separate action, for exactly the mission’s input amount, never unlimited. After it confirms, the quote and every rule are checked again before the swap is prepared, because the market may have moved.
A prepared transaction is valid until the quote it came from reaches your quote-age limit (and never longer than 90 seconds). After that a fresh check is required.
The app tracks what happens next: declined in the wallet, submitted, pending, confirmed, reverted, or not found on the network (dropped or replaced). A hash reported by the browser is read from the chain and attached only if it is exactly the prepared transaction.
Quotes and their limits
Three kinds of price appear in the app and they are never interchangeable:
- Reference price: a Chainlink Data Feed value read on chain. An oracle value updates when the price moves by a threshold or when its heartbeat elapses, so it can be minutes or hours old. Stock Token feeds update on weekdays only. It cannot be traded.
- Indicative price: a Uniswap v3 pool’s current mid price applied to your amount, ignoring the pool fee and how much the trade itself would move the price. It cannot be traded at that number.
- Executable quote: what a venue would return for your exact amount at the moment it was asked. Missions are checked only against this.
An executable quote is still only a reading. Between the quote and the block your transaction lands in, the price can move. That is what the minimum-received amount in the transaction is for: if the price moves past it, the transaction reverts instead of filling at a worse price. A revert still costs the network fee.
Price impact is shown only when a venue supplies enough to state it. Uniswap v3 quotes include the pool price before and after the swap. KyberSwap does not supply a price-impact figure, so none is shown for it, and a mission with a price-impact limit prefers a venue that does.
TernAgent does not compute a “liquidity score”. It shows the executable output, the gap to the reference price, and whether a route exists.
Simulation versus real transactions
- A simulation (
eth_estimateGas, or a quoter call) runs the transaction against the chain’s state at that moment without sending it. It shows that the transaction would have succeeded then, and what it would have cost. - A real transaction is signed by your wallet, broadcast, and included in a later block, against whatever the state is then.
A passing simulation and a fresh quote reduce avoidable failures. They cannot guarantee the final result, a price, or a return.
Shadow runs
A shadow run is a mission in evaluation-only mode. It records real quotes, whether your rules would have passed, and the costs estimated at that time. It lists what it assumed instead of checked (that the wallet holds the balance, that the approval exists).
It never prepares or sends a transaction, never claims a fill, and is not a backtest: it observes the present from the moment you start it. A “would act” on a shadow receipt is not a realised result and says nothing about profit or loss.
Portfolio coverage
Balances are read from the chain for the verified registry only: ETH and 37 tokens. A token that is not in the registry is never discovered or shown, so the balances view is not a full inventory of a wallet. Each reading shows the block it was read at and its age, and is refreshed only when you press Refresh. Values use reference prices, which are not prices you can sell at.
Monitoring requirements
Missions and receipts are stored in PostgreSQL. Evaluations run in one of three ways, and the app always says which:
- A background worker (
pnpm worker): a long-running process next to the web app. Missions are evaluated on their interval whether or not a browser is open. - A scheduler calling
/api/cron/tickwith the deployment’s secret. Missions are evaluated on that schedule and no more often, so a 15-minute schedule means 15-minute checks whatever a mission’s interval says. - An open mission page. Whenever no worker process is running, a mission’s page also evaluates it on the mission’s own interval while the page is open and visible. That stops when you close the tab. It is not 24/7 monitoring, and the page says so.
Each mission is evaluated under a lease so two evaluations never overlap, at most once per interval however many workers run, with retries that back off up to 15 minutes after failures. The worker’s last heartbeat and last pass are shown in the app.
Integrations needed for execution
- An RPC endpoint for chain ID 4663. The official public endpoint works but is rate-limited; a provider endpoint in
ROBINHOOD_RPC_URLis recommended. The server checks the endpoint’s chain ID before using anything it returns. - A database (
DATABASE_URL) for accounts, missions, receipts and prepared-transaction records. - A verified venue. Both are on by default:
- Uniswap v3 (direct pool): router
0xCaf681a66D020601342297493863E78C959E5cb2. Listed for chain 4663 in the official Uniswap deployments registry; code confirmed on chain. - KyberSwap aggregator: router
0x6131B5fae19EA4f9D964eAc0408E4408b66337b5. Router named by KyberSwap’s API for chain slug "robinhood"; source on Sourcify: exact match.
- Uniswap v3 (direct pool): router
- A browser wallet on Robinhood Chain, holding the input asset and some ETH for the network fee.
Without the database, market conditions and balances still work, and missions are unavailable. Without a venue, monitoring and receipts still work, and swaps through it are disabled with the reason shown.
Pausing and cancelling
- Pause stops evaluations until you resume. A paused mission still expires at its deadline.
- Cancel ends the mission. No further evaluations run, and anything prepared but not signed is withdrawn.
Neither can undo what is already on chain. A transaction your wallet has broadcast will confirm or fail on its own, which is why a mission with a submitted transaction cannot be cancelled in the app. A token approval you granted stays in place until you revoke it from your wallet; approvals are for the exact mission amount, so a completed swap uses it up.
Decision receipts
Every evaluation writes one receipt: mission ID and owner, evaluation time, policy version, the limits in force, every source with its timestamp, a summary of the quote, each check with its outcome and reason code, the decision, and a transaction hash only when your wallet really broadcast one.
Receipts are application records in TernAgent’s database. They are not on-chain evidence and they are not cryptographically signed or proven. The on-chain evidence is the transaction itself, which you can verify on the block explorer. Exports never contain API keys, signatures or calldata.
Reference missions
The home page shows real decisions without asking you to connect a wallet. They come from 3 reference missions that the operator of this site runs: ordinary stored missions, built by the same validation as yours, evaluated by the same monitor, and recorded as ordinary receipts.
- 250 USDG → WETH: Buys WETH unless the executable output falls more than 0.75% under what the reference prices implied when the mission was opened.
- 0.1 WETH → USDG: Sells WETH only once the executable output is at least 0.4% above what the reference prices implied when the mission was opened. It waits until the market has moved that far.
- 50 USDG → NVDA: Buys the NVDA Stock Token only during the US regular trading session, and only if the executable output is within 1.5% of what the reference prices implied when the mission was opened.
- Their owner is the zero address (
0x000000…). No wallet is behind it, nobody can sign in as it, and they are shadow runs, so no transaction can ever be prepared for them. - A mission’s limits cannot be edited. So that the examples stay meaningful, each reference mission is closed and reopened every 24 hours, with its minimum output set once from the Chainlink reference prices at that moment. Each receipt states the limit that was in force.
- They are checked every 5 minutes when a background worker runs, and on each scheduler pass otherwise. Closed reference missions and their receipts are deleted after 7 days.
- They are the only missions readable without a session:
/api/referencelists them and/api/reference/receipts/<id>returns one receipt. The live reading at the top of the home page, and the “check against live quotes” button of the mission preview, are fresh evaluations that are shown and not stored.
The optional language assistant
If the deployment has a language-model provider configured, the mission builder can turn one sentence into a draft of the form. The structured form is fully functional without it, and when it is not configured the builder says so instead of imitating one.
- The model’s output is constrained to a fixed schema and then re-checked by ordinary code. Assets are resolved against the verified registry by the application, not by the model.
- Anything ambiguous or missing becomes a question for you. It is never guessed.
- The result only pre-fills the form. You review it, and saving runs the same validation as a hand-typed mission.
- The model never evaluates a mission, never decides whether a limit passed, and cannot prepare, sign or send anything.
Stock Tokens
Robinhood Stock Tokens are ERC-20 tokens issued by Robinhood Assets (Jersey) Limited. TernAgent lists one only when the issuer’s registry, the Chainlink feed directory and the token contract itself all agree on it; a token with a matching ticker and a different address is not listed.
- They carry eligibility restrictions set by the issuer. They are not available to U.S. persons, and restrictions apply in other jurisdictions including Canada, the United Kingdom and Switzerland. TernAgent cannot verify your eligibility; the mission builder asks you to confirm it.
- The issuer can pause transfers. The contract’s pause flag is read before every decision, and a paused asset makes the mission wait.
- The underlying market has sessions and holidays; the tokens trade on chain at any hour. The market calendar (NYSE core trading session, 2026-01-01 to 2028-12-31) is context, or a rule only if you set it. Outside its coverage it reports “unavailable” rather than guessing.
Read the issuer’s terms: Stock Token documentation.
Accounts and data safety
- Connecting a wallet is not signing in. Signing in uses Sign-In with Ethereum (EIP-4361): a message bound to this site’s domain, with a single-use nonce and a short expiry, verified on the server.
- Sessions live in an httpOnly cookie; only a hash of the token is stored.
- Every mission, receipt and prepared transaction belongs to one address, and every server operation checks ownership. A mission of another account answers exactly like one that does not exist. The one exception is the operator’s reference missions, which are public by design and hold no user data.
- The server holds no signing key. It never asks for a seed phrase or a private key.
- Transaction targets and spenders come from a fixed, verified list on the server. Nothing a user, a provider response or a language model supplies can add to it.
What is not built
- Automated or scoped signing (session keys, delegated execution). Every transaction needs your wallet.
- RFQ venues, the Lighter order book, or any venue other than the two listed above.
- Multi-step missions, recurring orders, or selling into several assets.
- Backtesting against historical data.
- Cryptographically signed or on-chain-anchored receipts.
- An audit. This software has not been audited, and it should not be treated as production-ready because it runs.
The $TERN token
$TERN is the project’s token on Robinhood Chain (chain ID 4663). Its status on this site right now: $TERNCA: Soon
- The application does not use it. No mission, check, limit or receipt depends on $TERN, and nothing here requires holding it.
- No contract address has been published: the site prints “CA: Soon” and no token address of any kind. Until that changes, an address offered anywhere as $TERN is not from this project.
- The address reaches the site through one command, which requires contract code at the address on chain ID 4663 and reads its symbol, name, decimals and total supply before anything is written. You can check the result yourself at
/api/token, which also returns a fresh read of the contract. - No supply, allocation, price or utility is stated on this site unless it was read from the contract. Announcements are made on @TernAgent.
Market checks reduce avoidable mistakes. They do not guarantee execution, a price, or a return. Nothing here is investment advice.