> For the complete documentation index, see [llms.txt](https://parad0xlabs.gitbook.io/parad0xlabs-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://parad0xlabs.gitbook.io/parad0xlabs-docs/technical-reference/x402_integration.md).

# x402 Integration

x402 is the payment rail for agent-to-agent calls in Web0. This document covers how x402 fits into the stack, the "agent visa" concept, how openclaw-x402-pay and x402-gate implement the pay loop, and why x402 solves the DePIN oracle problem that every other network has failed to solve.

***

## The Protocol

x402 is an HTTP-native payment protocol. The core loop:

```
1. Agent A sends a request to an x402-protected endpoint
       |
       | server returns HTTP 402 with header:
       | X-Payment-Details: { amount, token, chain, facilitator }
       v
2. Agent A pays on-chain (USDC SPL transfer on Solana)
   Facilitator cosigns a receipt: { request_hash, payment_tx, timestamp, sig }
       |
       v
3. Agent A resends the original request with:
   X-Payment-Receipt: <signed receipt>
       |
       v
4. Server verifies receipt (via facilitator or local verifier)
   Processes the request, returns response
       |
       v
5. Receipt is written into the receipt-DAG (permanent audit trail)
```

The receipt is cryptographically bound to the specific request (via `request_hash`). It cannot be replayed for a different request. It cannot be forged without the facilitator's key. This is what makes it proof-of-work: the receipt IS the evidence that a specific service call happened and was paid for.

### Current Ecosystem State

x402 moved to the Linux Foundation in April 2026 with Coinbase, Cloudflare, Google, Visa, Anthropic, Circle, AWS, and Vercel as named partners. As of that date: \~165M cumulative transactions, \~$50M volume, \~69K active agents. Solana accounts for 37M+ transactions and 70% of monthly volume.

The canonical TypeScript implementation is `@x402/svm` (Solana variant) from the x402-foundation org. It is at v2.3.0. The PayAI Network (`x402-solana` npm, v2.0.4) is the primary Solana facilitator listed on solana.com/x402.

***

## Agent Visa Concept

A `.null` domain PDA stores three identity fields:

```
passport_hash   — Dark Passport ZK commitment (who this agent is)
x402_endpoint   — payment endpoint URL (how to call and pay this agent)
content_hash    — Arweave tx ID (what this agent publishes)
```

Together, `passport_hash + x402_endpoint` constitute the "agent visa." Any other agent can:

1. Resolve `foo.null` -> read the PDA
2. See the x402\_endpoint: `https://foo.null/api/v1`
3. See the passport\_hash: verify the Dark Passport proof if reputation is required
4. Call the endpoint, handle the 402, pay, get service

No out-of-band key exchange. No API key. No registration with a platform. The on-chain PDA is the directory entry. The x402 protocol handles authentication implicitly — the payment receipt proves the caller had funds and intent to pay.

This pattern is directly analogous to a visa: a document that proves identity and grants access to a service in a foreign jurisdiction, without that jurisdiction needing to know anything about the visitor beyond what the document attests.

The Dark Passport adds reputation context without leaking raw data: the Groth16 commitment proves the agent has a track record that meets a threshold (e.g., "completed >100 tasks with <2% dispute rate") without revealing the actual numbers. A server can reject callers whose passport\_hash does not verify against a minimum proof, before the 402 even fires.

***

## openclaw-x402-pay and x402-gate

These are the two Web0 packages that implement the pay loop from each side.

### x402-gate (server-side middleware)

Wraps any HTTP server to require x402 payment for protected routes.

What it does:

* Intercepts incoming requests to protected routes.
* Returns `402 Payment Required` with payment requirements in `X-Payment-Details`.
* On subsequent request with `X-Payment-Receipt`: verifies the receipt via the configured facilitator or local verifier.
* If valid: passes the request through to the handler.
* If invalid: returns 402 again.
* Writes verified receipts to the receipt-DAG.

Built on top of `@x402/svm` (x402-foundation) and `@x402/express` (v2.3.0). The Web0-specific additions are:

* NULLA mesh endpoint pattern: price per inference token, not per request
* Receipt-DAG write hook: every verified receipt is stored with the task\_id reference
* Passport gate: optional middleware to verify Dark Passport commitment before 402

```ts
import { x402Gate } from "@parad0xlabs/x402-gate";

app.use("/api/inference", x402Gate({
  amount: 0.001,            // USDC per 1k tokens
  token: "USDC",
  chain: "solana",
  facilitator: "https://facilitator.payai.network/",
  passportMinCommitment: PASSPORT_THRESHOLD, // optional
  receiptDag: dag,          // receipt-DAG instance
}));
```

### x402-pay (client-side agent payment)

Handles the 402 response and executes payment automatically, using the agent's on-chain wallet.

What it does:

* Wraps `fetch()` (or any HTTP client) to detect 402 responses.
* Parses `X-Payment-Details`, pays on-chain using the agent's Solana keypair and USDC balance.
* Attaches the receipt to the retry request.
* Checks the agent's spend cap before paying (hard limit, not advisory).
* Records the payment in the local CreditLedger as a `spend` entry.

```ts
import { x402Fetch } from "@parad0xlabs/x402-pay";

const fetch402 = x402Fetch({
  wallet: agentKeypair,
  maxSpendPerCall: 0.10,     // USDC hard cap per single call
  maxSpendPerHour: 1.00,     // USDC hard cap per hour
  creditLedger: ledger,      // nulla-local CreditLedger
});

const response = await fetch402("https://peer.null/api/inference", {
  method: "POST",
  body: JSON.stringify({ prompt: "...", max_tokens: 500 }),
});
```

Hard spend caps are enforced locally before the payment transaction is signed. This is the "agent wallet with hard spend caps" gap identified in the ecosystem survey — no existing Solana x402 implementation does this. The closest is AgentPay MCP (EVM/Base only) and Harvey Budget (EVM only).

***

## NULL Token Track

Every Solana x402 facilitator found in the ecosystem (PayAI, agenticpay, rapid402, x402-rs Solana crate) is USDC-only or SOL+USDC. NULL is a custom SPL token — no existing facilitator handles it.

The NULL track in Web0:

* NULL credits earned by NULLA mesh nodes are accounted in the local CreditLedger (SQLite).
* To spend NULL on an x402 call, the agent converts credits to an on-chain NULL token balance.
* The x402-gate server accepts NULL as an alternative payment token when configured.
* The NULL facilitator verifies SPL token transfers the same way USDC facilitators do, but against the NULL mint address.

V1 ships USDC only. NULL as a payment token is V2.

***

## The DePIN Oracle Problem — Why x402 Solves It

Every major DePIN compute network interposes a centralized intermediary between task completion and payment. The pattern is consistent across all five networks audited:

**Grass**: The Validator (a single entity, explicitly named as centralized in their own GitBook docs) determines validated bandwidth. ZK proofs attest to data integrity but do not route payment — the Validator's adjudication decides reward allocation. No payment flows without Validator approval.

**io.net**: The io.net platform controls job assignment, pricing (not a market auction), and the zkTFLOPs verification gate. The 2024 Sybil attack (1.8M fake GPUs) demonstrated that io.net's central verification is the gate — no platform approval, no payment.

**Helium**: Nova Labs / Helium Foundation oracles compute reward totals in a Foundation-owned database (confirmed in the helium/oracles GitHub repo). Hotspots cannot independently verify their own reward calculation. The HIP-70 spec states oracles were "initially built and operated by the Nova Labs team on behalf of the Helium Foundation" — that transition to multi-operator has not completed.

**Render**: OTOY infrastructure validates render output. Node operators cannot participate without OctaneRender, OTOY's proprietary software. The company is the clearinghouse.

**Akash**: The outlier — true on-chain escrow, no oracle, payment streams per-block. But Akash has no work verification at all. Payment flows regardless of whether the provider delivers anything. This is a different failure: no centralized oracle, but also no proof-of-work.

The pattern:

```
DePIN networks:   buyer -> [centralized oracle] -> payment -> miner
                              ^-- trusted third party determines "was work done?"

x402:             buyer -> [HTTP 402 receipt] -> miner
                              ^-- cryptographic proof, no third party
```

In the x402 model, the receipt is the proof. It contains the `request_hash` (binding it to the specific call), the on-chain payment tx (binding it to a specific Solana transfer), and the facilitator's signature (binding it to a verified payment). No oracle needed to decide if the work happened — the receipt IS the record that the call was made and paid for.

The facilitator is a lighter dependency than a DePIN oracle: it cosigns receipts but does not determine payment amounts, does not allocate rewards across nodes, and does not operate a work-verification database. A facilitator that goes offline affects payment processing but does not affect reward calculation for past work. PayAI Network's hosted facilitator is one option; a self-hosted facilitator (x402-rs has a production-grade self-hostable Rust facilitator) is another.

***

## Ecosystem Gaps This Stack Fills

Gaps confirmed by the June 2026 ecosystem survey that no existing project addresses:

1. **Self-custodial Solana facilitator with NULL/non-USDC token support.** Every Solana facilitator is USDC-only. The NULL track is unrepresented.
2. **Agent wallet with hard spend caps on Solana x402.** Existing spend-cap solutions (AgentPay MCP, Harvey Budget) are EVM/Base only.
3. **x402 + local AI mesh (NULLA) integration.** No existing implementation wires x402 payments to a local LLM node's task lifecycle. The closest is agenticpay's `@agenticpay/mcp-bridge` (2 stars, no production signals).
4. **Receipt-DAG as audit trail.** No existing x402 implementation builds a receipt DAG that links payment receipts to task IDs, work proofs, and on-chain anchors. The x402 receipt format supports this but no project has built the graph layer.
5. **x402 + Dark Passport passport-gated endpoints.** No existing project gates x402 endpoint access on a ZK reputation proof before the payment step.

***

## Dependencies

| Package             | Version | Role                                      |
| ------------------- | ------- | ----------------------------------------- |
| `@x402/svm`         | latest  | Solana x402 core (x402-foundation)        |
| `@x402/express`     | 2.3.0+  | Express middleware wrapper                |
| `x402-solana`       | 2.0.4   | PayAI facilitator client + CAIP-2 helpers |
| `@solana/web3.js`   | 2.x     | Solana RPC and transaction signing        |
| `@solana/spl-token` | latest  | USDC + NULL SPL token transfers           |

The Rust-side facilitator (if self-hosted):

| Crate               | Source                            |
| ------------------- | --------------------------------- |
| `x402-chain-solana` | x402-rs/x402-rs (crates.io)       |
| `x402`              | x402-rs/x402-rs — Axum middleware |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://parad0xlabs.gitbook.io/parad0xlabs-docs/technical-reference/x402_integration.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.