Bots and AI agents
Every product here is open to programs, and what they borrow must come back in the same transaction.
In shortPrograms use the same contracts as people. They can trade, execute orders for bounties, borrow pool liquidity or idle stake for one transaction, and run vaults for depositors. Nothing they borrow can leave the transaction.
- Access
- permissionless, no key
- Flash fee
- 0.05%
- Stake-arb split
- half bot, half stakers
- Bounties
- up to 5%
Saturn v4 is built to be used by programs as much as by people. Every product is a contract on Phantasma with no allow-list: a trading bot, an AI agent or a fleet of them calls the same methods your wallet does, and the chain holds all of them to the same rules. This guide lists what a program can do on mainnet today, what it earns, and what it can never do to you.
Trading
- Swap on any pool, or ask the router which pool pays most for a given trade and read any pool's price. A bot pays the same fee as you and that fee is split the same four ways, so bot volume feeds pool owners, the treasury and stakers of the token sold like any other trade.
- Market data without touching the chain: the public API at apiops.saturnx.cc serves tokens, pools, prices, candles and stats as JSON, refreshed every 15 seconds. Its /llms.txt page is a guide written for machines.
Earning bounties by keeping the market running
- Limit orders. When a pool can pay an order's minimum, anyone may execute it and keep the bounty: the owner's chosen share, up to 5 percent, of whatever came in above their minimum. The owner never receives less than the minimum they set.
- TWAMM streams. Each chunk of a streaming order can be fired by anyone once its pacing time has passed, for a bounty of up to 5 percent of that chunk's output. Saturn Ops has an Execute chunk button, Saturn runs a keeper that fires due chunks where it is switched on, and your bot can call the same method.
Borrowing capital for one transaction
Two contracts lend a program money it does not have, on one condition: the money is back before the transaction ends, or the whole transaction is undone as if it never happened. Nothing can be walked away with.
| Source | What is borrowed | Cost | Who earns |
|---|---|---|---|
| Protocol liquidity, flash arbitrage | Any token held by the v4 liquidity contract, which is every pool's reserves, up to the balance on hand | A 0.05 percent flash fee to the treasury, plus the normal swap fee on both legs | The executor keeps the whole net profit |
| Staked capital, stake arbitrage | Idle tokens staked in Holder rewards, up to the total staked of that token | Nothing up front | Profit is split half to the bot, half to that token's stakers |
Both run the same shape: borrow, buy on one pool, sell on another, repay. The contract checks that the round trip came back with more than it borrowed and reverts if not. For staked capital the vault's balance is re-checked against the total staked before the transaction can commit, so a stake can only grow from this, never shrink.
Own-capital arbitrage exists too. A bot that brings its own tokens keeps 100 percent of the net profit and pays only the swap fees.
Managing other people's money: agent vaults
From saturnvaults 4.2.0 (on devnet; mainnet still runs 4.1.3, where an agent's trades are one-pool round trips that can lose) an agent can open a vault in one token, with a fee between 1 and 30 percent, a minimum deposit and a hold of up to 30 days. Anyone can deposit and receives shares. The agent may only run trades that go from the vault's token through other tokens and back, over two pools (agentArb) or three (agentArb3), and the chain cancels any trade that does not end with more of the token than it started. The agent is paid its fee from each trade's profit; the rest stays with depositors and raises the share price. See Agent vaults for the whole picture.
Lending
- The peer-to-peer market is open to programs on both sides. A lender is any wallet holding TAZ: it reads open requests and submits quotes. A borrower registers a credit account first and posts an RA/TAZ v4 pool as collateral; up to saturnvault 1.0 an RA/TAZ v3 LP certificate is accepted too.
- Automated protocol lending, where loans would be approved from a shared reserve with terms set by credit score, is deployed but switched off in this version. Every call to it answers 'Auto-lending disabled in v1.0'. Until it is enabled, all loans are matched on the P2P market.
What a program can never do
- Spend from your wallet. Every method checks the signature of the address it acts for.
- Keep your stake. Borrowed stake must return in full within the same transaction, and the vault's balance is re-checked before commit.
- Pay you less than your limit order's minimum, or fire a TWAMM chunk before its pacing window or below its floor.
- Skip the fees. Bots pay the same swap fees as everyone.
Arbitrage bots are expected here and welcome. A pool priced away from the market will be corrected by them, quickly. Price your pool at the market when you create it, and expect a large single swap to be traded around; use a TWAMM stream for size, and fire its chunks on time. Whoever fires a chunk picks the moment and can wrap it in swaps of their own in the same transaction; a chunk left to grow is a bigger target with the same floor.
- Does a bot need permission or an API key?
- No. The contracts are permissionless and the read API is public and unauthenticated. A bot needs a Phantasma wallet with KCAL for gas and SOUL for the data fee, like any user.
- Which contracts are involved?
- saturnrouter for read-only quotes and prices, saturnswap for swaps, saturnlimit for limit orders, saturntwamm for streams, saturnflash for flash arbitrage, saturnarb for own-capital arbitrage, saturnstakearb for stake arbitrage, saturnvaults for agent vaults, and saturnmarket for peer-to-peer loans. Every one of them publishes its methods on chain.
- Is anyone doing this yet?
- At the time of writing the mainnet counters for flash arbitrages, stake arbitrages and agent vaults all read zero. The field is open.