ACXV API Schema

Machine-readable contract for the ACXV API, generated from the Rust types that implement it. Two artifacts ship together from the same commit, so they cannot disagree about the API they describe:

| File | Format | Covers | Reach for it when you need | | --- | --- | --- | --- | | schema.json | JSON Schema draft 2020-12 | every endpoint, including admin and diagnostics | runtime validation, event and WebSocket frame shapes | | openapi.json | OpenAPI 3.1 | public endpoints only | a typed HTTP client, rendered reference docs |

openapi.json is derived from the same in-process bundle as schema.json, so every schema in it is plain draft 2020-12 — that is why the document targets 3.1 rather than 3.0, whose dialect cannot express these shapes. Endpoints marked x-internal in the bundle are absent from the OpenAPI document, along with the types only they use.

npm install @across-protocol/acxv-api-schema          # tracks master
npm install @across-protocol/acxv-api-schema@staging  # tracks staging

Every published version is 0.1.0-<channel>.<commit>. Pin the exact version if you need a contract that cannot move under you.

Typed HTTP client

openapi-fetch type-checks the path, method, body, and response together:

npm install openapi-fetch
npm install -D openapi-typescript
npx openapi-typescript \
  node_modules/@across-protocol/acxv-api-schema/openapi.json \
  -o src/acxv-api.d.ts

import createClient from "openapi-fetch";
import type { paths } from "./acxv-api";

const client = createClient<paths>({
  baseUrl: "https://acxv.example.com",
  headers: { "X-API-Key": process.env.ACXV_API_KEY ?? "" },
});

// `body` is checked against SubmitOrderRequest; `data` is SubmitOrderResponse.
const { data, error } = await client.POST("/submit", { body: order });

Auth headers differ by endpoint — /submit takes X-API-Key, while relayer endpoints take X-Relayer-Key plus the X-Auth-Message / X-Auth-Signature pair. Each operation's security block names which it requires, and components.securitySchemes maps those names to headers.

Runtime validation

Validate against schema.json, which covers the event and WebSocket frames that OpenAPI cannot express:

import Ajv2020 from "ajv/dist/2020";
import schema from "@across-protocol/acxv-api-schema";

// `Ajv2020`, not the default `ajv` export: the bundle declares draft 2020-12 and
// the default build only carries the draft-07 meta-schema.
const ajv = new Ajv2020({ schemas: [schema] });
const validateResult = ajv.getSchema(
  `${schema.$id}#/$defs/RelayerResultResponse`,
);

if (!validateResult?.(frame)) {
  throw new Error(ajv.errorsText(validateResult?.errors));
}

Types without a client

npm install -D json-schema-to-typescript
npx json2ts \
  --unreachableDefinitions \
  -i node_modules/@across-protocol/acxv-api-schema/schema.json \
  -o src/acxv-schema.d.ts

import type { SubmitOrderRequest, SubmitOrderResponse } from "./acxv-schema";

Rendered reference

npx @redocly/cli preview-docs node_modules/@across-protocol/acxv-api-schema/openapi.json

Every deployment also serves its own copy — GET /openapi.json for the document and GET /docs for the rendered page, both unauthenticated. Those bytes are the contract that deployment is actually running, which is the authoritative answer when a published artifact and a live service seem to disagree.

Reading the artifacts directly

import schema from "@across-protocol/acxv-api-schema";
import openapi from "@across-protocol/acxv-api-schema/openapi.json";

// Endpoint metadata, keyed "METHOD /path", including the admin surface.
const submit = schema["x-endpoints"]["POST /submit"];
console.log(submit.requestBody.content["application/json"].schema.$ref);

// The same endpoint as an OpenAPI operation.
console.log(openapi.paths["/submit"].post.operationId); // "submitOrder"

WebSocket endpoints carry their frame schemas under x-websocket in both artifacts, since OpenAPI has no native representation for them. The HTTP response documented for those operations is the 101 upgrade.