Trader API
The public gateway speaks the same POST shapes as a Hyperliquid-style client. This page is the testnet surface. It is not a promise about mainnet.
REST
POST /info reads. POST /exchange trades. Both take a JSON body. Info requests name a type. Exchange requests are a signed action plus a nonce.
curl -s -X POST https://api.x1arena.com/info \
-H 'content-type: application/json' \
-d '{"type":"l2Book","coin":"BTC"}'Useful info types:
meta,allMids,l2Book,candleSnapshot,recentTrades,liquidationsclearinghouseState,openOrders,userFills,userFees,fundingHistoryportfolio,spotMeta,spotClearinghouseState
extraAgents lists agent keys approved by a wallet. approveAgent and revokeAgent are signed by the master. An agent can trade. It cannot withdraw. follow and unfollow copy a sub-account. openTwaps shows slices still running.
An order action is { type: "order", orders, grouping }. Each order has asset a, buy b, price p, size s, reduce-only r, and t of { limit: { tif } } or a trigger. tif is Gtc, Ioc, or Alo. Cancel is { type: "cancel", cancels: [{ a, o }] }. Amend is { type: "modify", oid, order }.
curl -s -X POST https://api.x1arena.com/exchange \
-H 'content-type: application/json' \
-d '{"action":{"type":"order","orders":[{"a":0,"b":true,"p":"100","s":"0.001","r":false,"t":{"limit":{"tif":"Gtc"}}}],"grouping":"na"},"nonce":1700000000000,"signature":"BASE58_SIGNATURE","signer":"YOUR_PUBKEY"}'Signing
The web client signs a UTF-8 statement: the domain (x1.trading), Chain: x1:testnet, the nonce in decimal, and the canonical JSON of the action (object keys sorted). actionMessage builds those bytes. The signature is ed25519, encoded as base58. The body is { action, nonce, signature, signer }. The nonce is milliseconds, newer than the last nonce for that signer, and inside the gateway clock window. Signatures over the older x1p-action-v1 prefix plus a raw nonce still verify.
import { actionMessage } from "@x1p/sdk";
import nacl from "tweetnacl";
import bs58 from "bs58";
// secretKey is the 64-byte ed25519 secret. Keep it off the page and out of git.
const action = {
type: "order",
orders: [{ a: 0, b: true, p: "100", s: "0.001", r: false, t: { limit: { tif: "Gtc" } } }],
grouping: "na",
};
const nonce = Date.now();
const signature = bs58.encode(nacl.sign.detached(actionMessage(action, nonce), secretKey));
await fetch("https://api.x1arena.com/exchange", {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({ action, nonce, signature, signer: publicKey }),
});The same bytes are signed for these actions. approveAgent is signed by the master. Orders, cancels, and twapCancel are signed by the agent after that approval.
{ "type": "cancel", "cancels": [{ "a": 0, "o": 123 }] }{ "type": "twapCancel", "a": 0, "t": 42 }{ "type": "approveAgent", "agentAddress": "AGENT_PUBKEY", "agentName": "desk", "name": "desk" }A per-order problem comes back inside statuses. A bad signature is { status: "err" }.
Ops status
opsStatus is a public read for operators. It returns the schema version, base taker and maker ppm, each market's max leverage and whether its session is open, the authorized oracle publishers and threshold, the multisig member count, threshold, and delay, the age of the last funding settlement, the maker heartbeat, and the last 20 quote errors, and the open withdraw inbox. maker.lastQuoteAgeMs is the age of the market maker's last successful quote cycle. It is not the newest resting order from any account. That book-wide age is maker.bookRestingAgeMs. maker.markets lists the maker wallet's bid and ask counts and top-of-book age. maker.skips counts markets pulled for a stale feed, a stale mark, or a closed session. meta.markFresh is false when that market's authoritative mark is missing or older than X1P_ORACLE_STALE_MS. inbox.pastDue is true when an open withdraw has waited more than forcedBatches commits. A cancel does not set it, and a late request is not included by this read. Publisher keys are public. A missing threshold is null, not a guessed number. When no governor is set, multisig.configured is false and reason says this is a single-key testnet. The body has no key files, RPC URLs, or secrets. liquidation reports whether the runner is armed, its one-second cadence, the last pass age, result, error, print count, fresh marks, and stale positions. It has no account ids. fundingHistory includes a rate row for an hour with no open interest. The 7-day chart draws that row. backup.stale is true when X1P_BACKUP_DIR has no x1perps-gateway-*.tgz newer than X1P_BACKUP_MAX_AGE_HOURS (default 24). The field does not upload anything. reconcile.ok is true when the settler mirror matches the chain account. If the mirror is behind, the gateway copies the landed liability, sequence, and root and leaves balances alone. posting is disabled: batches are posted by x1p-deploy-tool with X1P_DEPLOY_KEYPAIR, or by scripts/localnet.sh. followed is true when this process copied that landed tip. A match with followed true is expected on testnet. oracle.lastPublishAgeMs is the age of the newest feed updatedMs, or the last mark this process applied. oracle.stale is true when that age is missing or older than X1P_ORACLE_STALE_MS. The gateway code default is 120 seconds. Testnet exchange.env may set 15000 (15 seconds); that file is the live value and this page does not change it. oracle.publisherLamports is the first publisher's balance when the RPC can read it, and oracle.publisherXnt is that balance in XNT. The body still has no keys. A mirror that is ahead of the chain stays ahead. userFees adds feesPaidToday and feesPaid7d from fee cents stored per day. Older fees stay in feesPaid only.
curl -s -X POST https://api.x1arena.com/info \
-H 'content-type: application/json' \
-d '{"type":"opsStatus"}'WebSocket
Connect to /ws. Subscribe with method: "subscribe". A connection holds 16 subscriptions. Account channels (userFills, userEvents, orderUpdates) are signed again on each connection.
const ws = new WebSocket("wss://api.x1arena.com/ws");
ws.onopen = () => {
ws.send(JSON.stringify({
method: "subscribe",
subscription: { type: "l2Book", coin: "BTC" },
}));
};
ws.onmessage = (event) => handle(JSON.parse(event.data));Public channels: l2Book, trades, allMids, candle, and liquidations. A liquidation message is coin, price, size, kind, and time. It does not name an account.
Rate limits
Each IP has 12,000 weight per minute (the demo process uses 20,000). At most 4,096 IPs and 4,096 addresses are tracked. Book and account reads in the public list cost 2. userRole costs 60. Other info reads cost 20. Long lists add 1 weight per 20 rows, or per 60 candles. An exchange action costs 1 + batch length / 40 on the IP and on the address. The address buffer starts at 10,000 and refills as you trade. Cancels may spend a wider budget, then one action every 10 seconds. Over the budget the gateway answers 429. opsStatus.rateLimit repeats these caps and the reject counts since this process started. It does not name the caller. The same numbers are in docs/ops/rate-limits.md.
Prices and sizes are decimal strings. BTC size has 5 decimals and price has 1. Cash on the book is whole dollars of testnet collateral.