Skip to main content
GET
/
v1
/
api-meta
/
notifications
List notifications for an address
curl --request GET \
  --url https://api.testnet.arcus.xyz/v1/api-meta/notifications
{
  "address": "<string>",
  "notifications": [
    {
      "createdAtNs": "<string>",
      "notificationId": "<string>",
      "subaccountIdx": 123,
      "marketId": 123,
      "seen": true,
      "payload": {
        "marketId": 123,
        "subaccountIdx": 127,
        "side": 123,
        "makerOrderId": "<string>",
        "fillSize": 123,
        "fillPrice": 123,
        "fee": 123
      }
    }
  ]
}
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.

Query Parameters

​
address
string
required

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.

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.

Pattern: ^(0x|0X)?[0-9a-fA-F]{40}$
​
limit
integer<int32>
default:50

Maximum rows to return. Defaults to 50, capped at 200.

Required range: 1 <= x <= 200
​
before_ns
string

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).

Pattern: ^[0-9]+$

Response

Notifications (possibly empty array).

​
address
string
required

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.

Pattern: ^(0x|0X)?[0-9a-fA-F]{40}$
​
notifications
object[]
required