Run your own P2P bot

02What a bot is here

A P2P bot is a program you run on your own machine, with your own keys, that posts offers on Saturn's P2P market, takes them, and carries each trade through its locks, claims and refunds, as the P2P page does for a person. Saturn never holds your keys, never trades for you and runs no bot of its own: your keys, your risk.

03Try it on devnet in 10 minutes

You need Node 22 or later and a terminal. Run these commands in order. The first two download the kit and its SHA-256 from this site, and the third checks one against the other: do not run the kit if the check fails (on macOS, check with shasum -a 256 -c saturn-p2p-bot-kit.tgz.sha256).

1. curl -fsSLO https://ops.saturnx.cc/downloads/saturn-p2p-bot-kit.tgz
2. curl -fsSLO https://ops.saturnx.cc/downloads/saturn-p2p-bot-kit.tgz.sha256
3. sha256sum -c saturn-p2p-bot-kit.tgz.sha256
4. tar xzf saturn-p2p-bot-kit.tgz
5. cd saturn-p2p-bot-kit
6. npm ci --ignore-scripts
7. npx tsx examples/new-keys.ts
8. npm run faucet -- --pha <seller P2K address> --base <seller 0x address>
9. npm run faucet -- --pha <buyer P2K address> --base <buyer 0x address>
10. npm run seller
11. npm run buyer

• new-keys.ts makes a key pair for each example bot in the keys folder, each file readable only by you, and prints only the addresses, with the two faucet commands filled in.
• One faucet claim sends test TAZ, RA, SOUL and KCAL on Phantasma devnet, and test mUSDC and a little ETH on Base Sepolia.
• Run npm run seller and npm run buyer in two terminals. The buyer takes the seller's offers and the seller sells into the buyer's, through the public P2P board, with real locks and claims on the two test networks.
• Watch them trade on https://ops.saturnx.cc/p2p with devnet picked in the Network menu at the top of the page.
• npm run seller -- --dry-run shows what a bot would do and sends nothing. Ctrl-C once stops a bot cleanly: it cancels its offers and finishes its running trades. Its state stays in its data folder, so a restart resumes every trade.

04What the kit checks before it signs

The kit runs the same checks as the P2P page before every signature, and signs only when all of them pass. A failed check sends nothing. In short:

• The contracts on both chains are the pinned ones: the escrow's code and admin on Phantasma, SaturnSwap and USDC on Base.
• Every amount, token, price and address of a trade is what your bot agreed to, and a trade on an offer that follows the reference price is within your limit price.
• The other side's lock is on chain, confirmed, with the right amount, recipient and time left, before your bot locks or claims.
• Fees are no higher than the trade's fee, and the time limits leave room for both claims.
• Your bot holds what its own step needs (the tokens with their gas reserve, USDC with a little ETH), and no other trade of the bot uses the same lock.

docs/CHECKS.md, inside the download, lists every check with what it guards against and the P2P page's code it copies.

05Rules that can pause your bot

• 3 no-shows in 24 hours pause your bot for 24 hours after the last one. A no-show is an accepted trade where your bot owed the next lock and did not send it in time. Declining a take, or leaving one unanswered, is not a no-show.
• Takes and offers count apart. 3 takes your bot did not lock in time pause its takes. 3 trades on its offers it did not lock in time pause its new offers and accepts, and take its offers off the board.
• These limits count per identity: your API key, or your IP address without one, so bots without a key behind one IP address share them. As the seller, one identity may tie up at most a third of a token's shared lock cap at a time.
• The devnet faucet serves each Phantasma address and each Base address once every 24 hours, at most 3 claims a day from one connection, and 20 claims an hour and 200 a day for everyone together.
• An offer stays listed only while its bot keeps it alive: a bot that stops is taken off the board within about 90 seconds.

06Going live: an API key and your limits

An API key is optional. Without one, the board allows each IP address 10 offers and takes a minute, and 120 other writes a minute. For an API key with its own, higher limits and its own identity, ask in Saturn's Telegram channel, t.me/stellargateio. Keep the key in a file only you can read and give the bot its path. Keys can be revoked at any time. For maker rewards and the accept rate, a key is not a separate maker on its own network address: a take from the offer's API key, or from the same IP address (IPv6: the same /64) with any key, counts as the maker's own and is left out of its takes, accept rate and the no-shows its reward quality counts (a missed lock still counts toward the 3-in-24-hours pause). Two of your bots trading with each other from one machine never raise an accept rate. A completed trade between them is still a completed trade: like any other, it proves the address pair of the offer it filled and makes the maker's Base address eligible for a share of maker rewards.

• Start on devnet, keep small balances on a bot's addresses, and watch it before you trust it.
• Use keys made for the bot. The kit refuses a key file other users can read, never takes a key from the command line, and never writes a key or a secret to its logs.
• Mainnet P2P is off for now: the kit has no mainnet settings yet and refuses mainnet. When it opens, a bot will also need --mainnet on its command line and KIT_ALLOW_MAINNET=1 in its environment.

Your keys, your risk. Nobody can undo a trade, recover funds or stop a bot you left running. The kit checks every trade before it signs, but it trades at the prices and amounts you give it: a wrong price in your config is a real trade at that price.

07Reference

• The P2P API, described for programs (OpenAPI): https://apiops.saturnx.cc/openapi/p2p.json
• The P2P guide written for bot authors and AI agents: https://apiops.saturnx.cc/llms/p2p.txt
• Long-poll: one heartbeat call keeps up to 40 offers listed and waits up to 25 seconds for a take, so a take reaches the bot within about a second. Trade reads can wait for a change the same way.
• Self-claims: by default a selling bot claims its USDC itself and never sends its secret to the board, and a buying bot claims its tokens itself when Saturn's keeper has not (after 60 seconds on devnet). Locks that end unclaimed are refunded after their time limits.
• Retries: every error says whether to retry and when. An offer or a take carries a token the bot keeps on disk first, so a retried request is never made twice.
• Writing your own bot: README.md, inside the download, shows the kit's TypeScript API (createKit, then postOffer, take, buyUpTo, sellDownTo and run), every option and the safety model. The two example bots in examples/ are a starting point to copy.