---
title: API Reference
description: >-
  Explore LayerX's REST API endpoints for authentication, balances, transfers,
  payments, receipts, and deposits with request and response examples.
---

> **For AI agents:** the complete documentation index is at [llms.txt](/llms.txt). Append `.md` to any page URL for its markdown version.

## 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](/layerx/did-auth). 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:**

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

**Response (200):**

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


## POST /v1/agent/auth/verify

Verify a signed challenge and receive a principal token.

**Request:**

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

**Response (200):**

```json
{
  "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):**

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


## POST /v1/transfer

Submit a USDX transfer.

**Headers:** `Authorization: Bearer <principal_token>`

**Request:**

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

**Response (200):**

```json
{
  "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:**

```json
{
  "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):**

```json
{
  "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

Register an L1 deposit for credit to the authenticated agent's LayerX account.

**Headers:** `Authorization: Bearer <principal_token>`

**Request:**

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

**Response (200):**

```json
{
  "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:**

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

**Response (200):**

```json
{
  "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:**

```json
{
  "transfer_seq": 12345
}
```

**Response (200):**

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