Agents and automation
How to run a headless client (a bot, a strategy loop or an LLM agent) against Acta. The protocol is
the same one the web app uses; this page covers what changes when nobody watches the session.
Examples use the TypeScript SDK (@acta-markets/ts-sdk 0.5.5 or later).
Headless keypair
A taker needs only a Solana keypair: no registration and no on-chain setup. Load it from a file the agent's process can read and nothing else can:
import { readFileSync } from "node:fs";
import { KeypairAuthProvider } from "@acta-markets/ts-sdk";
import { ActaWsClient } from "@acta-markets/ts-sdk/ws";
const auth = await KeypairAuthProvider.fromJson(readFileSync(process.env.ACTA_KEYPAIR!, "utf8"));
const ws = new ActaWsClient({
url: "wss://devnet-api.acta.markets",
role: "taker",
onDisconnect: "keep_quotes",
products: ["covered_call", "cash_secured_put", "call_spread", "put_spread", "cash_put"],
clientName: "my-agent",
clientVersion: "0.1.0",
autoReconnect: true,
});
ws.connectAndAuthenticate(auth);
await ws.waitForAuthenticated(30_000);
The same key signs the auth challenge and the sponsored transactions, so it controls the wallet's funds. Use a dedicated wallet funded only with what the agent may trade. On devnet the faucet funds a new wallet once; see Sandbox.
The SDK reconnects, authenticates again (resume first, a fresh signature after session_expired),
resubscribes and re-reads open RFQs and positions on its own. The agent does not handle any of that.
Price before you ask
Creating an RFQ broadcasts it to makers. To learn a price without that, read indicatives and price the fill locally:
import { grossFromIndicative1e9, previewFill } from "@acta-markets/ts-sdk/ws";
const terms = { type: "cash_secured_put", strike: "136000000000" } as const;
const fees = quoteToken.protocol_fees; // /tokens or GetTokens, per quote token
const preview = previewFill({
terms,
side: "sell",
quantity: "1000000000",
// A sell indicative is already net of the fee; previewFill takes the gross price.
price1e9: grossFromIndicative1e9(strikePrice, "sell", terms, fees), // a strike's `price` of type "quoted"
fees,
underlyingDecimals: 9,
quoteDecimals: 6,
});
// preview.premium.{grossAtoms, feeAtoms, netAtoms}, preview.collateral,
// preview.breakeven1e9, preview.maxProfitAtoms, preview.maxLossAtoms
The fee follows the program's rule: the smaller of premium_bps of the price and volume_bps of the
strike (or spread width). An indicative is the median of maker answers, net of the fee on a sell and
gross on a buy; it is not a firm quote. With a real quote, pass QuoteReceived.price, which is gross.
Indicatives exist for covered calls and cash-secured puts only.
Submit, then reconcile
Two commands can take effect without the agent seeing the reply: RfqRequest and
SubmitSignedSponsoredTx. Resending either one blindly can open a second RFQ or try to fill an order
twice. The SDK owns both:
const { rfqId, created } = await ws.createRfqOnce({
market_pda: market, terms, side: "sell", quantity, timeout_seconds: 30,
});
const outcome = await ws.submitOrderOnce({ orderIdHex, txBase64: signedTx });
switch (outcome.type) {
case "accepted": // queued; follow OrderSubmitted / OrderConfirmed / OrderFailed
break;
case "rejected": // this attempt was not forwarded; act on outcome.action
break;
case "reconciled": // the reply was lost, so the SDK looked the order up
// outcome.state.type: pending | confirmed | unknown. unknown is not proof of non-execution.
break;
}
createRfqOnceresends a lost reply with the same id while the RFQ could still be open. A repeat is rejected withduplicate_rfq_id, which proves the first attempt created it.submitOrderOncenever sends one order twice. A timeout, a disconnect ordelivery: "unknown"turns into aGetOrderStatuslookup, and every later call for that order only looks it up.- Neither
OrderFailednor anunknownstatus authorizes signing the order again. Pick another quote or open a new RFQ instead. - The SDK keeps this record in memory. After a process restart, read
GetMyActiveRfqsandGetOrderStatusbefore submitting anything.
Errors
Every error maps to one action: retry, reauthenticate, refresh, reconcile, fix_request or
stop. Branch on the action, never on message or reason text:
import { ActaWsRequestError } from "@acta-markets/ts-sdk/ws";
try {
await ws.acceptQuote(rfqId, maker, orderIdHex);
} catch (err) {
if (!(err instanceof ActaWsRequestError)) throw err;
switch (err.action) {
case "retry": /* back off, send the same request */ break;
case "refresh": /* fetch fresh quotes or state, build a new request */ break;
case "reconcile": /* look the command up before anything else */ break;
case "fix_request": /* the request is invalid; change it */ break;
case "stop": /* market, venue or account state must change first */ break;
case "reauthenticate": /* the SDK re-authenticates; resend after it does */ break;
}
}
The action of every code is in the WS error catalog and
the ServerError catalog. errorAction(error, "not_applicable")
gives the same answer for an Error frame.
Units
Most agent bugs here are unit bugs.
| Value | Unit |
|---|---|
quantity, size_rule | Underlying atoms, for every product, including puts and spreads |
strike, price, net_price, indicatives, underlying_price | Quote per whole underlying, scaled by 1e9 |
collateral, premium totals | Atoms of the collateral mint: underlying for a covered call, quote otherwise |
protocol_fees | Basis points, per quote token |
priceis gross. A seller receivesnet_price, the price after the protocol fee; a buyer paysprice.- A cash-secured put is sized in underlying atoms, not in quote. Convert a quote budget with
quoteAmountToQuantity, then snap it to the size rule. - Amounts are decimal strings on the wire and in the SDK types. Do money math in
bigint(BigInt(price)) or with the SDK helpers (totalPremiumQuoteAtoms,previewFill), never inNumber.
Pace
- HTTP replies carry
X-RateLimit-Limit,X-RateLimit-Remainingand, on429,Retry-After. Welcome.rate_limitslists the WebSocket budgets of the connection. The TS client paces its own messages by them: a message over budget waits instead of being rejected or closing the socket. The wallet budget is shared by all of a wallet's connections, so keep one connection per wallet.- Positions and RFQs arrive as events; do not poll them in a loop. Re-read on reconnect, which the SDK already does.