> ## Documentation Index > Fetch the complete documentation index at: https://docs.arcus.xyz/llms.txt > Use this file to discover all available pages before exploring further. # List notifications for an address > Returns the most recent notifications for `address`, newest-first. Returns the most recent notifications for `address`, newest-first. Public — no `X-API-Key` and no signature required. Use `before_ns` to page backwards in time by passing the `createdAtNs` of the oldest row from the previous response. The inbox is fed by an in-process Kafka consumer in `api-meta` that decodes `AccountUpdate` SBE messages from `core-updates` and surfaces three event families: terminal resting fills (maker side, `OrderState.Filled`), liquidations, and TP/SL triggers. Notifications have a 30-day TTL. **Opt-in side effect.** The first call to this endpoint for an `address` enrolls it as a notifications subscriber. Until the first call, the Kafka consumer does NOT store any notifications for that address (this keeps inactive accounts out of the table). Once enrolled, notifications start accumulating from the next matching event onwards; events that happened before enrollment are not backfilled. The enrollment write is best-effort — a transient failure logs + metricks but does NOT fail the inbox read. ## OpenAPI ````yaml /api-reference/openapi.yml get /v1/api-meta/notifications openapi: 3.1.0 info: title: Arcus API version: 1.0.0 description: > REST API for the Arcus exchange. Provides endpoints for order management, market data, and account onboarding. ## Coming soon (not implemented yet) The following features are declared in this spec (or implied by it) but are **not yet live** on the gateway or matching engine. Schemas and endpoints may be present so clients can wire against the final shape, but today the gateway returns `501 Not Implemented` or the feature is simply absent. Do not depend on these in production until they are announced as live. - **Modify order** (`POST /modifyOrder`) — reduce-only modifications will preserve queue priority; any change that moves the price level or increases size will be handled as an atomic cancel + replace (queue priority is lost). Currently returns `501 Not Implemented`. - **Batch modify order** (`POST /batchModifyOrders`) — same semantics as `modifyOrder`, applied atomically per item. Currently returns `501 Not Implemented`. - **Next predicted funding rate** — the predicted funding rate for the upcoming interval is not yet exposed on `GET /markets` or the markets WebSocket channel. Only the current realized rate is available today. - **Funding rate calculations** — the authoritative calculation methodology (premium sampling window, interest-rate component, clamping, payment schedule) is still being finalized and is not documented here yet. - **Advanced order types** — trailing stop, stop-limit, OCO, and other conditional / bracket order variants beyond plain `LIMIT` and `MARKET` are not yet supported. ## Authentication Order management and credential-creating endpoints require **three** request headers: - `X-API-Key` — hex-encoded Ed25519 public key (64 chars). The public key *is* the API key. Obtain/register one via `POST /createApiKey`. - `X-Timestamp` — Unix time in **nanoseconds** as a decimal string (e.g. `"1713825891591000000"`). Millisecond or second epochs are rejected with `401 Unauthorized`. Must be within ±30,000 ms (`MaxTimestampDriftMs`, the drift window stays configured in milliseconds) of server wall-clock; otherwise the request is rejected with `401 Unauthorized`. - `X-Signature` — lowercase hex-encoded Ed25519 signature (128 chars). **Single-order endpoints** (`placeOrder`, `cancelOrder`, `modifyOrder`) use the **ordersign typed canonical payload** as the signing message — a compact, key-sorted JSON object with engine-native integer values. The payload is NOT the raw HTTP body; it is built from the parsed request fields: ``` placeOrder: {"ad":"0x…","ai":N,[,"c":"…"],"ct":N,"g":N,"m":N,"op":1,"p":N,"q":N,"r":0|1,"s":N,"t":N,"v":1} cancelOrder: {"ad":"0x…","ai":N,[,"c":"…"],"ct":N,[,"id":"…"],"m":N,"op":2,"v":1} modifyOrder: {"ad":"0x…","ai":N,[,"c":"…"],"ct":N,[,"id":"…"],"m":N,"op":3,"p":N,"q":N,"v":1} ``` `ct` in the payload must equal `X-Timestamp`. Integer values `p`, `q` etc. are engine-native ticks/quantums, not human-readable decimals. Keys in brackets are conditional (omitted when empty). `op` is the operation enum: `1`=place, `2`=cancel, `3`=modify, `4`=placeUntriggered (TPSL). See the `ordersign` package for full field definitions and reference signing code. **Batch endpoints do not use this header** — see below. - **Batch endpoints are signed per order — no `X-Signature`.** `POST /batchPlaceOrders` and `POST /batchCancelOrders` require `X-API-Key` + `X-Timestamp` only; the gateway does **not** verify an envelope `X-Signature` for these routes. Instead, each element of the `orders` / `cancels` array embeds its own `"signature"` field — a 128-hex Ed25519 signature over the **ordersign typed canonical payload** for that operation: - Plain `orders` elements (no `tpsl_type`) use `op=1`. - TPSL / conditional `orders` elements (with `tpsl_type`) use `op=4` (`OpPlaceUntriggered`) — same field set as `op=1` but a different `op` value, preventing replay of a TPSL signature as a plain placeOrder. - `cancels` elements use `op=2`. The `ct` field inside every element's payload must equal the shared `X-Timestamp` header value. The whole batch consumes a single replay slot. Read-only endpoints (`GET /openOrders`, `GET /fills`, etc.) require only `X-API-Key`. In relaxed local development the gateway may run with signatures disabled; the OpenAPI `security` blocks list `signedRequest` (the three-header AND) or `{}` (empty) to reflect that. ## Account-scoped requests Public account info reads such as fills, positions, orders, open orders, and account snapshots require `address` as a **query parameter**. Signed order management requests also require `address`, and it must match the master Ethereum address returned for that API key from `POST /createApiKey`. WebSocket `placeOrder` / `cancel` / `batchPlaceOrders` / `batchCancelOrders` / `modifyOrder` use the same value in the JSON payload field `address`. ## Order execution is asynchronous `POST /placeOrder`, `POST /cancelOrder`, `POST /batchPlaceOrders`, and `POST /batchCancelOrders` are asynchronous. They return either: - **`202 Accepted`** — the common case. The signed request was validated by the gateway and forwarded to the matching engine; the body does **not** carry the order's terminal state. - **`200 OK`** — returned only when the gateway already has definitive state for the request by the time it responds (the body's `status` reflects that state, e.g. `OPEN` / `FILLED` / `CANCELED` / `REJECTED`). Clients should treat this as best-effort enrichment and not rely on it. In both cases the body echoes `orderId` / `clientId` so callers can correlate WebSocket events with the request. To observe the full order lifecycle (`OPEN`, `FILLED`, `CANCELED`, `REJECTED`, fills, rejection reasons, etc.) clients **must** subscribe to the `orders` WebSocket channel (and `userFills` for trade-level events). Treat both the `202` and `200` HTTP bodies as request acknowledgements; all definitive state lives on the WebSocket. `POST /modifyOrder` and `POST /batchModifyOrders` are **not implemented yet** — the schemas are declared so consumers can wire against the final shape, but the gateway returns `501 Not Implemented` today. When live, they will follow the same async contract. ## Order rejection reasons When the matching engine (go-core) rejects an order, the resulting `AccountUpdate` event (delivered over the WebSocket `account` channel with `type: REJECTED`) carries a `rejectionReason` enum. The same value may also appear on HTTP `OrderResponse` / `CancelOrderResponse` bodies that resolved to definitive state before returning (the `200` path described above). The complete set of reasons go-core can emit today is: | Value | Meaning | |------------------------------|-------------------------------------------------------------------------| | `POST_ONLY_WOULD_CROSS` | Post-only order was rejected because it would have crossed the book and taken liquidity. | | `SELF_TRADE` | Order would have matched against another resting order belonging to the same account; self-trade prevention rejected it. | | `UNDERCOLLATERALIZED` | Account has insufficient free collateral / margin to support the order. | | `COULD_NOT_FILL` | Generic "could not fill" outcome. Legacy reason — prefer the IOC/FOK-specific values below for time-in-force-driven cancels. | | `IOC_CANCELED` | An `IMMEDIATE_OR_CANCEL` order produced zero fills against the book and was canceled. | | `FOK_FAILED` | A `FILL_OR_KILL` order could not be filled in full at submission and was canceled in its entirety. | | `REDUCE_ONLY_WOULD_INCREASE` | A `reduceOnly` order was rejected because executing it would have opened or increased the account's position rather than reducing it. | | `TOO_MANY_CLIENT_IDS` | Account already has 10,000 live `clientId`s (the per-account maximum). Cancel an existing order or wait for one to reach a terminal state to free a slot. | | `DUPLICATE_CLIENT_ID` | The `clientId` already maps to a live order on this account. Cancel the prior order (or use atomic modify via `placeAndCancel`) before reusing the same `clientId`. | See the `RejectionReason` schema for the canonical enum. ## Rate limiting Rate-limited endpoints return `429 Too Many Requests` carrying two retry-after signals: - `Retry-After` HTTP header (integer seconds, RFC 7231 compliant). - `retryAfterMs` field in the JSON body — precise milliseconds. The body also carries a typed `reason` indicating which layer rejected (`ip`, `account_empty`, `account_partial`). See `RateLimitedError` for the schema and `TooManyRequests` for the behavioral contract. Partner market-makers may be added to the bypass allowlist via the `RATELIMIT_BYPASS_ADDRESSES` server-side configuration (per environment). Allowlisted addresses skip rate-limit charging entirely and never receive a 429 from this layer. servers: - url: https://api.testnet.arcus.xyz description: Testnet - url: https://api.arcus.xyz description: Mainnet security: [] tags: - name: Onboarding description: Account and API key management. - name: Public description: >- Unauthenticated endpoints — market data, health checks, and account-scoped info reads. - name: Exchange description: > Signed order management endpoints (all are HTTP `POST`). Every request must carry the full header triple `X-API-Key` + `X-Timestamp` + `X-Signature` where `X-Signature` is an Ed25519 signature over the operation-specific signing message: `placeOrder`, `cancelOrder`, and `modifyOrder` sign the ordersign typed canonical payload (the JSON object itself, no prefix), while `cancelAllOrders` and `setLeverage` use the legacy `X-Timestamp + ACTION + canonicalJSON(body)` message (ACTION = the final camelCase path segment; the HTTP method is not signed). `X-Timestamp` is a Unix nanosecond epoch (decimal string) and must be within ±30,000 ms of server wall-clock. See the top-level **Authentication** section for full details. These endpoints also require query parameter `address` matching the key's master Ethereum address. - name: Referral description: > Affiliate / referral program endpoints. Mutating endpoints (`POST`) require the full Ed25519 signature triple and the body `address` must match the API key's master Ethereum address. Read endpoints (`GET`) are public and scoped by `?address=`. - name: Meta description: > Product / UX-level APIs served by the `api-meta` service. These live behind the same host as the rest of the API but are routed (via the ALB path rule on `/v1/api-meta/*`) to a separate deployment with its own ScyllaDB keyspace and its own deployment lifecycle. They share the same `X-API-Key` + Ed25519 signature scheme as Exchange endpoints; the signed `REQUEST_PATH` includes the `/v1/api-meta/...` prefix verbatim. - name: UserPreferences description: > Per-master-wallet preference store (favorited markets, dashboard layouts, theme, language, …). Reads are public and scoped by `?address=`; writes (PATCH / DELETE) require an Ed25519 signature and are bound to the address registered to `X-API-Key`. See `UserPreferenceKey` for the known keys and `UserPreferenceValue` for the type system. - name: MarketMetadata description: > Curated reference data for markets (company profile, branding, headline financials, …) refreshed from the upstream ticker feed. Reads are public; freshness is bounded by the per-row `ingestedAt` returned in the response envelope. - name: Notifications description: > Per-master-wallet inbox of "unseen events" surfaced from the matching engine: terminal resting-order fills (maker side, fully filled), liquidations, and TP/SL triggers. Reads are public and scoped by `?address=`; the `:markSeen` write requires an Ed25519 signature and is bound to the address registered to `X-API-Key`. Notifications expire after 30 days. paths: /v1/api-meta/notifications: get: tags: - Notifications summary: List notifications for an address description: Returns the most recent notifications for `address`, newest-first. operationId: getNotifications parameters: - $ref: '#/components/parameters/AddressQuery' - name: limit in: query required: false schema: type: integer format: int32 minimum: 1 maximum: 200 default: 50 description: Maximum rows to return. Defaults to 50, capped at 200. - name: before_ns in: query required: false schema: type: string pattern: ^[0-9]+$ description: > Paging cursor as a decimal string: only rows with `createdAtNs < before_ns` are returned. Omit for the first page, then pass the `createdAtNs` of the oldest row in the previous response verbatim (string, to avoid precision loss). responses: '200': description: Notifications (possibly empty array). content: application/json: schema: $ref: '#/components/schemas/NotificationsResponse' '400': description: Missing or malformed `address`. content: application/json: schema: $ref: '#/components/schemas/error' '503': description: Backing store unavailable. Caller should retry with backoff. content: application/json: schema: $ref: '#/components/schemas/error' components: parameters: AddressQuery: name: address in: query required: true schema: $ref: '#/components/schemas/EthereumAddressHex' description: > Master Ethereum address for this API key (must match `address` from `POST /createApiKey` for the same key). Required on REST for account-scoped reads and for place/cancel. Invalid hex → 400; mismatch with key → 403. schemas: NotificationsResponse: type: object required: - address - notifications properties: address: $ref: '#/components/schemas/EthereumAddressHex' notifications: type: array items: $ref: '#/components/schemas/Notification' error: type: object required: - error properties: error: type: string description: Human-readable error message. examples: - Invalid request body code: type: string description: > Machine-readable error code for generic (non-order) rejections. Present on geo-restriction blocks; clients should key product-availability UI off this rather than the human `error` string. | Value | Meaning | |------------------|---------| | `GEO_RESTRICTED` | The action is not available from the caller's country/region for this product (perps and/or spot). Reads remain available; only state-changing actions are blocked. | enum: - GEO_RESTRICTED errorSource: type: string description: > Scopes the failure to a specific operation. Present on structured order errors (place / cancel / modify flows); absent on generic HTTP errors. enum: - Order - Cancel errorType: type: string description: > Machine-readable reason for the API-layer rejection. Present alongside `errorSource` on structured order errors; absent on generic HTTP errors. | Value | Meaning | |-------------------|---------| | `Tick` | Price or size does not align to the market's tick size / step size. | | `InvalidRequest` | A request field failed validation (bad address, unknown market, invalid enum, etc.). TPSL-specific causes: `stopPrice` required when `tpslType` is set; `tpslType` must be `STOP_LOSS` or `TAKE_PROFIT`; `reduceOnly` must be `true` for TPSL orders; trigger price must not sit on the wrong side of the current oracle (would fire immediately); batch grouping/shape constraints violated (wrong order count, missing or duplicate `tpslType` legs). | | `OracleDeviation` | The order's price deviates from the current oracle price by more than the allowed threshold. Adjust the price closer to the oracle and resubmit. | | `ReduceOnly` | A reduce-only order was rejected because filling it would open or increase the account's position rather than reduce it. | | `Unavailable` | The requested operation (place / cancel) is temporarily disabled. | | `Unauthorized` | API key or trading-identity check failed. | | `Forbidden` | The authenticated key is not permitted to perform the requested operation. | | `NotImplemented` | The requested capability is not yet available on this path (e.g. TPSL over WebSocket). | | `Transmission` | The gateway accepted and validated the request but could not deliver it to the matching engine. Retry. | | `Internal` | Unexpected gateway-side failure unrelated to transmission. | enum: - Tick - InvalidRequest - OracleDeviation - ReduceOnly - Unavailable - Unauthorized - Forbidden - NotImplemented - Transmission - Internal rejectionReason: type: string description: > Machine-readable engine-level rejection code. Present on `OrderResponse` / `BatchOrderItemResponse` when `status` is `REJECTED` on the synchronous `200` path (i.e. the gateway already had a definitive engine reject before responding). Absent on `202` responses and on HTTP error bodies — in those cases rejection reasons are delivered asynchronously via the `orders` WebSocket channel. Mirror of the canonical `RejectionReason` schema in `openapi.yaml` — keep the two in lockstep (and the hardcoded list in `sdks/python/scripts/post_process_models.py`). | Value | Meaning | |------------------------------------|---------| | `POST_ONLY_WOULD_CROSS` | Post-only order would have crossed the book and taken liquidity. | | `SELF_TRADE` | Order would match against the account's own resting order; blocked by self-trade prevention. | | `UNDERCOLLATERALIZED` | Account has insufficient free collateral / margin to support the order. | | `COULD_NOT_FILL` | Generic "could not fill" (legacy; prefer `IOC_CANCELED` / `FOK_FAILED`). | | `IOC_CANCELED` | IOC order produced zero fills and was canceled. | | `FOK_FAILED` | FOK order could not be fully filled at submission. | | `REDUCE_ONLY_WOULD_INCREASE` | reduce-only order would have opened or increased the position. | | `TOO_MANY_CLIENT_IDS` | Account already has 10,000 live `clientId`s (the per-account maximum). Cancel or let existing orders reach a terminal state to free slots before placing new ones with distinct `clientId`s. | | `DUPLICATE_CLIENT_ID` | Account already has an open order with the same `clientId`. | | `POSITION_TPSL_ALREADY_EXISTS` | A position-level TPSL of the same trigger class (TP or SL) already exists for this account+market. At most one TP and one SL per market. | | `ENTRY_TPSL_CANNOT_BE_POSITION_TPSL` | A TPSL bound to an entry order (`parentOrderId` set) cannot also be a position-level TPSL; entry-linked TPSLs are sized partial legs. | | `OPEN_ORDER_CAP_EXCEEDED` | Account has reached its per-account open-order cap; cancel a resting order or let one reach a terminal state before placing another. | | `ORDER_WILL_TAKE_LIQUIDITY_DURING_MARKET_HALT` | Outside regular trading hours, a crossing order would have taken liquidity past the off-hours trading bound while the market is halted at that band. | | `ORDER_NOT_FOUND` | `cancelOrder` referenced an order not on the orderbook (already filled, canceled, never placed, or owned by another account). | | `ORDER_NOT_FOUND_FOR_MODIFY` | `modifyOrder` referenced an order not on the regular orderbook; TPSL and untriggered orders cannot be modified. | | `MODIFY_CHANGED_IMMUTABLE_FIELD` | `modifyOrder` attempted to change an immutable field (`side`, `timeInForce`, `reduceOnly`, or `orderType`). | | `MODIFY_ZERO_SIZE` | `modifyOrder` specified a new size of zero or less. | enum: - POST_ONLY_WOULD_CROSS - SELF_TRADE - UNDERCOLLATERALIZED - COULD_NOT_FILL - IOC_CANCELED - FOK_FAILED - REDUCE_ONLY_WOULD_INCREASE - TOO_MANY_CLIENT_IDS - DUPLICATE_CLIENT_ID - POSITION_TPSL_ALREADY_EXISTS - ENTRY_TPSL_CANNOT_BE_POSITION_TPSL - OPEN_ORDER_CAP_EXCEEDED - ORDER_WILL_TAKE_LIQUIDITY_DURING_MARKET_HALT - ORDER_NOT_FOUND - ORDER_NOT_FOUND_FOR_MODIFY - MODIFY_CHANGED_IMMUTABLE_FIELD - MODIFY_ZERO_SIZE EthereumAddressHex: type: string pattern: ^(0x|0X)?[0-9a-fA-F]{40}$ description: > 20-byte EVM address as hex: optional `0x` or `0X` prefix and exactly 40 hexadecimal digits. API responses normalize to lowercase `a`–`f` after `0x`. Notification: type: object required: - createdAtNs - notificationId - type - subaccountIdx - marketId - seen - payload properties: createdAtNs: type: string pattern: ^[0-9]+$ description: > Engine timestamp in nanoseconds, as a decimal **string**. The value exceeds 2^53, so it is serialized as a string to avoid precision loss in JS clients (where all numbers are float64). Pass it back verbatim as the `before_ns` cursor and inside `ids[].created_at_ns` on `:markSeen`; a truncated value targets the wrong clustering key. notificationId: type: string description: >- UUID. Deterministic across consumer replays (`(gsn, outputSubSeq, accountId, type)` → UUIDv5). type: $ref: '#/components/schemas/NotificationType' subaccountIdx: type: integer format: int32 marketId: type: integer format: int32 seen: type: boolean payload: oneOf: - $ref: '#/components/schemas/NotificationFillPayload' - $ref: '#/components/schemas/NotificationLiquidationPayload' - $ref: '#/components/schemas/NotificationTPSLPayload' - $ref: '#/components/schemas/NotificationTransferPayload' NotificationType: type: string description: > Notification family. Drives which payload shape is carried in `payload`. - `resting_fill`: a maker order took to `OrderState.Filled` (partial maker fills are intentionally not surfaced). - `liquidation`: the user's position was force-closed by the engine's liquidation pass. - `tpsl_triggered`: a TP/SL order's trigger condition fired. - `deposit`: an on-chain deposit credited the trading account. Not market-scoped — the enclosing `marketId` is 0. - `withdrawal`: a withdrawal debited the trading account. Not market-scoped — the enclosing `marketId` is 0. enum: - resting_fill - liquidation - tpsl_triggered - deposit - withdrawal NotificationFillPayload: type: object description: >- Payload for `resting_fill` notifications. All sizes/prices are raw integer quantums/ticks. required: - marketId - subaccountIdx - side - makerOrderId - fillSize - fillPrice - fee properties: marketId: type: integer format: int32 subaccountIdx: type: integer format: int32 minimum: 0 maximum: 255 side: type: integer format: int32 description: SBE Side enum (0=Unknown, 1=Buy, 2=Sell). makerOrderId: type: string fillSize: type: integer format: int64 fillPrice: type: integer format: int64 fee: type: integer format: int64 positionEffect: type: string enum: - OPEN_LONG - OPEN_SHORT - ADD_LONG - ADD_SHORT - CLOSE_LONG - CLOSE_SHORT - FLIP_LONG_TO_SHORT - FLIP_SHORT_TO_LONG description: > How this maker fill changed the account's position in marketId. Absent on rows written before this field was introduced. NotificationLiquidationPayload: type: object required: - marketId - subaccountIdx - side - size - fillPrice properties: marketId: type: integer format: int32 subaccountIdx: type: integer format: int32 side: type: integer format: int32 size: type: integer format: int64 fillPrice: type: integer format: int64 NotificationTPSLPayload: type: object required: - marketId - subaccountIdx - side - orderId - triggerPrice - tpslType properties: marketId: type: integer format: int32 subaccountIdx: type: integer format: int32 side: type: integer format: int32 orderId: type: string triggerPrice: type: integer format: int64 tpslType: type: integer format: int32 description: 0=StopLimit, 1=StopMarket, 2=TakeProfit, 3=TakeProfitMarket. parentOrderId: type: string description: Set when the TPSL is bound to a parent entry order. NotificationTransferPayload: type: object description: > Payload for `deposit` and `withdrawal` notifications. These events are not market-scoped, so the enclosing `Notification.marketId` is 0. Amounts are raw quote quantums; the frontend converts using the quote-asset decimals. required: - subaccountIdx - amount - netQuoteBalance properties: subaccountIdx: type: integer format: int32 minimum: 0 maximum: 255 amount: type: integer format: int64 description: > Transfer amount in quote quantums (always positive; the notification `type` distinguishes a credit from a debit). netQuoteBalance: type: integer format: int64 description: > The perspective account's net quote balance after the transfer, in quote quantums. operationId: type: string description: > Transfer id, matching the `eventId` go-socks emits on `accountTransferUpdates`, so a client can correlate the inbox row with the live event. ````