API

Everything the app shows comes from Anyperp's public HTTP API: markets, rounds and their signatures, the index series, the vault, protocol parameters and the attested listener data. Public reads need no sign-in and no key. Wallet reads and signed actions use the same session the app uses.

Base URL and versions

The API's base URL is <API base URL>, and every path starts with /v1. The full description of every operation is served as OpenAPI at <API base URL>/v1/openapi.json and as JSON Schema at <API base URL>/v1/schema.json.

curl "<API base URL>/v1/markets?state=live&limit=20"

Responses and errors

A successful response wraps its data with metadata:

{
  "data": { "items": [], "nextCursor": null, "total": 0 },
  "meta": {
    "requestId": "8f1c2b9e-0d4a-4e57-9a51-3f6d2f1e7c10",
    "asOf": "2026-10-16T12:00:00.000Z",
    "mode": "indexed",
    "contractVersion": "1.0.0"
  }
}

Collections are pages of { items, nextCursor, total }. Pass nextCursor back as cursor for the next page; limit takes 1 to 100. Data read from the chain is served from finalized state.

An error has one shape everywhere:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "The requested resource was not found.",
    "retryable": false,
    "details": { "resourceId": "..." }
  },
  "meta": { "requestId": "...", "asOf": "...", "mode": "indexed", "contractVersion": "1.0.0" }
}

retryable says whether the same request can succeed later.

Units

Amounts can exceed the range of a JavaScript number. Read them with BigInt or an exact decimal type. Signed values (PnL, skew, net exposure, accruals) carry a leading minus sign.

Public endpoints

A quote takes marketId, side, sizeFixed9 and leverage, and for a close intent: "close" with the positionId. It reports canSubmit and, when the order can't go through, a rejection in the error shape. A quote expires 60 seconds after it is made.

Wallet endpoints

These need the session cookie set at sign-in:

The live event stream

GET /v1/events is a server-sent event stream. Each message's event is the event type, its data the JSON event, and its id the event id. Filter market events with ?marketId=.

A heartbeat comment arrives every 15 seconds. A reconnecting EventSource sends Last-Event-ID and resumes where it left off; a new client can pass cursor. Events tell you what changed; read the endpoints again for the new state.

curl -N "<API base URL>/v1/events?marketId=<marketId>"

The contract package

@anyperp/contract is the API's TypeScript contract: every request and response type, the event union, the operation registry and a small client for browsers and Node 22.

import { createAnyperpClient, ApiClientError } from "@anyperp/contract";

const api = createAnyperpClient({ baseUrl: "<API base URL>" });

const markets = await api.request("markets", { query: { state: "live", limit: 20 } });
const first = markets.data.items[0];

const series = await api.request("marketSeries", {
  params: { marketId: first.id },
  query: { interval: "hour", limit: 168 },
});

try {
  await api.request("round", { params: { roundId: "unknown" } });
} catch (error) {
  if (error instanceof ApiClientError) console.log(error.status, error.response.error.code);
}

// Browser: live events through EventSource
const stop = api.subscribe(
  (event) => {
    if (event.type === "round.finalized") console.log(event.data.round.finalIndexFixed9);
  },
  { marketId: first.id },
);

request takes an operation name from the registry with its params, query and body, and throws ApiClientError with the status and the error envelope. eventsUrl gives the stream's URL for server-side consumers.

Signed actions

Every action that changes state is a Solana transaction signed in the user's wallet. The API prepares it and records it; it never holds a user's key.

Signing in

1. GET /v1/eligibility returns termsVersion.
2. POST /v1/auth/challenge with { wallet, origin }, the wallet's address and the app's origin, returns a challenge with the exact message to sign. It expires after 5 minutes.
3. The wallet signs the message bytes with its message-signing feature.
4. POST /v1/auth/verify with { challengeId, wallet, signatureBase64, nonUsPersonAttested, termsVersion } checks the Ed25519 signature and sets the HttpOnly session cookie.

POST /v1/auth/logout ends the session.

Prepare, sign and send, submit

1. Prepare. POST /v1/transactions/prepare with { action, idempotencyKey }. The response carries the unsigned transaction (serializedTransactionBase64), its recentBlockhash and lastValidBlockHeight, the cluster, a plain description (unsignedMessageDescription), the required signers and the network fee in lamports.
2. Sign and send. The wallet signs the transaction and sends it to Solana.
3. Submit. POST /v1/transactions/submit with { transactionId, signature, idempotencyKey }. The API checks the transaction against the prepared message and returns its state: submitted, confirmed, failed or expired.

GET /v1/transactions/:transactionId and the transaction.updated event follow it to confirmation. For an order, orderId in the transaction matches the orderId of its order.filled event. A repeated request with the same idempotency key returns the same intent; the same key with different input is a CONFLICT.

Actions