Answers about the balance API

XferAPI is a balance and ledger API for app-defined credits, points, coins, and other units. It stores accounts and executes balanced, traceable transfers.

No. It does not collect payments, custody funds or crypto, provide exchange, or settle external currency.

Yes. The standard product is an XferAPI-operated HTTPS API and management console.

The hosted XferAPI service currently operates in the United States. If you have data residency, latency, or regional deployment requirements, contact [email protected] to discuss options.

Yes, through contact sales. XferAPI provides deployment, upgrades, and service in an agreed private environment under a managed commercial engagement.

Yes. As of July 2026, XferAPI and its production predecessor are used by more than 100 organizations, from small businesses to large enterprises. In aggregate, they have completed more than 464 million successful balance transfers and moved over 300 billion customer-defined units. These figures include managed private deployments; they are not hosted-service-only metrics, payment volume, or monetary value. Organization identities and individual usage are not disclosed.

XferAPI evolved from a predecessor ledger system that operated in production for 3.5 years. Across the production reconciliation records retained for that system, no reconciliation discrepancy was identified during that period, and its persisted transfer and account records supported routine reconciliation and audit review. This describes the predecessor system; it is not current Hosted-service uptime, an availability commitment, an SLA, or independent audit assurance.

Free, Basic, Pro, and Max workspaces can create 2, 5, 20, and 50 ledgers respectively. Enterprise capacity is agreed separately. Every ledger counts, including a disabled ledger.

Each ledger can add 2, 5, 10, or 20 additional asset codes on Free, Basic, Pro, or Max. The exact built-in points code does not count. A ledger that omits points does not receive a hidden free slot. Enterprise capacity is custom.

Free, Basic, Pro, and Max include 3, 10, 25, and 50 additional platform account definitions per ledger. The built-in -1 and -2 definitions do not count, and system account 0 is not a platform account. Each range counts once and may contain 1–20 IDs. Enterprise capacity is custom.

They remain operational. Existing workspaces, ledgers, assets, platform account definitions, and complete ranges can still be used, queried, edited, reordered, enabled, disabled, and re-enabled. XferAPI blocks only another creation while the relevant current-plan limit is reached. Traffic quota, rate, burst, and entries per transfer change when the downgrade takes effect.

A user may create up to two Free workspaces they own. Workspaces joined only as a member do not count. If paid workspaces later downgrade and leave the owner above two, those workspaces keep working; the owner simply cannot create another Free workspace while at or above the limit.

The caller-owned transfer ID and scene identify one operation inside a ledger. Keep that pair and the complete payload stable for concurrent delivery and exact retries of the same operation.

Yes. A transfer can be N-to-M as long as source and destination totals match independently for every asset.

For a timeout, disconnect, invalid or missing envelope, internal_error, service_unavailable, or transfer_state_conflict, resend the exact original transfer ID, scene, and payload directly. Do not create a new ID or make a read request first.

For POST /v1/transfers, insufficient_balance and execution-time amount_out_of_range are the terminal transaction failure codes. The original ID-and-scene pair can never later succeed, so fix the business condition and start the next attempt with a new transfer ID. transfer_already_reversed means the pair is already closed, while idempotency_conflict means it belongs to another payload.

Yes. rate_limit_exceeded, quota_exceeded, and billing_suspended do not start a new transfer. After backoff or remediation, resend the same transfer ID, scene, and exact payload.

Reversal applies the inverse balance changes for the whole transfer and moves its existing records to their reversal state. If reversal arrives before the transfer, an empty tombstone prevents that later transfer from executing.

Yes. Destination entries accept Unix-second start and expiry boundaries. Reads and deductions evaluate availability at that boundary; physical cleanup of expired batches is lazy.

It is a ledger-owned negative-ID account range for issuance, spending, fees, settlement, or another platform flow. An entry point can deterministically distribute transfers across its configured ID range.

Amounts are positive signed-64-bit integer base units encoded as decimal JSON strings. JavaScript backends can convert them directly to BigInt without losing precision.

No. Your application decides why and how much value moves. XferAPI validates and records the resulting accounting operation.