Balance and transfer API reference

Request body

{
  "transfer_id": "order_123",
  "scene": "spend",
  "background_completion": true,
  "meta": { "order_id": "order_123" },
  "from_accounts": [{
    "account_id": "buyer_42",
    "asset": "points",
    "amount": "100",
    "action": "spend",
    "allow_overdraft": true
  }],
  "to_accounts": [
    { "account_id": "seller_7", "asset": "points", "amount": "90", "action": "spend" },
    { "account_id": "-2", "asset": "points", "amount": "10", "action": "spend" }
  ]
}

Success

{
  "code": "ok",
  "message": "success",
  "data": null
}

The caller already owns transfer_id, so a successful create response does not repeat it. Persist the ID and scene before sending and use them for reads and exact retries.

The expire_at value is an exclusive boundary. With background_completion enabled, durable source work may finish before the destination side. A network timeout is uncertain: directly retry the exact original request with the same ID and scene.

{
  "transfer_id": "order_123",
  "scene": "spend"
}

{
  "code": "ok",
  "message": "success",
  "data": null
}

Reversal is an entire-transfer operation. XferAPI applies inverse balance changes and moves the existing records to their reversal state. Repeating the same reversal is idempotent.

Use any syntactically valid transfer ID. Prefixes such as adj_ and sys_ carry no special semantics. Reversal validates lowercase snake_case scene syntax without requiring the scene to remain in the current configuration, but the exact XferAPI-managed scene sys_expire cannot be submitted.

A reversal may arrive before the matching transfer. In that case XferAPI records an empty reversal tombstone, and a later transfer with the same ID and scene is not allowed to execute.

Filter by transfer_id, scene, status, or an inclusive updated_at time window. The list includes XferAPI-generated expiration recycling transfers with scene sys_expire; that scene is also valid in read filters. start_time and end_time are Unix seconds, and the complete end_time second is included. page defaults to 1, page_size defaults to 20 and accepts 1–100, and the response includes top-level total, page, and page_size. Results use a stable newest-first order with a deterministic tie-breaker.

{
  "code": "ok",
  "message": "success",
  "data": {
    "points": {
      "current": "40",
      "future": "80",
      "permanent": "40",
      "batches": [
        { "amount": "80", "start_at": 1798761600, "expire_at": 0, "active": false }
      ]
    }
  }
}

{
  "code": "ok",
  "message": "success",
  "data": {
    "current": "40",
    "future": "80",
    "permanent": "40",
    "batches": [
      { "amount": "80", "start_at": 1798761600, "expire_at": 0, "active": false }
    ]
  }
}

The all-assets route returns data as an object keyed by asset. Use /v1/accounts/member_42/assets/points when you need one asset only; its data is the balance value directly and does not repeat asset. Every stored account-asset record remains present even when all balance totals are zero. Object property order is not contractual. Amounts are signed 64-bit integers encoded as decimal strings, so JavaScript callers can convert them directly to BigInt without losing precision.

For each ordinary source account and asset, XferAPI selects spendable value at the single server time captured for the Transfer. Batches that have not started or have reached their exclusive expire_at boundary are not spendable. Among active batches with an expiration, XferAPI spends the earliest expire_at first, then uses permanent balance. A source entry cannot select a specific batch, and relative order among batches with the same expire_at is not part of the API contract.

{
  "account_ids": ["member_42", "member_43"],
  "assets": ["points", "credits"]
}

{
  "code": "ok",
  "message": "success",
  "data": {
    "member_42": {
      "points": {
        "current": "100",
        "future": "20",
        "permanent": "80",
        "batches": [
          { "amount": "20", "start_at": 1798761600, "expire_at": 0, "active": false }
        ]
      }
    }
  }
}

The response data is keyed first by account ID and then by asset, using the same balance value as the individual reads without repeated account_id or asset fields. account_ids is required and accepts 1–100 unique valid IDs. assets is optional: omit it to read every stored asset, or provide 1–100 unique lowercase vocabulary codes to return only matching rows. Requested accounts with no matching stored account-asset record are omitted instead of receiving an empty object. A matching stored record remains present even when all balance totals are zero. JSON object property order is not contractual. Empty arrays, excess items, duplicates, or invalid values return invalid_request; malformed JSON, assets: null, or unknown fields return invalid_request_body.

{
  "code": "ok",
  "message": "success",
  "data": [{
    "account_id": "seller_7",
    "transfer_id": "order_123",
    "scene": "spend",
    "direction": "credit",
    "transfer_status": "posted",
    "amount": "90",
    "asset": "points",
    "action": "spend",
    "meta": { "order_id": "order_123" },
    "created_at": 1784188800,
    "updated_at": 1784188800
  }],
  "total": 1,
  "page": 1,
  "page_size": 20
}

direction is credit or debit. transfer_status is posted, reversed, or empty_reversal. Filter by transfer_id, status, asset, scene, direction, or action. Pagination defaults to page 1 with 20 items, accepts 1–100 items per page, and returns invalid_request for an invalid page value.

This endpoint returns the same record shape and filter vocabulary as account activity, but spans every account in the ledger. It includes XferAPI-generated expiration recycling records with scene sys_expire, including the system account 0 side of that movement; these are normal durable business-history entries, not hidden maintenance rows. Prefer /v1/accounts/{account_id}/records for a user or account history view; use the ledger-wide feed only when the workflow genuinely needs cross-account records.

{
  "code": "ok",
  "message": "success",
  "data": {
    "actions": {
      "top_up": "Top up",
      "spend": "Spend",
      "refund": ""
    },
    "scenes": {
      "top_up": "Top up",
      "spend": "Spend",
      "promotion": ""
    },
    "assets": {
      "points": "Points",
      "credits": ""
    },
    "platform_accounts": [
      { "account_id": "-1", "name": "Top-up account", "length": 1, "status": "active" },
      { "account_id": "-2", "name": "Spending account", "length": 1, "status": "active" }
    ]
  }
}

actions, scenes, and assets are JSON objects whose property names are configured codes and whose values are display descriptions. This supports direct lookup such as data.actions[action]. A configured code with no description uses an empty string, for example "refund": ""; a vocabulary with no entries is {}.

JSON object property order is not part of the API contract. Do not infer Console configuration order or business priority by iterating these objects; sort codes explicitly when presentation order matters. Transfers may use only codes already configured on the selected ledger. The generated sys_expire scene is intentionally not user-configurable and does not need to appear in this map, while Transfer and Record reads still return and filter it normally.

platform_accounts remains a list because every item defines a negative-ID range with fields such as account_id, length, and status. The inclusive range is [account_id - length + 1, account_id], and length must be an integer from 1 through 20. Sending the entry ID lets XferAPI select a deterministic bucket; sending another ID inside the configured range uses that exact bucket. Disabled ranges remain visible for interpreting history but reject new transfer entries.