Agents
A program can trade every Sagitta market from a wallet of its own. There are four ways in, from the most hands-on to the most automatic:
| Tool | What it is |
|---|---|
@sagitta/sdk |
The TypeScript library the site itself uses: reads, local quotes and transaction builders |
| The trading API | GET /api/arena for a wallet’s holdings, the market list and open upkeep; POST /api/arena for transactions to sign |
sagitta.mjs |
A command-line client: one command per action, one JSON object per result |
nash.mjs |
A player that runs on its own, explaining each trade it makes |
Every one of them signs on your own machine with your own key. Your key never goes to a Sagitta server, and Sagitta’s
keeper signs its upkeep with a key of its own. POST /api/arena answers with transactions for you to sign, and the
CLIs build and check every transaction themselves.
API keys
Section titled “API keys”Every call to the API counts against a budget of calls per 60 seconds (see Limits):
| Budget | Who | Calls per 60 seconds |
|---|---|---|
| Without a key | Anyone else, counted per IP address (an IPv6 address by its /48) | 2 |
| With a key | A free API key sent with the call, counted per key wherever the calls come from | 30 |
| The site | sagitta.broker’s own pages, with a site token | 300 |
A key belongs to a wallet address and costs a signature, nothing else. Signing sends no transaction and costs nothing. Getting a key takes two calls, which fit in the budget without one:
GET /api/keys/challenge?address=<your address>answers with amessageto sign: a Sign-In With Solana message that names the API’s domain, your address, the cluster, a single-use nonce and an expiry a few minutes away.- Sign the message’s exact bytes with your wallet’s
signMessage, then sendPOST /api/keyswith{ "address": "…", "message": "<the message>", "signature": "<base58>" }.
The answer holds the key, which starts sk_sag_, and it is shown this once: the API keeps only a hash of it. It also
gives prefix (sk_sag_ and the next 8 characters, safe to show), address, tier (key), limit, window_s,
created_at, and rotated, which is true when the address’s previous key stopped working just then.
With @solana/kit, the whole exchange is a few lines:
import { createKeyPairSignerFromBytes, getBase58Decoder } from "@solana/kit";
const API = "https://api.sagitta.broker";const signer = await createKeyPairSignerFromBytes(secretKeyBytes); // your 64-byte key
const challenge = await fetch(`${API}/api/keys/challenge?address=${signer.address}`).then((r) => r.json());const [signed] = await signer.signMessages([{ content: new TextEncoder().encode(challenge.message), signatures: {} }]);const signature = getBase58Decoder().decode(signed[signer.address]);const issued = await fetch(`${API}/api/keys`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ address: signer.address, message: challenge.message, signature }),}).then((r) => r.json());// issued.key is shown this once: keep it somewhere only you can readSending it. Pass the key with every call as Authorization: Bearer <key>, or as X-Api-Key: <key>:
curl -s -H "Authorization: Bearer $SAGITTA_API_KEY" "https://api.sagitta.broker/api/arena?keeper=1"- One key per address. Asking again rotates it: the new key works at once and the old one stops.
- Revoking. Ask for a challenge with
&purpose=revoke, sign it, and send the same body toDELETE /api/keys. The key stops working at once, and the answer is{ address, revoked, prefix }. - A bad key is refused, not ignored. A key that was revoked, replaced or never issued gets
401with the reason. Send a valid key, or none for the budget without one. - How many. At most 3 keys a day per IP address and 3 per wallet address; rotating a key counts.
- Abuse. A key the operators revoke also stops its address getting a new one, until they lift it. Revoking your own key does not.
- The key endpoints always count against the budget without a key, from your IP address, whatever else the call carries.
node sagitta.mjs key does all of this with the CLI’s wallet and keeps the key in ~/.sagitta/api-key. What the API
stores for a key is listed under API keys on the privacy page.
The trading API
Section titled “The trading API”The API reads the chain and builds transactions; it never signs them. Every answer below is JSON, and every
transaction comes back unsigned for the wallet named as payer to sign and send through any Solana endpoint. The
reference has every field and an example of each.
Reading
Section titled “Reading”GET /api/arena takes one query, which picks the view:
| Query | What it answers |
|---|---|
?list=1 |
{ markets }: every market, the same rows as /api/markets |
?who=<address> |
One wallet’s book: sol, positions (each with its market, side, symbol, units and worth_sol, what a cash-out pays now), positions_sol, tickets (its tickets until they are delivered), pending_sol, credits_sol (what withdraw pays out) and equity_sol |
?pools=<mint> |
The first look before listing: a coin’s canonical pool on each venue Sagitta reads, with its quote, the cost to move it (manipulation_cost_sol, null while unmeasured: a pool is measured only while a market reads it) and the markets already on it; whether a Chainlink feed covers it; or, for a stock token, whether it lists and why not |
?keeper=1 |
Open upkeep: each market’s matured tickets and their bounties, the reading its queue waits on, whether an execute would freeze it, whether it can be retired, and its accrued burn share, then the burn’s state and how, what each chore does in words |
Each ticket in tickets carries its id (a decimal string), its kind, its sol or shares, when it was committed,
and whether it has matured (anyone can execute it now) or settled (waiting for delivery).
Building transactions
Section titled “Building transactions”POST /api/arena takes a JSON body with a kind and the payer, the wallet that will sign and pay for the
transaction. A market is named by its address, the address of one of its side tokens, the address of the token or feed
it follows, its slug, its symbol, or a side symbol such as TSLAUP. A stock market’s side symbols carry the underlying’s
ticker, so every market on that ticker shares them, whichever issuer’s token it follows: TSLAUP fits the markets on
xStocks’ TSLAx, Ondo’s TSLAon and Backpack’s TSLA alike (see Names).
A market’s address and a side token’s address each name one market, sunset and frozen ones included, so a holder can
always reach the market of a token in its wallet. The address of a token or feed, a market’s slug (tslax, sol-usd)
and a stock token’s symbol (TSLAx) find the market the site’s page for them shows: on a token or feed with several
markets, the first listed that is neither sunset nor frozen, else the first listed. Between look-alikes that both have
markets, spelling decides: COPX is Backpack’s COPX and COPx is xStocks’ COPx, and VRTX, Vertex’s ticker, finds
Vertex’s token while vrtx is the slug of Vertiv’s VRTx. A coin’s symbol, in any spelling, never takes a stock token’s
or a feed’s name or side symbol, even before that stock or feed has a market (such a name then answers 404), and
sagitta and its side symbols, SAGITTAUP and SAGITTADN with an epoch’s number or without, always name Sagitta’s
own $SAGITTA market. Any other name (a ticker, a coin’s symbol or a side symbol) that fits markets on more than one
token is refused, with each token’s markets listed. On one token, an active market answers first: when exactly one
fits, it answers, and when several do, the name is refused with a request for the market’s address. When none is
active, a lone sunset or frozen market answers, and several are refused. A market listed moments ago answers 503
until its state is read; try again after the Retry-After seconds. A leading $, surrounding spaces and a trailing
/ are ignored. side is UP or DOWN in any case, and amounts may be numbers or decimal strings.
kind |
Body, beyond kind and payer |
What it builds |
|---|---|---|
buy |
market, side, sol; optional recipient (who gets the shares) and referrer |
commit_mint: the ticket fills at the side’s NAV at the first reading after the commit, less the 4% fee, plus its deposit and, on a relayed market, the reading fee |
sell |
market, side; optional pct of the holding (100 when left out) and recipient |
commit_redeem, filled the same way, less 4%. Older epochs’ tokens convert first, in the same transaction when they fit. Tokens too many epochs behind get a convert of their own first, as far as one transaction holds, and the same sell sent again goes on from there and sells in its last transaction |
execute |
market; optional max tickets (a call settles at most 32) and bounty_to |
execute: settles the tickets whose reading has arrived, the bounty to bounty_to’s market wallet; a payer with no market wallet opens one in the same transaction |
poke |
market |
poke, which applies the latest reading and settles up to 8 tickets |
deliver |
market, ticket (one settled ticket’s id, as a decimal string) |
deliver: pays that ticket’s shares and SOL to its owed account (anyone may) |
claim |
market, ticket (its id) |
claim: takes everything a settled ticket owes the payer, who must be its owed account |
withdraw |
— | withdraw: the payer’s market wallet balance to the payer |
retire |
market |
retire, once governance has sunset the market or its version, or closed its route: buys close at once, and it freezes at a reading after the call |
create-market |
mint (a stock token on the allowlist, the coin, or a Chainlink feed account the allowlist holds); optional pool and quote |
A listing: a stock token on the allowlist, a coin on its canonical pool (relayed, or Raydium CLMM pool history once the coin’s route is bound or pinned to that pool), or another market on a Chainlink feed the allowlist holds. A relayed source with no reading ring gets its ring first, and the listing follows once a fresh reading is posted. When its ring holds no reading from the last 600 slots, the request asks the price signers for one: call again in about a minute. Asks are limited per caller and per ring. While a coin’s pool is still being checked before its first listing, the answer is 503: call again after the Retry-After seconds. The reference gives each listing’s fields |
Each answer is { tx: { message, summary, payer, last_valid_block_height }, summary }. message is the compiled,
unsigned transaction in base64, with the freshest blockhash; summary.kind repeats the request’s kind, and the summary
lists the deposits the transaction opens (each returned to the payer), the rent it may spend, every account it writes
and why, and its fee.
A buy, for example:
curl -s https://api.sagitta.broker/api/arena \ -H "Authorization: Bearer $SAGITTA_API_KEY" -H "content-type: application/json" \ -d '{ "kind": "buy", "payer": "<your address>", "market": "tslax", "side": "UP", "sol": 0.05 }'Before it answers, the API makes each transaction with the SDK, whose account guard checks every account it
writes, and checks that a recipient other than the payer could collect. A request it can’t build gets 400 with the
reason in words: not enough SOL, nothing to sell, nothing owed, a market that isn’t retirable, or a coin with no
canonical pool on a venue Sagitta reads.
Check before you sign. An API that answered wrongly could hand you a wrong transaction, so a program that trades for
real checks what it signs: build the same request locally with the SDK and compare the two with its
checkWireMessage, which also confirms that you are the only signer and that the priority fee stays within your cap.
The CLIs do exactly that.
?who=, ?pools= and every POST read the chain for the caller, so each costs more than one unit of a budget the API
keeps per IP address for chain reads, inside the limits above. Past it the answer is 429 with Retry-After and
{ "error": "slow down" }.
sagitta.mjs
Section titled “sagitta.mjs”One file, run by Node 20.18 or newer, with @solana/kit and the SDK bundled inside: there is nothing to install.
mkdir -p ~/sagitta && cd ~/sagittacurl -fsSLO https://sagitta.broker/cli/sagitta.mjscurl -fsSLO https://sagitta.broker/cli/SHA256SUMSshasum -a 256 -c --ignore-missing SHA256SUMS # must print "sagitta.mjs: OK"; if not, delete the file and don't run itnode sagitta.mjs wallet # creates ~/.sagitta/key.json and prints its addressSend a little SOL to the address it prints: 0.05 SOL covers a first trade with its deposits and fees. The key file is the only copy of the key, so back it up.
node sagitta.mjs key # a free API key for that address, kept in ~/.sagitta/api-keynode sagitta.mjs wallet open --send # the market wallet where bounties and referral shares landnode sagitta.mjs markets # every board, stocks firstnode sagitta.mjs buy TSLAx UP 0.05 # a dry run: what the buy would send, and its feesnode sagitta.mjs buy TSLAx UP 0.05 --send # put 0.05 SOL on TSLAx risingnode sagitta.mjs sell TSLAx UP 50 --send # cash out half of itnode sagitta.mjs balance # SOL, holdings, open tickets, creditsnode sagitta.mjs claim --send # collect what the markets owe youHow a trade travels:
- The CLI asks the API for the market list, then reads the market on chain through an RPC of its own (the public
endpoint, or
SAGITTA_RPC, which must answer with mainnet-beta’s genesis hash), and only keeps it if Sagitta’s core program, pinned when the file was built, confirms it and the API’s row matches it. - It builds the commit with the SDK, runs the account guard and the payee check, and simulates it. Without
--sendit stops there and prints what it would send and the most it would cost. - With
--send, it sets a compute budget and a priority fee from the cluster’s recent fees, never aboveSAGITTA_MAX_PRIORITY, checks the exact bytes against its own build, signs with the local key and sends. Only the signed transaction leaves the machine. - The ticket fills at the first reading after the commit. The CLI waits for it; when the reading is in and nobody has executed the ticket after a short grace, it executes it itself, and when a settled ticket hasn’t been delivered, it collects it.
- It prints the result as a single JSON object on stdout. Progress lines go to stderr, so
| jqworks directly.
A market is named by its address, its slug (tslax, sol-usd, bonk-1a2b3c4d5e6f), a stock token’s symbol, a side
symbol, or the address of one of its side tokens in the current epoch, which the CLI checks against the chain before it
trades. Names resolve as in the trading API. A memecoin’s name alone never picks a market, since anyone can list a coin
under any symbol: the CLI answers with each matching market’s slug and address instead. --no-wait returns as soon as the commit lands, --to delivers
the result to another wallet, and --ref credits a referrer.
SAGITTA_KEY is a keypair file or the key itself in base58 (never printed), SAGITTA_API the API for lists and views,
and SAGITTA_RPC the RPC for everything on chain. Another cluster or deployment takes an explicit SAGITTA_CLUSTER
with SAGITTA_RPC and SAGITTA_CORE, is announced on every run, and is refused when that RPC answers for
mainnet-beta.
Without a key, each command makes at most two API calls, so it fits the budget, and a 429 from that budget is waited
out for its Retry-After rather than treated as a failure. A key the API refuses stops the command with the reason:
run key again, or unset SAGITTA_API_KEY to go without.
Upkeep
Section titled “Upkeep”Upkeep is open to any wallet and pays a bounty (see Keepers):
node sagitta.mjs work # markets with tickets ready or a reading waitingnode sagitta.mjs execute TSLAx --send # settle the tickets whose reading has arrivednode sagitta.mjs poke TSLAx --send # apply the latest readingThe full command list, options and output fields are in sagitta.broker/cli/README.md.
nash.mjs
Section titled “nash.mjs”nash.mjs uses the same key, RPC, pinned core program and checks, and decides for itself. Download it next to
sagitta.mjs:
curl -fsSLO https://sagitta.broker/cli/nash.mjscurl -fsSLO https://sagitta.broker/cli/SHA256SUMSshasum -a 256 -c --ignore-missing SHA256SUMS # must print "nash.mjs: OK"; if not, delete the file and don't run itnode nash.mjs # report what it would do, and trade nothingnode nash.mjs --loop 300 --live # trade, every five minutesEach pass:
- Exits. Holdings it opened (and, with
--adopt, any others) are sold when the pots have evened out, the opposing pot is almost empty, a profit or loss threshold is crossed, or a holding period runs out. - The smaller pot. On each open market it looks at the side with less SOL behind it, which earns the larger
multiple. If the gap and the opposing pot are big enough, it enters and logs the expected value per SOL: the chance
of winning times the slice of the opposing pot it would collect, less the chance of losing times what its own stake
would give up, less the 8% round trip and the reading fee on both tickets. A move
dhands over the fraction1 − (1+d)^−100of the losing pot (63% at 1%); NASH.md has the formula. Because a ticket fills after any move the market already has pending, the estimate uses the pots as they will stand once that move is applied. - Upkeep. It executes ready tickets, applies readings and collects what it is owed, starting with markets it holds.
Each pass makes three API calls (two with --no-keeper); before it trades, the chain confirms each market and what the
wallet holds there. Without a key that allows a pass every 90 seconds or so, so a faster --loop needs a key from
node sagitta.mjs key.
By default it favours turnover: full-size entries, and a rotation after --hold-min minutes. --no-volume sizes
strictly and skips entries below an EV floor. It never takes the side with more SOL behind it, never holds both sides
of a market, and passes over memecoin pools that are cheap to push. The details are in
sagitta.broker/cli/NASH.md.