API Reference

API reference

LayerX exposes a REST API for all operations. The base URL is https://layerx.paxeer.network.

Authentication

Most endpoints require authentication via a principal token obtained through the DID challenge/verify flow. Include the token in the Authorization header:

Authorization: Bearer <principal_token>

Public read endpoints (marked below) do not require authentication.

Endpoints

Authentication

Method	Path	Auth	Description
`POST`	`/v1/agent/auth/challenge`	No	Request a DID challenge
`POST`	`/v1/agent/auth/verify`	No	Verify a signed challenge, receive a principal token

Accounts

Method	Path	Auth	Description
`GET`	`/v1/balance`	Yes	Get the authenticated agent's USDX balance
`GET`	`/v1/balance/\{did\}`	Public	Get any agent's USDX balance

Transfers

Method	Path	Auth	Description
`POST`	`/v1/transfer`	Yes	Submit a USDX transfer
`GET`	`/v1/transfers`	Yes	List transfers for the authenticated agent
`GET`	`/v1/transfers/\{did\}`	Public	List transfers for a specific DID

Payments

Method	Path	Auth	Description
`POST`	`/v1/pay`	Yes	Submit a payment (402LXP convenience endpoint)
`GET`	`/v1/stream`	Yes	SSE stream of incoming payments

Receipts

Method	Path	Auth	Description
`GET`	`/v1/receipt/\{seq\}`	Public	Get a signed receipt by sequence number

Deposits & withdrawals

Method	Path	Auth	Description
`POST`	`/v1/deposit`	Yes	Register an L1 deposit for credit
`POST`	`/v1/withdraw`	Yes	Request a USDX withdrawal to L1
`POST`	`/v1/force-settle`	Yes	Force-settle a transfer to L1

POST /v1/agent/auth/challenge

Request a DID challenge for authentication.

Request:

{
  "did": "did:ed25519:agent.scanner.v1"
}

Response (200):

{
  "challenge": "a3F9xK2m...",
  "expires_at": "2026-01-15T10:05:00Z"
}

POST /v1/agent/auth/verify

Verify a signed challenge and receive a principal token.

Request:

{
  "did": "did:ed25519:agent.scanner.v1",
  "challenge": "a3F9xK2m...",
  "signature": "base64url-encoded-signature"
}

Response (200):

{
  "principal_token": "eyJhbGciOiJFZERTQSJ9...",
  "expires_at": "2026-01-15T11:05:00Z"
}

GET /v1/balance

Get the authenticated agent's USDX balance.

Headers: Authorization: Bearer <principal_token>

Response (200):

{
  "did": "did:ed25519:agent.scanner.v1",
  "balance": "47.50",
  "currency": "USDX"
}

POST /v1/transfer

Submit a USDX transfer.

Headers: Authorization: Bearer <principal_token>

Request:

{
  "to": "did:ed25519:service.weather.v2",
  "amount": "1.50",
  "memo": "optional reference string"
}

Response (200):

{
  "seq": 12345,
  "from": "did:ed25519:agent.scanner.v1",
  "to": "did:ed25519:service.weather.v2",
  "amount": "1.50",
  "timestamp": "2026-01-15T10:03:42Z",
  "receipt_signature": "base64url-encoded-sequencer-signature"
}

POST /v1/pay

Convenience endpoint for 402LXP payments. Behaves identically to /v1/transfer but is optimized for the 402LXP flow and accepts the payment challenge inline.

Headers: Authorization: Bearer <principal_token>

Request:

{
  "to": "did:ed25519:service.weather.v2",
  "amount": "0.001",
  "payment_challenge": "base64url-encoded-402-challenge"
}

Response (200): Same as /v1/transfer.

GET /v1/stream

Server-Sent Events stream of incoming transfers for the authenticated agent.

Headers: Authorization: Bearer <principal_token>

Response: text/event-stream

data: {"seq": 12346, "from": "did:ed25519:agent.buyer.v1", "amount": "0.50", "timestamp": "..."}

data: {"seq": 12347, "from": "did:ed25519:agent.buyer.v2", "amount": "1.00", "timestamp": "..."}

GET /v1/receipt/{seq}

Get a signed receipt by sequence number. This endpoint is public and requires no authentication.

Response (200):

{
  "seq": 12345,
  "sender": "did:ed25519:agent.scanner.v1",
  "recipient": "did:ed25519:service.weather.v2",
  "amount": "1.50",
  "timestamp": "2026-01-15T10:03:42Z",
  "batch_seq": 987,
  "merkle_leaf": "0xa3f9...",
  "merkle_proof": ["0xb2c1...", "0xd4e5..."],
  "signature": "base64url-encoded-sequencer-signature"
}

POST /v1/deposit

Headers: Authorization: Bearer <principal_token>

Request:

{
  "tx_hash": "0xabc123...",
  "did": "did:ed25519:agent.scanner.v1"
}

Response (200):

{
  "deposit_seq": 456,
  "amount": "100.00",
  "status": "confirmed",
  "credited_at": "2026-01-15T10:00:00Z"
}

POST /v1/withdraw

Request a USDX withdrawal to L1.

Headers: Authorization: Bearer <principal_token>

Request:

{
  "amount": "25.00",
  "to": "pax1abc123..."
}

Response (200):

{
  "withdrawal_seq": 789,
  "amount": "25.00",
  "status": "pending",
  "estimated_settlement": "2026-01-15T10:10:00Z"
}

POST /v1/force-settle

Force-settle a specific transfer to L1 immediately.

Headers: Authorization: Bearer <principal_token>

Request:

{
  "transfer_seq": 12345
}

Response (200):

{
  "transfer_seq": 12345,
  "l1_tx_hash": "0xdef456...",
  "status": "settled"
}