perp-cli 0.12.17 → 0.14.1

package/dist/exchanges/arcus/agent.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Arcus agent (API key) lifecycle — design §10.4.
+ *
+ * approve:
+ *  1. Resolve the master EVM signer from OWS (`masterOwsWallet`).
+ *  2. Create or reuse OWS wallet `agent-arcus-<master>` (empty passphrase, same
+ *     pattern as Pacifica's `agent-pac-<master>`); its Solana account is the
+ *     Ed25519 key. API key = hex(32-byte pubkey decoded from the base58 address).
+ *     OWS `signMessage(…, "solana", …)` produces a raw Ed25519 signature over
+ *     the given bytes (no prefix) — verified locally against tweetnacl.
+ *  3. Sign the `CreateApiKey` EIP-712 typed data with the master wallet.
+ *  4. POST /v1/createApiKey (no X-API-Key).
+ *  5. Confirm via GET /v1/apiKeys?address= (poll until the key is ACTIVE).
+ *  6. Return ArcusAgentMeta — persisting it is the caller's job.
+ *
+ * revoke: POST /v1/revokeApiKey signed by the same master wallet (EIP-712
+ * `RevokeApiKey`). The OWS agent wallet is left in place for the caller.
+ */
+import type { ArcusAgentMeta } from "../../settings.js";
+import type { Network } from "../venue-types.js";
+/** Arcus accepts validUntil between 1 and 180 days from server time. */
+export declare const ARCUS_MAX_KEY_DAYS = 180;
+export declare function arcusAgentWalletName(masterOwsWallet: string): string;
+/** Base58 Solana address → 64-hex Ed25519 public key. */
+export declare function ed25519PubHexFromBase58(address: string): string;
+interface ApiKeyEntry {
+    apiKey: string;
+    address: string;
+    status: string;
+    accountIndex?: number;
+    allSubaccounts?: boolean;
+    validUntil: number;
+}
+export declare function listArcusApiKeys(network: Network, address: string): Promise<ApiKeyEntry[]>;
+export interface ApproveArcusAgentOpts {
+    /** User-facing agent name; also sent as the Arcus `apiWalletName` (1–64 chars). */
+    agentName: string;
+    masterOwsWallet: string;
+    passphrase: string | null;
+    /** 0–9 for one subaccount, 255 for all subaccounts. */
+    accountIndex: number;
+    network: Network;
+    /** Key lifetime in days, 1..180. */
+    validDays: number;
+}
+export declare function approveArcusAgent(opts: ApproveArcusAgentOpts): Promise<ArcusAgentMeta>;
+export interface RevokeArcusAgentOpts {
+    meta: ArcusAgentMeta;
+    masterOwsWallet: string;
+    passphrase: string | null;
+    network: Network;
+}
+/** Revoke the key on Arcus. Throws on rejection (a 404 means the key is not registered to this owner). */
+export declare function revokeArcusAgent(opts: RevokeArcusAgentOpts): Promise<void>;
+export {};

package/dist/exchanges/arcus/agent.js

@@ -0,0 +1,188 @@
+/**
+ * Arcus agent (API key) lifecycle — design §10.4.
+ *
+ * approve:
+ *  1. Resolve the master EVM signer from OWS (`masterOwsWallet`).
+ *  2. Create or reuse OWS wallet `agent-arcus-<master>` (empty passphrase, same
+ *     pattern as Pacifica's `agent-pac-<master>`); its Solana account is the
+ *     Ed25519 key. API key = hex(32-byte pubkey decoded from the base58 address).
+ *     OWS `signMessage(…, "solana", …)` produces a raw Ed25519 signature over
+ *     the given bytes (no prefix) — verified locally against tweetnacl.
+ *  3. Sign the `CreateApiKey` EIP-712 typed data with the master wallet.
+ *  4. POST /v1/createApiKey (no X-API-Key).
+ *  5. Confirm via GET /v1/apiKeys?address= (poll until the key is ACTIVE).
+ *  6. Return ArcusAgentMeta — persisting it is the caller's job.
+ *
+ * revoke: POST /v1/revokeApiKey signed by the same master wallet (EIP-712
+ * `RevokeApiKey`). The OWS agent wallet is left in place for the caller.
+ */
+import bs58 from "bs58";
+import { PerpError } from "../../errors.js";
+import { loadOws } from "../../signer/ows-loader.js";
+import { OwsEvmSigner } from "../../signer/ows-evm.js";
+import { networkConfig } from "../venue.js";
+import { arcusVenue } from "../venues/arcus.js";
+import { ArcusClient } from "./client.js";
+import { createApiKeyTypedData, nowNs, revokeApiKeyTypedData, splitEvmSignature } from "./signing.js";
+/** Arcus accepts validUntil between 1 and 180 days from server time. */
+export const ARCUS_MAX_KEY_DAYS = 180;
+const DAY_MS = 86_400_000;
+const CONFIRM_ATTEMPTS = 10;
+const CONFIRM_INTERVAL_MS = 1_000;
+export function arcusAgentWalletName(masterOwsWallet) {
+    return `agent-arcus-${masterOwsWallet}`;
+}
+function signingChainId(network) {
+    const id = networkConfig(arcusVenue, network).signingChainId;
+    if (id === null)
+        throw new Error("arcus venue definition is missing signingChainId");
+    return id;
+}
+async function signTyped(signer, td) {
+    return splitEvmSignature(await signer.signTypedData(td.domain, td.types, td.message));
+}
+/** Base58 Solana address → 64-hex Ed25519 public key. */
+export function ed25519PubHexFromBase58(address) {
+    const bytes = bs58.decode(address);
+    if (bytes.length !== 32) {
+        throw new PerpError("INVALID_PARAMS", `Expected a 32-byte Ed25519 public key, got ${bytes.length} bytes`);
+    }
+    return Buffer.from(bytes).toString("hex");
+}
+export async function listArcusApiKeys(network, address) {
+    const res = await new ArcusClient(network, null).get("/v1/apiKeys", "apiKeys", { address });
+    if (!res || !Array.isArray(res.apiKeys)) {
+        throw new PerpError("EXCHANGE_ERROR", "Arcus /v1/apiKeys: missing apiKeys array");
+    }
+    return res.apiKeys;
+}
+function tryDeleteWallet(walletName) {
+    try {
+        loadOws().deleteWallet(walletName);
+        return true;
+    }
+    catch (err) {
+        process.stderr.write(`[warn] failed to clean up orphan wallet "${walletName}": ${err instanceof Error ? err.message : String(err)}\n`);
+        return false;
+    }
+}
+export async function approveArcusAgent(opts) {
+    const { agentName, masterOwsWallet, passphrase, accountIndex, network, validDays } = opts;
+    if (agentName.length === 0 || agentName.length > 64) {
+        throw new PerpError("INVALID_PARAMS", "Arcus agent name must be 1–64 characters");
+    }
+    if (!Number.isInteger(validDays) || validDays < 1 || validDays > ARCUS_MAX_KEY_DAYS) {
+        throw new PerpError("INVALID_PARAMS", `Arcus key lifetime must be 1–${ARCUS_MAX_KEY_DAYS} days (got ${validDays})`);
+    }
+    if (!(Number.isInteger(accountIndex) && ((accountIndex >= 0 && accountIndex <= 9) || accountIndex === 255))) {
+        throw new PerpError("INVALID_PARAMS", `Arcus accountIndex must be 0–9 or 255 (got ${accountIndex})`);
+    }
+    // 1. master
+    const master = OwsEvmSigner.create(masterOwsWallet, passphrase ?? undefined);
+    const ownerAddress = master.getAddress().toLowerCase();
+    // 2. agent wallet (create or reuse)
+    const ows = loadOws();
+    const agentWalletName = arcusAgentWalletName(masterOwsWallet);
+    const existing = ows.listWallets().find((w) => w.name === agentWalletName);
+    const created = existing === undefined;
+    const wallet = existing ?? ows.createWallet(agentWalletName, "");
+    const sol = wallet.accounts.find((a) => a.chainId.startsWith("solana:"));
+    if (!sol) {
+        if (created)
+            tryDeleteWallet(agentWalletName);
+        throw new PerpError("INVALID_PARAMS", `Agent wallet "${agentWalletName}" has no Solana (Ed25519) account`, {
+            remediation: "Check OWS vault configuration",
+        });
+    }
+    const apiKeyHex = ed25519PubHexFromBase58(sol.address);
+    // 3. EIP-712 CreateApiKey
+    const validUntilMs = Date.now() + validDays * DAY_MS;
+    const nonce = nowNs().toString(); // Unix-ns string, single-use per (address, accountIndex)
+    const chainId = signingChainId(network);
+    const signature = await signTyped(master, createApiKeyTypedData({
+        chainId, apiWalletName: agentName, publicKeyHex: apiKeyHex, validUntilMs, accountIndex, nonce,
+    }));
+    // 4. register
+    const client = new ArcusClient(network, null);
+    try {
+        await client.postUnsigned("/v1/createApiKey", "createApiKey", {
+            address: ownerAddress,
+            publicKey: apiKeyHex,
+            apiWalletName: agentName,
+            accountIndex,
+            validUntil: validUntilMs,
+            nonce,
+            signature,
+        });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        if (err instanceof PerpError && err.structured.code === "ORDER_PENDING") {
+            // The request may have registered the key: deleting the wallet would orphan an active
+            // venue API key whose private key no longer exists anywhere. Keep it and say so.
+            throw new PerpError("ORDER_PENDING", `Arcus createApiKey outcome unknown: ${msg}`, {
+                exchange: "arcus",
+                cause: err.structured,
+                agentWalletName,
+                apiKeyHex,
+                remediation: `Do NOT re-run approve yet — the key ${apiKeyHex} may already be registered. The agent wallet "${agentWalletName}" was KEPT (it holds that key). ` +
+                    `Check the account's API keys on Arcus (perp wallet agent list arcus, or the Arcus UI), then re-run: perp wallet agent approve arcus --master ${masterOwsWallet}`,
+            });
+        }
+        const cleanupOk = created ? tryDeleteWallet(agentWalletName) : true;
+        throw new PerpError("APPROVE_FAILED", `Arcus createApiKey failed: ${msg}`, {
+            cause: err instanceof PerpError ? err.structured : undefined,
+            remediation: cleanupOk
+                ? `Fix the cause above and retry: perp wallet agent approve arcus --master ${masterOwsWallet}`
+                : `Delete the orphan OWS wallet "${agentWalletName}" manually, then retry`,
+        });
+    }
+    // 5. confirm
+    for (let i = 0; i < CONFIRM_ATTEMPTS; i++) {
+        const keys = await listArcusApiKeys(network, ownerAddress);
+        const hit = keys.find(k => k.apiKey.toLowerCase() === apiKeyHex && k.status === "ACTIVE");
+        if (hit) {
+            return {
+                kind: "arcus",
+                agentName,
+                agentWalletName,
+                apiKeyHex,
+                accountIndex,
+                ownerAddress,
+                validUntil: new Date(validUntilMs).toISOString(),
+                network,
+                approvedAt: new Date().toISOString(),
+            };
+        }
+        await new Promise(r => setTimeout(r, CONFIRM_INTERVAL_MS));
+    }
+    throw new PerpError("APPROVE_PARTIAL", "Arcus accepted createApiKey but the key is not listed as ACTIVE yet", {
+        remediation: `Check GET /v1/apiKeys?address=${ownerAddress} for key ${apiKeyHex}, then re-run the approve command (re-registering an owned key is allowed)`,
+    });
+}
+/** Revoke the key on Arcus. Throws on rejection (a 404 means the key is not registered to this owner). */
+export async function revokeArcusAgent(opts) {
+    const { meta, masterOwsWallet, passphrase, network } = opts;
+    const master = OwsEvmSigner.create(masterOwsWallet, passphrase ?? undefined);
+    if (master.getAddress().toLowerCase() !== meta.ownerAddress.toLowerCase()) {
+        throw new PerpError("INVALID_PARAMS", `Master wallet ${master.getAddress()} does not own Arcus key ${meta.apiKeyHex}`, {
+            remediation: `Use the OWS wallet for ${meta.ownerAddress}`,
+        });
+    }
+    const nonce = nowNs().toString(); // Unix-ns string, single-use per (address, accountIndex)
+    const signature = await signTyped(master, revokeApiKeyTypedData({
+        chainId: signingChainId(network),
+        apiWalletName: meta.agentName,
+        publicKeyHex: meta.apiKeyHex,
+        accountIndex: meta.accountIndex,
+        nonce,
+    }));
+    await new ArcusClient(network, null).postUnsigned("/v1/revokeApiKey", "revokeApiKey", {
+        address: meta.ownerAddress,
+        publicKey: meta.apiKeyHex,
+        apiWalletName: meta.agentName,
+        accountIndex: meta.accountIndex,
+        nonce,
+        signature,
+    });
+}

package/dist/exchanges/arcus/client.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Arcus REST client — raw fetch, Ed25519 header auth, venue rate limiting,
+ * HTTP/venue errors → PerpError.
+ *
+ * Auth headers (protected writes): X-API-Key (64-hex pubkey), X-Timestamp
+ * (Unix ns, ±30 s), X-Signature (128-hex Ed25519). All reads are public and
+ * take `?address=` (account state on Arcus is readable by anyone).
+ */
+import { PerpError, type ErrorCode } from "../../errors.js";
+import type { Network } from "../venue-types.js";
+import { type Ed25519SignFn } from "./signing.js";
+export interface ArcusAuth {
+    apiKeyHex: string;
+    sign: Ed25519SignFn;
+    /** Master EVM address that owns the key (sent as `?address=`). */
+    ownerAddress: string;
+}
+type Query = Record<string, string | number | boolean | null | undefined>;
+export interface ArcusResponse<T> {
+    status: number;
+    data: T;
+}
+/** Map an Arcus rejectionReason (engine) to an error code. Unknown → EXCHANGE_ERROR. */
+export declare function arcusRejectionCode(reason: string | null | undefined): ErrorCode;
+/** PerpError for an engine rejectionReason; details carry `rejectionReason` for callers that branch on it. */
+export declare function arcusRejectionError(reason: string | null | undefined, message: string, details: Record<string, unknown>): PerpError;
+/** setLeverage rejection (HTTP 422 or a 200/REJECTED body) → PerpError. Unknown reason → EXCHANGE_ERROR. */
+export declare function arcusLeverageRejectError(reason: string | null | undefined, message: string, details: Record<string, unknown>): PerpError;
+/**
+ * HTTP 429 → RATE_LIMITED. Order writes carry `retryAfterMs` (exact) and
+ * `reason`; otherwise Retry-After (whole seconds). Docs: api-reference/rate-limits.
+ */
+export declare function arcusRateLimitedError(retryAfterHeader: string | null, text: string): PerpError;
+export declare class ArcusClient {
+    readonly network: Network;
+    private readonly auth;
+    readonly baseUrl: string;
+    private readonly rateKey;
+    constructor(network: Network, auth: ArcusAuth | null);
+    get hasAuth(): boolean;
+    requireAuth(): ArcusAuth;
+    private acquire;
+    /** Callers acquire the rate-limit slot first (signed requests do so BEFORE taking their timestamp). */
+    private send;
+    /** Public GET. `endpoint` is the rate-limit weight key. */
+    get<T>(path: string, endpoint: string, query?: Query): Promise<T>;
+    /** Unsigned POST (EIP-712 wallet-signed bodies: createApiKey / revokeApiKey / withdraw). */
+    postUnsigned<T>(path: string, endpoint: string, body: Record<string, unknown>): Promise<ArcusResponse<T>>;
+    /**
+     * Scheme-1 POST. The rate-limit slot is acquired first; only then is the
+     * timestamp `ctNs` taken and handed to `build`, which returns the typed-payload
+     * signature and the pre-serialized body (canonicalJson — the body's int64 ns
+     * `timestamp` exceeds Number precision and must be emitted from a bigint).
+     * `ctNs` becomes X-Timestamp; `?address=` carries the master address.
+     */
+    postScheme1<T>(path: string, endpoint: string, build: (ctNs: bigint) => Promise<{
+        bodyJson: string;
+        signatureHex: string;
+    }>): Promise<ArcusResponse<T>>;
+    /** Scheme-2 POST: signs `ts + action + canonicalJson(body)` and sends that exact canonical body. */
+    postScheme2<T>(action: string, body: Record<string, unknown>): Promise<ArcusResponse<T>>;
+}
+export {};

package/dist/exchanges/arcus/client.js

@@ -0,0 +1,285 @@
+/**
+ * Arcus REST client — raw fetch, Ed25519 header auth, venue rate limiting,
+ * HTTP/venue errors → PerpError.
+ *
+ * Auth headers (protected writes): X-API-Key (64-hex pubkey), X-Timestamp
+ * (Unix ns, ±30 s), X-Signature (128-hex Ed25519). All reads are public and
+ * take `?address=` (account state on Arcus is readable by anyone).
+ */
+import { PerpError, orderOutcomeUnknown } from "../../errors.js";
+import { acquireRate, rateLimitedError } from "../rate-limiter.js";
+import { arcusVenue } from "../venues/arcus.js";
+import { canonicalJson, nowNs, scheme2Message, signUtf8Hex } from "./signing.js";
+const TIMEOUT_MS = 15_000;
+function restUrl(net) {
+    const cfg = arcusVenue.networks[net];
+    if (!cfg)
+        throw new PerpError("NOT_IMPLEMENTED", `Arcus has no ${net} environment`);
+    return cfg.restUrl;
+}
+function qs(q) {
+    const parts = [];
+    for (const [k, v] of Object.entries(q)) {
+        if (v === null || v === undefined)
+            continue;
+        parts.push(`${encodeURIComponent(k)}=${encodeURIComponent(String(v))}`);
+    }
+    return parts.length ? `?${parts.join("&")}` : "";
+}
+/** OrderRejectionReason (openapi, docs.arcus.xyz; MISSING_MARK_PRICE: testnet changelog v1.8.12). */
+const REJECTION_CODES = {
+    UNDERCOLLATERALIZED: "MARGIN_INSUFFICIENT",
+    DUPLICATE_CLIENT_ID: "DUPLICATE_ORDER",
+    POSITION_TPSL_ALREADY_EXISTS: "DUPLICATE_ORDER",
+    ORDER_NOT_FOUND: "ORDER_NOT_FOUND",
+    ORDER_NOT_FOUND_FOR_MODIFY: "ORDER_NOT_FOUND",
+    POSITION_SIZE_CAP_EXCEEDED: "SIZE_TOO_LARGE",
+    OPEN_INTEREST_CAP_EXCEEDED: "SIZE_TOO_LARGE",
+    POST_ONLY_WOULD_CROSS: "ORDER_REJECTED",
+    IOC_CANCELED: "ORDER_REJECTED",
+    FOK_FAILED: "ORDER_REJECTED",
+    COULD_NOT_FILL: "ORDER_REJECTED",
+    FILL_WILL_EXCEED_TRADING_BOUND: "ORDER_REJECTED",
+    ORDER_WILL_TAKE_LIQUIDITY_DURING_MARKET_HALT: "ORDER_REJECTED",
+    REDUCE_ONLY_WOULD_INCREASE: "INVALID_PARAMS",
+    ENTRY_TPSL_CANNOT_BE_POSITION_TPSL: "INVALID_PARAMS",
+    SELF_TRADE: "RISK_VIOLATION",
+    OPEN_ORDER_CAP_EXCEEDED: "RISK_VIOLATION",
+    TOO_MANY_CLIENT_IDS: "RISK_VIOLATION",
+    MISSING_MARK_PRICE: "PRICE_STALE",
+    MODIFY_CHANGED_IMMUTABLE_FIELD: "INVALID_PARAMS",
+    MODIFY_ZERO_SIZE: "INVALID_PARAMS",
+    MODIFY_TPSL_NOT_SUPPORTED: "CAPABILITY_UNSUPPORTED",
+    MODIFY_SUPERSEDED_BY_CANCEL: "ORDER_REJECTED",
+    MODIFY_SIZE_ALREADY_FILLED: "ORDER_REJECTED",
+    MODIFY_WOULD_CROSS_OUTSIDE_RTH_TRADING_BOUNDARY: "ORDER_REJECTED",
+};
+const REJECTION_REMEDIATION = {
+    POST_ONLY_WOULD_CROSS: "The post-only (ALO) price would cross the book — move the price away from the touch or drop post-only",
+    REDUCE_ONLY_WOULD_INCREASE: "Reduce-only order would open or grow the position — check the side and position size",
+    POSITION_TPSL_ALREADY_EXISTS: "A position TP/SL of this kind already exists for the market — cancel it first (one TP and one SL per market)",
+    OPEN_ORDER_CAP_EXCEEDED: "Open-order cap reached — cancel resting orders first: perp trade cancel-all -e arcus",
+    TOO_MANY_CLIENT_IDS: "10,000 live client ids reached — cancel resting orders first",
+    SELF_TRADE: "The order would match your own resting order — cancel it or change the price",
+    MISSING_MARK_PRICE: "No live mark price for this market (oracle gap) — retry once pricing resumes",
+    MODIFY_TPSL_NOT_SUPPORTED: "TP/SL orders cannot be modified — cancel and place a new one",
+    MODIFY_SUPERSEDED_BY_CANCEL: "A pending cancel for this order won — the order is cancelled",
+    MODIFY_SIZE_ALREADY_FILLED: "The order was already filled up to the new size and has been cancelled",
+};
+/** setLeverage 422 rejectReason (SetLeverageRejectReason). */
+const LEVERAGE_REJECT_CODES = {
+    UNDERCOLLATERALIZED: { code: "MARGIN_INSUFFICIENT", remediation: "Lowering leverage would under-margin open positions — add collateral or reduce positions first" },
+    HAS_OPEN_POSITION: { code: "INVALID_PARAMS", remediation: "Isolated mode needs a flat market — close the position, then switch to isolated" },
+    INVALID_LEVERAGE: { code: "INVALID_PARAMS", remediation: "Leverage must be within [1, market max] (perp market list -e arcus)" },
+    UNKNOWN_MARKET: { code: "SYMBOL_NOT_FOUND", remediation: "List markets with: perp market list -e arcus" },
+};
+/** Map an Arcus rejectionReason (engine) to an error code. Unknown → EXCHANGE_ERROR. */
+export function arcusRejectionCode(reason) {
+    return (reason && REJECTION_CODES[reason]) || "EXCHANGE_ERROR";
+}
+/** PerpError for an engine rejectionReason; details carry `rejectionReason` for callers that branch on it. */
+export function arcusRejectionError(reason, message, details) {
+    const remediation = reason ? REJECTION_REMEDIATION[reason] : undefined;
+    return new PerpError(arcusRejectionCode(reason), message, {
+        ...details,
+        rejectionReason: reason ?? null,
+        ...(remediation !== undefined ? { remediation } : {}),
+    });
+}
+/** setLeverage rejection (HTTP 422 or a 200/REJECTED body) → PerpError. Unknown reason → EXCHANGE_ERROR. */
+export function arcusLeverageRejectError(reason, message, details) {
+    const hit = reason ? LEVERAGE_REJECT_CODES[reason] : undefined;
+    return new PerpError(hit ? hit.code : "EXCHANGE_ERROR", message, {
+        ...details,
+        rejectReason: reason ?? null,
+        ...(hit ? { remediation: hit.remediation } : {}),
+    });
+}
+/**
+ * HTTP 429 → RATE_LIMITED. Order writes carry `retryAfterMs` (exact) and
+ * `reason`; otherwise Retry-After (whole seconds). Docs: api-reference/rate-limits.
+ */
+export function arcusRateLimitedError(retryAfterHeader, text) {
+    let body = {};
+    try {
+        body = JSON.parse(text);
+    }
+    catch { /* non-JSON 429: header only */ }
+    const base = rateLimitedError("arcus", retryAfterHeader, text);
+    if (typeof body.retryAfterMs !== "number" && body.reason === undefined)
+        return base;
+    const reason = body.reason ?? null;
+    const hint = reason === "account_empty" ? "The subaccount trading pool is exhausted (drip: 1 action / 10 s) — slow the order loop"
+        : reason === "account_partial" ? "The subaccount trading pool cannot cover this charge — send a smaller batch"
+            : reason === "ip" ? "Per-IP read weight is exhausted — reduce non-order traffic from this IP"
+                : base.structured.remediation;
+    return new PerpError("RATE_LIMITED", `arcus: rate limited (HTTP 429${reason ? `, ${reason}` : ""})`, {
+        ...(typeof body.retryAfterMs === "number" ? { retryAfterMs: body.retryAfterMs } : base.structured.details?.retryAfterMs !== undefined ? { retryAfterMs: base.structured.details.retryAfterMs } : {}),
+        reason,
+        body: text.slice(0, 500),
+        remediation: hint,
+    });
+}
+function toPerpError(status, text, endpoint) {
+    let body = {};
+    try {
+        body = JSON.parse(text);
+    }
+    catch { /* non-JSON error page: message carries raw text */ }
+    const msg = body.error ?? text.slice(0, 200);
+    const details = { status, endpoint, body: text.slice(0, 500) };
+    const m = `Arcus ${endpoint}: ${msg}`;
+    const lower = msg.toLowerCase();
+    if (body.rejectionReason)
+        return arcusRejectionError(body.rejectionReason, m, details);
+    if (body.rejectReason)
+        return arcusLeverageRejectError(body.rejectReason, m, details);
+    if (body.errorType === "Tick")
+        return new PerpError("INVALID_TICK", m, details);
+    if (body.errorType === "ReduceOnly")
+        return new PerpError("INVALID_PARAMS", m, details);
+    if (status === 401 || body.errorType === "Unauthorized") {
+        return new PerpError("SIGNATURE_FAILED", m, {
+            ...details,
+            remediation: "Check the system clock (±30 s) and that the Arcus API key is registered and not expired: perp wallet agent approve arcus",
+        });
+    }
+    if (status === 403 || body.code === "GEO_RESTRICTED") {
+        return new PerpError("POLICY_DENIED", m, {
+            ...details,
+            remediation: lower.includes("whitelist")
+                ? "This address is not on the Arcus access whitelist — request access at https://arcus.xyz"
+                : "Arcus rejected the request for this address/region",
+        });
+    }
+    if (status === 404) {
+        if (lower.includes("no activity")) {
+            return new PerpError("DEPOSIT_REQUIRED", m, { ...details, remediation: "Deposit USDG into the Arcus account first" });
+        }
+        // "order" first: an order-lookup 404 message may also mention the market.
+        if (lower.includes("order"))
+            return new PerpError("ORDER_NOT_FOUND", m, details);
+        if (lower.includes("market"))
+            return new PerpError("SYMBOL_NOT_FOUND", m, details);
+        return new PerpError("EXCHANGE_ERROR", m, details);
+    }
+    if (status === 501)
+        return new PerpError("NOT_IMPLEMENTED", m, details);
+    if (status === 409)
+        return new PerpError("DUPLICATE_ORDER", m, details);
+    if (status >= 400 && status < 500)
+        return new PerpError("INVALID_PARAMS", m, details);
+    return new PerpError("EXCHANGE_ERROR", m, details);
+}
+export class ArcusClient {
+    network;
+    auth;
+    baseUrl;
+    rateKey;
+    constructor(network, auth) {
+        this.network = network;
+        this.auth = auth;
+        this.baseUrl = restUrl(network);
+        this.rateKey = `arcus:${network}`;
+    }
+    get hasAuth() { return this.auth !== null; }
+    requireAuth() {
+        if (!this.auth) {
+            throw new PerpError("NO_SIGNER_AVAILABLE", "Arcus: no API key configured for signed requests", {
+                remediation: "Register an agent key: perp wallet agent approve arcus",
+            });
+        }
+        return this.auth;
+    }
+    async acquire(endpoint) {
+        await acquireRate(this.rateKey, arcusVenue.rateLimit, endpoint);
+    }
+    /** Callers acquire the rate-limit slot first (signed requests do so BEFORE taking their timestamp). */
+    async send(method, url, endpoint, headers, body) {
+        // Timeout covers fetch + body read. A GET failure is definite (TIMEOUT /
+        // EXCHANGE_UNREACHABLE); a POST failure may have reached the venue → outcome
+        // unknown (ORDER_PENDING, never resubmit — design §12.3).
+        const signal = AbortSignal.timeout(TIMEOUT_MS);
+        let res;
+        let text;
+        try {
+            res = await fetch(url, {
+                method,
+                headers: body !== null ? { "Content-Type": "application/json", ...headers } : headers,
+                body,
+                signal,
+            });
+            text = await res.text();
+        }
+        catch (err) {
+            const reason = signal.aborted ? `timed out after ${TIMEOUT_MS}ms` : (err instanceof Error ? err.message : String(err));
+            if (method === "POST") {
+                throw orderOutcomeUnknown("arcus", endpoint, new Error(reason), "Do NOT resubmit — the request may have been applied. Check open orders, positions and balances on arcus");
+            }
+            throw new PerpError(signal.aborted ? "TIMEOUT" : "EXCHANGE_UNREACHABLE", `Arcus ${endpoint}: ${reason}`, { exchange: "arcus" });
+        }
+        if (res.status === 429)
+            throw arcusRateLimitedError(res.headers.get("retry-after"), text);
+        const pendingRemediation = "Do NOT resubmit — the request may have been applied. Check open orders, positions and balances on arcus";
+        // A POST answered 5xx (other than 501 Not Implemented) may have been applied before the error.
+        if (method === "POST" && res.status >= 500 && res.status !== 501) {
+            throw orderOutcomeUnknown("arcus", endpoint, new Error(`HTTP ${res.status}: ${text.slice(0, 200)}`), pendingRemediation);
+        }
+        if (!res.ok)
+            throw toPerpError(res.status, text, endpoint);
+        let data;
+        try {
+            data = text.length ? JSON.parse(text) : null;
+        }
+        catch {
+            // A 2xx POST with an unreadable body WAS accepted — what it did is unknown.
+            if (method === "POST")
+                throw orderOutcomeUnknown("arcus", endpoint, new Error(`unreadable response (HTTP ${res.status})`), pendingRemediation);
+            throw new PerpError("EXCHANGE_ERROR", `Arcus ${endpoint}: invalid JSON`, { body: text.slice(0, 500) });
+        }
+        return { status: res.status, data: data };
+    }
+    /** Public GET. `endpoint` is the rate-limit weight key. */
+    async get(path, endpoint, query = {}) {
+        await this.acquire(endpoint);
+        return (await this.send("GET", `${this.baseUrl}${path}${qs(query)}`, endpoint, {}, null)).data;
+    }
+    /** Unsigned POST (EIP-712 wallet-signed bodies: createApiKey / revokeApiKey / withdraw). */
+    async postUnsigned(path, endpoint, body) {
+        await this.acquire(endpoint);
+        return this.send("POST", `${this.baseUrl}${path}`, endpoint, {}, JSON.stringify(body));
+    }
+    /**
+     * Scheme-1 POST. The rate-limit slot is acquired first; only then is the
+     * timestamp `ctNs` taken and handed to `build`, which returns the typed-payload
+     * signature and the pre-serialized body (canonicalJson — the body's int64 ns
+     * `timestamp` exceeds Number precision and must be emitted from a bigint).
+     * `ctNs` becomes X-Timestamp; `?address=` carries the master address.
+     */
+    async postScheme1(path, endpoint, build) {
+        const auth = this.requireAuth();
+        await this.acquire(endpoint);
+        const ctNs = nowNs();
+        const { bodyJson, signatureHex } = await build(ctNs);
+        const url = `${this.baseUrl}${path}${qs({ address: auth.ownerAddress })}`;
+        return this.send("POST", url, endpoint, {
+            "X-API-Key": auth.apiKeyHex,
+            "X-Timestamp": ctNs.toString(),
+            "X-Signature": signatureHex,
+        }, bodyJson);
+    }
+    /** Scheme-2 POST: signs `ts + action + canonicalJson(body)` and sends that exact canonical body. */
+    async postScheme2(action, body) {
+        const auth = this.requireAuth();
+        await this.acquire(action);
+        const ts = nowNs();
+        const canonical = canonicalJson(body);
+        const sig = await signUtf8Hex(auth.sign, scheme2Message(ts, action, canonical));
+        const url = `${this.baseUrl}/v1/${action}${qs({ address: auth.ownerAddress })}`;
+        return this.send("POST", url, action, {
+            "X-API-Key": auth.apiKeyHex,
+            "X-Timestamp": ts.toString(),
+            "X-Signature": sig,
+        }, canonical);
+    }
+}

package/dist/exchanges/arcus/public.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Arcus public market data — GET /v1/markets (one call serves both markets
+ * and funding rates).
+ *
+ * Mapping notes:
+ * - symbol: `baseAsset` (plain ticker, e.g. "TSLA"); venueSymbol: display name
+ *   ("TSLA-USD") which is also the `market` key for l2OrderBook/trades/candles.
+ * - tickSize / stepSize: the top-level fields. `tickTiers` (per-price-band
+ *   placement grid) is NOT folded into VenueMarket — the signed integer price
+ *   always divides by the top-level tickSize; tiers only restrict which limit
+ *   prices are accepted. The adapter validates/aligns against the tier tick
+ *   (see tickForPrice) using the raw market.
+ * - maxLeverage: floor(1 / initialMarginFraction) (regular-hours IMF).
+ * - assetClass from `category`: CRYPTO → crypto, EQUITIES → equity,
+ *   FOREX → fx. COMMODITIES / INDICES listings on Arcus are ETFs (GLD, SLV,
+ *   USO, CPER, SPY, QQQ …) → "etf" when `fullAssetName` names an ETF/Trust/
+ *   Fund/Shares; otherwise commodity / index (canonical then comes only from the
+ *   explicit table).
+ * - session: only for markets with `regularTradingHours` (24/7 crypto → null).
+ *   underlyingOpen = !isOutsideRth; priceBand = off-hours trading bounds when
+ *   published; marginMultiplier = offHoursIMF / IMF.
+ * - funding: hourly (`fundingRate` is the per-hour fraction last charged);
+ *   `nextFundingAt` is Unix seconds.
+ * - tradable: status === "ONLINE".
+ */
+import type { AssetClass, VenueMarket } from "../venue-types.js";
+import type { VenuePublicData } from "../venue.js";
+import { ArcusClient } from "./client.js";
+export interface ArcusTickTier {
+    upToPrice?: string;
+    tick: string;
+}
+export interface ArcusRawMarket {
+    marketDisplayName: string;
+    fullAssetName?: string;
+    marketId: number;
+    status: string;
+    baseAsset: string;
+    quoteAsset: string;
+    tickSize: string;
+    stepSize: string;
+    tickTiers: ArcusTickTier[] | null;
+    minOrderNotional: string | null;
+    minOrderSize: string | null;
+    maxOrderSize: string | null;
+    oraclePrice?: string;
+    markPrice?: string;
+    fundingRate?: string;
+    nextFundingAt?: number;
+    volume24h?: string;
+    volume24hNotional?: string;
+    openInterest?: string;
+    initialMarginFraction?: string;
+    maintenanceMarginFraction?: string;
+    offHoursInitialMarginFraction?: string;
+    regularTradingHours: unknown | null;
+    isOutsideRth: boolean;
+    upperTradingBound: string | null;
+    lowerTradingBound: string | null;
+    category: string;
+}
+export declare function fetchArcusRawMarkets(client: ArcusClient): Promise<ArcusRawMarket[]>;
+export declare function arcusAssetClass(m: ArcusRawMarket): AssetClass;
+export declare function toArcusVenueMarket(m: ArcusRawMarket): VenueMarket;
+export declare const arcusPublicData: VenuePublicData;