LayerX API

LayerX (layerxd) is the agent-native settlement fabric. It gives every Matrix agent an instant-settling, gasless, USD-denominated balance (USDX), fully reserved 1:1 by USDL, with a Merkle-provable signed receipt for every transfer, net-settled to Paxeer mainnet (chain 125) on a tiered schedule. An agent's DID is its account.

Surface split

Since Phase 4 (full-transparency rollup model), the surface is split into two groups:

Public read / explorer -- unauthenticated. Anyone can read so receipts and roots are independently verifiable and the reserve is publicly auditable.
Write / principal -- authorized by a DID signature alone (signed intent) or an X-LayerX-Agent principal token as a convenience. The shared transport bearer (LAYERX_TOKEN) is an optional fleet gate, never the public gate.

Routes -- public read surface (no auth)

Method	Path	Purpose
GET	`/healthz`	Unauthenticated liveness
GET	`/`	Service root: name, version, health link
GET	`/v1/info`	Sequencer metadata (chain ID, anchor/USDL addresses, window, sequencer pubkey)
GET	`/v1/supply`	Circulating USDX supply + on-chain USDL reserve (the reserve proof, invariant i1)
GET	`/v1/batches`	Settlement batch feed (KEYSET-paginated)
GET	`/v1/batch/{id}`	Single batch by UUID
GET	`/v1/anchor/{root}`	On-chain anchor proof for a Merkle root
GET	`/v1/receipt/{seq}`	Signed inclusion receipt (+ anchor proof once settled)
GET	`/v1/transfers`	Public transfer feed (KEYSET-paginated: `?limit=&before=&did=`)
GET	`/v1/account/{did}`	Account snapshot (balance, escrow bound, payout address)
GET	`/v1/stream`	Public live event stream (SSE): `transfer` + `anchor` events; reconnect replays via `Last-Event-ID`
GET	`/v1/hold/{id}`	Escrow hold status

Routes -- auth lane (public; mints principal token)

Method	Path	Purpose
POST	`/v1/agent/auth/challenge`	Open the ed25519 DID auth lane
POST	`/v1/agent/auth/verify`	Mint a short-lived principal token

Routes -- write / principal surface

Method	Path	Purpose
GET	`/v1/balance`	Current USDX balance + escrow bound + payout address
GET	`/v1/deposit`	Vault address + DID-claim payload
POST	`/v1/account/evm`	Bind an EVM payout address to the account
POST	`/v1/pay`	Pay another agent by DID, returns signed receipt
POST	`/v1/hold`	Create an escrow hold (reserve funds)
POST	`/v1/hold/{id}/capture`	Capture a hold (settle to recipient)
POST	`/v1/hold/{id}/release`	Release a hold (return funds)
POST	`/v1/withdraw`	Burn USDX, release USDL to payout address
POST	`/v1/settle`	Force-settle the open settlement window now

Authentication

Two-layer auth on write paths:

Transport bearer (optional fleet gate) -- Authorization: Bearer <LAYERX_TOKEN>.
Principal -- either an X-LayerX-Agent session token (minted via challenge/verify) OR a directly DID-signed intent carried in-band.

The public read surface and auth lane are never transport-gated.

Account model

LayerX runs an always-on sequencer over a reserved-balance model:

Funds can be reserved against in-flight obligations (escrow holds).
Payments produce signed, Merkle-provable receipts.
Settlement anchors balances on-chain via the vault / settlement-anchor contracts.
Fully reserved: USDX == USDL in vault at all times.
Domain-separated Merkle leaves, Paxeer-anchored roots, L1 force-withdraw escape hatch.

Pay

POST /v1/pay

tostringrequired

The recipient agent DID.

amountstringrequired

The amount in USDX (decimal string, 6dp).

refstring

Optional 32-byte binding digest (0x + 64 hex).

curl -X POST https://layerx.example/v1/pay \
  -H "Authorization: Bearer $LAYERX_TOKEN" \
  -H "X-LayerX-Agent: $PRINCIPAL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"to": "did:matrix:agent:abcd1234567890ab", "amount": "12.500000"}'

okbooleanrequired

Whether the payment succeeded.

data.seqintegerrequired

The receipt sequence number. Fetch the signed receipt at GET /v1/receipt/{seq}.

Escrow holds

Escrow holds let you reserve funds before committing:

POST /v1/hold -- create a hold, reserving the amount.
POST /v1/hold/{id}/capture -- settle the hold to the recipient.
POST /v1/hold/{id}/release -- release the hold, returning funds.

Withdraw

POST /v1/withdraw

amountstringrequired

Amount in USDX to withdraw.

swap_outstring

Optional target asset symbol for a DEX swap (uppercase ticker, 1-12 chars).

Burns USDX and releases USDL to the agent's bound EVM payout address.

Transfer feed pagination

GET /v1/transfers?limit=50&before=<seq>&did=<did>

KEYSET-paginated. The response carries next_before for fetching the previous page. Filter by did to scope to a single account.

Invariants

Fully reserved (USDX == USDL in vault)
Sequencer holds no agent keys
Escrow-bounded spend
Domain-separated Merkle receipts
Paxeer-anchored roots
L1 force-withdraw escape hatch
DID-scoped accounts
Tiered settlement schedule
One always-on sequencer