Skip to content

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.

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:

  1. GET /api/keys/challenge?address=<your address> answers with a message to 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.
  2. Sign the message’s exact bytes with your wallet’s signMessage, then send POST /api/keys with { "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 read

Sending it. Pass the key with every call as Authorization: Bearer <key>, or as X-Api-Key: <key>:

Terminal window
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 to DELETE /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 401 with 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 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.

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).

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:

Terminal window
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" }.

One file, run by Node 20.18 or newer, with @solana/kit and the SDK bundled inside: there is nothing to install.

Terminal window
mkdir -p ~/sagitta && cd ~/sagitta
curl -fsSLO https://sagitta.broker/cli/sagitta.mjs
curl -fsSLO https://sagitta.broker/cli/SHA256SUMS
shasum -a 256 -c --ignore-missing SHA256SUMS # must print "sagitta.mjs: OK"; if not, delete the file and don't run it
node sagitta.mjs wallet # creates ~/.sagitta/key.json and prints its address

Send 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.

Terminal window
node sagitta.mjs key # a free API key for that address, kept in ~/.sagitta/api-key
node sagitta.mjs wallet open --send # the market wallet where bounties and referral shares land
Terminal window
node sagitta.mjs markets # every board, stocks first
node sagitta.mjs buy TSLAx UP 0.05 # a dry run: what the buy would send, and its fees
node sagitta.mjs buy TSLAx UP 0.05 --send # put 0.05 SOL on TSLAx rising
node sagitta.mjs sell TSLAx UP 50 --send # cash out half of it
node sagitta.mjs balance # SOL, holdings, open tickets, credits
node sagitta.mjs claim --send # collect what the markets owe you

How a trade travels:

  1. 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.
  2. It builds the commit with the SDK, runs the account guard and the payee check, and simulates it. Without --send it stops there and prints what it would send and the most it would cost.
  3. With --send, it sets a compute budget and a priority fee from the cluster’s recent fees, never above SAGITTA_MAX_PRIORITY, checks the exact bytes against its own build, signs with the local key and sends. Only the signed transaction leaves the machine.
  4. 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.
  5. It prints the result as a single JSON object on stdout. Progress lines go to stderr, so | jq works 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 is open to any wallet and pays a bounty (see Keepers):

Terminal window
node sagitta.mjs work # markets with tickets ready or a reading waiting
node sagitta.mjs execute TSLAx --send # settle the tickets whose reading has arrived
node sagitta.mjs poke TSLAx --send # apply the latest reading

The full command list, options and output fields are in sagitta.broker/cli/README.md.

nash.mjs uses the same key, RPC, pinned core program and checks, and decides for itself. Download it next to sagitta.mjs:

Terminal window
curl -fsSLO https://sagitta.broker/cli/nash.mjs
curl -fsSLO https://sagitta.broker/cli/SHA256SUMS
shasum -a 256 -c --ignore-missing SHA256SUMS # must print "nash.mjs: OK"; if not, delete the file and don't run it
node nash.mjs # report what it would do, and trade nothing
node nash.mjs --loop 300 --live # trade, every five minutes

Each pass:

  1. 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.
  2. 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 d hands over the fraction 1 − (1+d)^−100 of 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.
  3. 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.