x402 (HTTP 402 Payment Required)

x402 is an HTTP-native payment protocol that lets agents and users sign up and fund Locus workspaces by paying with USDC on Polygon (chain 137) or Base (chain 8453). The protocol uses HTTP 402 status codes to negotiate payments inline — no separate payment step needed.

How it works

Agent sends a request

The agent calls the x402 sign-up or top-up endpoint.

Server responds with 402 challenge

If payment is required, the server returns HTTP 402 with payment negotiation headers describing what to pay, where, and how much.

Agent constructs payment

The agent (or x402 client library) constructs a payment authorization using the payer’s wallet (Polygon or Base) and resends the request with payment headers.

Payment settles, request completes

The server validates the payment via the x402 facilitator, settles the USDC transfer, and returns a JWT token and workspace details.

The x402 protocol handles payment negotiation automatically. If you’re using an x402-compatible client library, the challenge-response flow is transparent — the client handles it for you.

Creates a new workspace (or returns an existing one) by paying with USDC on Polygon or Base.

curl -s -X POST https://api.buildwithlocus.com/v1/auth/x402-sign-up \
  -H "Content-Type: application/json"

The first request returns HTTP 402 with payment details. After the client handles payment negotiation, the successful response is:

{
  "success": true,
  "jwt": "eyJ...",
  "expiresIn": "30d",
  "isNewWorkspace": true,
  "accountType": "external",
  "workspaceId": "ws_abc123",
  "claimUrl": "https://buildwithlocus.com/claim/..."
}

Field	Description
`jwt`	Bearer token for all Locus API calls (30-day expiry)
`isNewWorkspace`	Whether a new workspace was created or an existing one was found
`accountType`	`external` (non-Locus wallet) or `locus` (Locus-owned wallet)
`claimUrl`	Link for the user to claim the workspace and link their email (external accounts only)

Initial credits on sign-up: $6.00

Top up credits via x402

Add credits to an existing workspace using USDC on Polygon or Base.

curl -s -X POST https://api.buildwithlocus.com/v1/billing/x402-top-up \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"amount": 5.00}'

The server responds with HTTP 402 to negotiate the payment. After settlement:

{
  "success": true,
  "jwt": "eyJ...",
  "expiresIn": "30d",
  "creditBalance": 5.00,
  "workspaceId": "ws_abc123"
}

Constraint	Value
Minimum top-up	$1.00
Maximum top-up	$100.00

The x402 protocol flow

  Client                           Locus API                     Facilitator
    │                                  │                              │
    │── POST /v1/auth/x402-sign-up ──→ │                              │
    │                                  │                              │
    │←── HTTP 402 + payment terms ─────│                              │
    │                                  │                              │
    │  (client constructs payment      │                              │
    │   using Polygon or Base wallet)  │                              │
    │                                  │                              │
    │── POST + payment headers ──────→ │                              │
    │                                  │── validate payment ────────→ │
    │                                  │←── settlement confirmed ─────│
    │                                  │                              │
    │←── 200 + {jwt, workspaceId} ─────│                              │

The facilitator (facilitator.payai.network) is a trusted intermediary that validates and settles x402 payments on Polygon and Base.

Claim links

When x402 creates a new workspace for an external wallet, a claim link lets the user connect their email and access the Locus dashboard.

Endpoint	Method	Auth	Description
`GET /v1/auth/claim-link`	GET	Required	Get claim link for authenticated workspace
`GET /v1/auth/claim-status/:token`	GET	Public	Check if claim token is valid, used, or expired
`POST /v1/auth/claim-redeem`	POST	Public	Redeem claim with email, links email to workspace

Redeem a claim

curl -s -X POST https://api.buildwithlocus.com/v1/auth/claim-redeem \
  -H "Content-Type: application/json" \
  -d '{"token": "claim_token_here", "email": "[email protected]"}'

{
  "success": true,
  "email": "[email protected]",
  "loginUrl": "https://buildwithlocus.com/login",
  "workspaceId": "ws_abc123"
}

Git push deploys with x402

x402 users can deploy via git push using their JWT token instead of a claw_ API key:

git remote add locus https://x:$JWT_TOKEN@git.buildwithlocus.com/{workspaceId}/{projectId}.git
git push locus main

The git server auto-detects the credential type — claw_ prefix means API key, anything else is treated as a JWT token.

MPP vs x402

Feature	MPP (Tempo)	x402 (Polygon / Base)
Blockchain	Tempo (chain 4217)	Polygon (chain 137) or Base (chain 8453)
Token	Tempo USDC	USDC (Polygon or Base)
Sign-up cost	$0.001 USDC	Negotiated via x402
Initial credits	$0.00	$6.00
Payment flow	`Payment` header with wallet address	HTTP 402 challenge-response
Facilitator	None (direct)	`facilitator.payai.network`

Both protocols create the same type of workspace and JWT token. Choose based on which chain your wallet is on. The x402 endpoints accept both Polygon and Base — the client picks which chain to pay on.

Technical details

Detail	Value
Blockchains	Polygon (chain 137) and Base (chain 8453)
Token (Polygon)	USDC (`0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359`)
Token (Base)	USDC (`0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`)
Facilitator	`https://facilitator.payai.network`
Libraries	`@x402/core`, `@x402/evm`
Initial credits on sign-up	$6.00

Getting started

Features

Agent tools

Build with Locus

Checkout

x402 (HTTP 402 Payment Required)

How it works

Top up credits via x402

The x402 protocol flow

Claim links

Redeem a claim

Git push deploys with x402

MPP vs x402

Technical details

​How it works

​Sign up via x402

​Top up credits via x402

​The x402 protocol flow

​Claim links

​Redeem a claim

​Git push deploys with x402

​MPP vs x402

​Technical details

How it works

Sign up via x402

Top up credits via x402

The x402 protocol flow

Claim links

Redeem a claim

Git push deploys with x402

MPP vs x402

Technical details