@parad0x_labs/x402

v0.3.0

Published

a month ago

DNA Payment Rail — x402 SDK and CLI for AI agent buyers and sellers on Solana.

0High
0Medium
0Low

loop22

ai agents payments solana usdc micropayments x402 dna machine-to-machine

DNA x402 — Payment Rail for Agents and APIs

DNA x402 is Parad0x Labs' x402 payment protocol for Solana. Any API can require payment, and any agent can pay programmatically with quote, proof, receipt, and optional on-chain anchoring.

On-chain receipt anchoring: opt-in, with no default program. Set RECEIPT_ANCHOR_PROGRAM_ID to a receipt_anchor deployment, for example the devnet program HSdEQWunzPtNqdzv5HfXuA3zwPLpgTXRyfbndnGamhXs.

Why DNA

AI agents need to pay for things: inference, storage, data, compute. Current options are API keys (no metering), credit cards (no agents), or crypto wallets (too manual). DNA solves this with a single SDK that handles quoting, payment, verification, and receipts — from $0.00001 to $100+ per call.

What This Package Is Not

Not a mixer
Not a privacy pool
Not a zk-SNARK payment hot path

Privacy-oriented Dark Null work is a separate product line. The live DNA x402 request path is optimized for fast payments and does not require zk proof generation per call. Builders can opt into the Dark Null private receipt path after a normal DNA receipt exists.

Features

Payments

Transfer verification (default): the seller checks an on-chain USDC SPL transfer by RPC before serving. The transfer must carry an SPL Memo equal to the quote's memoHash, which binds it to one quote (on by default; REQUIRE_PAYMENT_MEMO=0 opts out)
Stream verification: Streamflow streams are checked when the seller passes a streamflowClient (SDK seller and paywall); the bundled server passes none and refuses stream proofs
Netting (development only): an off-chain ledger that accepts a buyer's claim without on-chain verification; off by default, refused when NODE_ENV=production, and net totals are not settled on-chain
x402 HTTP standard: Any REST API becomes payment-gated with one middleware call
Receipt anchoring (opt-in): folds a 32-byte value into an hourly hash chain in a receipt_anchor deployment you configure (RECEIPT_ANCHOR_PROGRAM_ID); there is no default program, and an enabled but unusable configuration stops startup
Optional Dark Null privacy path: Hash-only private receipt request after a DNA receipt is issued
Replay protection: each payment proof is accepted once. Replay keys are stored in Postgres when X402_DATABASE_URL or DATABASE_URL is set, so a used proof stays refused after a restart and across instances; without a database they are in-process only (warning at startup, refused when NODE_ENV=production)
Surge pricing: Dynamic price multipliers (0.8x–2.5x) based on real-time load (queue depth, inflight, latency, error rate)

Marketplace

Shop discovery: Agents find providers by capability, price, latency, and reputation
Reputation engine: Scores sellers 0–100 based on fulfillment rate, latency, disputes, uptime, and anchored receipts — bronze/silver/gold tiers
Badge system: Auto-awarded badges — FAST_P95, FULFILLMENT_99, TOP_SELLER_24H, PROOF_ANCHORED, STREAM_READY
Ranking engine: Weighted scoring (50% price, 30% latency, 20% reputation) for quote comparison
Limit orders: Agents set "buy at max $X" — auto-executes when a quote matches
Market analytics: Trending, top-selling, top-revenue, on-sale detection, price history, demand velocity, volatility scores
Bundle system: Multi-step capability chains with cost breakdowns, margin policies, and execution hashing
Abuse reporting: Scam/malware/impersonation reports against shops
OpenAPI/MCP import: Auto-generate shop endpoints from OpenAPI specs or MCP tool definitions
Shop templates: Pre-built configs for research, ops, action, and always-on agent types

Developer Tools

Seller SDK: Self-contained dnaSeller() scaffold for trusted/demo integrations
DNA Guard: Fail-open/fail-closed middleware for spend ceilings, replay alerts, quality validation, receipt verification logs, and provider scoring
x402 Doctor: Diagnostic tool that detects x402 dialects (Coinbase, Memeputer, generic), identifies missing headers, suggests fixes
Tool catalog: Cost estimation, balance coverage, projected spend based on usage patterns
25+ structured error codes: Every error returns hints, trace IDs, docs URLs, and redacted payloads
Trace IDs: UUID per request via X-TRACE-ID header

Polymarket Multi-User Precheck

Shared builder credentials, per-user signer model: Server can keep shared builder headers/attribution credentials while each user order still requires a user-owned deposit wallet signer context (POLY_1271 / signature type 3)
Live readiness endpoint: GET /api/polymarket/live/readiness or GET /v1/polymarket/live/readiness
Per-user order precheck endpoint: POST /api/polymarket/live/order-precheck or POST /v1/polymarket/live/order-precheck
Live signed-order relay endpoint (gate-protected): POST /api/polymarket/live/submit or POST /v1/polymarket/live/submit
Alias env support:
- POLY_BUILDER_CODE -> POLYMARKET_BUILDER_CODE
- POLYMARKET_API_KEY -> POLYMARKET_BUILDER_API_KEY
- POLYMARKET_API_SECRET -> POLYMARKET_BUILDER_SECRET
- POLYMARKET_API_PASSPHRASE -> POLYMARKET_BUILDER_PASSPHRASE
Runtime non-regression rules:
- Keep shared builder credentials for attribution/API auth.
- Keep per-user signer/deposit wallet context for every order.
- Do not allow backend custody or backend signing.
- Do not skip /v1/polymarket/live/order-precheck before live submit.
- Production gate lock: keep X402_ENABLE_POLYMARKET_LIVE=1 with checklist ref X402_POLYMARKET_LIVE_CHECKLIST_REF=docs/DNA_X402_POLYMARKET_LIVE_CONSTITUTION.md#live-gate-lock.
- Do not switch back to paper/signal-only gate state unless explicitly requested by sls_0x.

Multi-User Ledger Runtime (Website Agents)

Users can scale to large concurrent agent counts under one platform builder integration, while balances remain per-user in ledger state.
Funding path:
1. User funds agent wallet.
2. User does one cash-in transfer to platform ledger.
3. Tips and bets run gasless against internal ledger balance.
4. User cashes out back to wallet when needed.
Required properties:
- Per-user ledger segregation and audit trail
- Explicit user-owned wallet flow
- No backend private-key custody/signing

Infrastructure

Audit logging: NDJSON corporate-grade audit trail for every payment event
Webhooks: HMAC-signed async payment notifications with retry logic and exponential backoff
Cached RPC client: Solana RPC with TTL cache, circuit breaker, retry logic, and in-flight deduplication
Heartbeat system: Real-time shop load monitoring (queue depth, p95 latency, error rate)
Admin API: Full observability — audit export, receipt inspection, pause controls, replay store stats
Liquefy bridge: Archive payment data into verified .null vaults with live sidecar streaming
Benchmarking suite: Compute profiling, transaction size analysis, soak test thresholds

NULL Tip Account Eligibility

Recipient enrollment required: a wallet must open Tips and complete wallet-session enrollment before it can receive in-app NULL tips.
Gift-icon / chat gating endpoint:
- GET /api/tips/account-status?wallet=<ownerWallet>
- GET /v1/tips/account-status?wallet=<ownerWallet>
- GET /api/tips/account/:ownerWallet/status
- GET /v1/tips/account/:ownerWallet/status
Response shape: { ok, ownerWallet, hasTipAccount, canReceiveTips }
Cash-out automation runtime:
- NULL_TIP_WITHDRAW_MODE=manual|webhook|mock
- NULL_TIP_WITHDRAW_AUTO_PROCESS=1|0
- automation processor endpoint: POST /api|/v1/admin/tips/withdrawals/process
- user status feed endpoint: GET /api|/v1/tips/withdrawals

Install

npm install @parad0x_labs/x402

That installs the SDK and the dna-x402 CLI (run it with npx dna-x402 inside a project that has the package installed, or with npx -p @parad0x_labs/x402 dna-x402 from anywhere). Use the SDK for production buyer/seller integrations, and use the CLI for zero-config demos or starter scaffolds.

Zero-Config Demo

Bring up a local seller in one terminal:

npx -p @parad0x_labs/x402 dna-x402 demo seller --mode netting --port 3000

Then hit it from a buyer in another terminal:

npx -p @parad0x_labs/x402 dna-x402 demo buyer --mode netting --base-url http://127.0.0.1:3000

Supported demo modes:

transfer
netting
stream

The demo path is for proving the full 402 handshake, receipt flow, and settlement-mode wiring without forcing you to wire a real wallet first. It is not a substitute for production wallet and custody policy.

Starter Scaffolds

Generate a runnable seller project:

npx -p @parad0x_labs/x402 dna-x402 init seller my-seller
cd my-seller
npm start

Generate a runnable buyer project:

npx -p @parad0x_labs/x402 dna-x402 init buyer my-buyer
cd my-buyer
npm start

The generated seller starter accepts transfer and stream only. Unverified netting is off unless you start the seller with DNA_TRUSTED_LOCAL_NETTING=1; it accepts a buyer's claim with no on-chain check, is for local development only, and the SDK refuses it when NODE_ENV=production. The generated buyer starter defaults to DNA_BUYER_MODE=netting, so for a local loop start the seller with DNA_TRUSTED_LOCAL_NETTING=1, or replace the demo buyer wallet with a real wallet and use transfer.

Quick Start

For Buyers (AI Agents)

import { fetchWith402 } from "@parad0x_labs/x402";

const result = await fetchWith402("https://provider.example/api/inference", {
  wallet: {
    payTransfer: async (quote) => ({
      settlement: "transfer",
      txSignature: "replace-with-real-wallet-tx-signature",
    }),
  },
  maxSpendAtomic: "50000",
});

const data = await result.response.json();

The payment transaction must include an SPL Memo instruction whose text is quote.memoHash; sellers refuse a transfer without it by default. buildMemoInstruction(quote.memoHash, payer) from @parad0x_labs/x402 builds it. A seller that has to accept wallets without memo support can opt out with REQUIRE_PAYMENT_MEMO=0 (server) or requirePaymentMemo: false (dnaSeller / dnaPaywall); the transfer is then not bound to a specific quote.

For a no-code smoke test instead of writing a buyer immediately:

npx -p @parad0x_labs/x402 dna-x402 demo buyer --mode transfer --base-url http://127.0.0.1:3000

If your buyer wants a deterministic receipt binding instead of a random per-call commitment, pass payerCommitment32B explicitly:

const result = await fetchWith402("https://provider.example/api/inference", {
  wallet: myWallet,
  maxSpendAtomic: "50000",
  payerCommitment32B: "9f".repeat(32), // 32-byte hex, with or without 0x prefix
});

For Sellers (Sell Compute, AI, Data — Anything)

import express from "express";
import { dnaSeller, dnaPrice } from "@parad0x_labs/x402/seller";

const app = express();
app.use(express.json());

// 1. One line — enable payments to your wallet
const pay = dnaSeller(app, { recipient: "YOUR_SOLANA_WALLET" });

// 2. Gate any endpoint with a price
app.get("/api/inference", dnaPrice("5000", pay), (req, res) => {
  res.json({ result: "inference output" });
});

app.listen(3000);

That is the fastest scaffold, not the strongest control surface. dnaSeller() now verifies transfer proofs through the local Solana payment verifier, and it can verify stream proofs too if you pass a real streamflowClient into the scaffold options. Signed receipts for the payment finalize handshake preserve the transfer signature or verified streamId, and unlocked JSON routes emit a second delivery-bound receipt tied to the actual protected response body. Finalized commits are bound to the quoted HTTP method and full request target; a commit for GET /api/a?x=1 will not unlock POST /api/a?x=1, GET /api/a?x=2, or /api/b. The scaffold also rejects reusing the same transfer signature across different commits, so one on-chain payment proof cannot unlock multiple paid requests. Unlocked text and binary responses also carry a signed delivery receipt in the x-dna-receipt header. Manual streaming/chunked handlers and redirect/file helper responses are rejected with 501 unsupported_delivery_mode so the scaffold does not pretend it can prove a delivery it never signed. Failed protected deliveries now restore the paid unlock on any 4xx or 5xx, instead of charging for an application error by default. Guard policies, replay controls, market routing, and anchoring still live in the full x402 server path.

For the zero-config runnable seller instead of hand-writing the app first:

npx -p @parad0x_labs/x402 dna-x402 demo seller --mode transfer --port 3000

Transfer is the default buyer path. Unsigned netting is disabled by default in the main server, and the buyer SDK does not pick it just because payNetted() exists. For local development only, opt in with UNSAFE_UNVERIFIED_NETTING_ENABLED=1 and pass preferNetting: true in the buyer call; the server and the SDK seller and paywall refuse it when NODE_ENV=production. Netting records amounts in an off-chain ledger; nothing settles the net totals on-chain. The main server only accrues balances into the netting ledger for actual netting settlements now; verified transfer and stream payments are not silently mirrored into off-chain netting state.

If you expose stream in a scaffolded seller or paywall, wire a real streamflowClient; otherwise stream verification now fails closed instead of accepting a bare top-up signature. In the current per-request quote/finalize flow, verified streamId proofs are also treated as single-use, just like transfer proofs. If you want long-lived subscription semantics, build that session policy explicitly instead of reusing one finalize proof forever. The x402 header-compat flow also fails closed if a verifier claims a transfer succeeded but does not return the canonical txSignature. It accepts PAYMENT-REQUIRED requirements only when they name an unexpired quote this server issued for the same resource (memo equal to the quote's memoHash, same recipient, amount and mint) and verifies the payment against that server-side quote; requirements a client edits or invents are refused with X402_REQUIRED_PROOF_MISMATCH.

Add DNA Guard (Spend Caps + Quality + Reputation API)

import express from "express";
import { AuditLogger, createDnaGuard, dnaPrice, dnaSeller } from "@parad0x_labs/x402";

const app = express();
app.use(express.json());

const pay = dnaSeller(app, { recipient: "YOUR_SOLANA_WALLET" });
const audit = new AuditLogger({ filePath: "./audit-guard.ndjson" });
const guard = createDnaGuard({ auditLog: audit });

app.use("/guard", guard.router());

app.get("/api/inference", dnaPrice("5000", pay), guard.protect({
  providerId: "gpu-cluster-a",
  endpointId: "inference",
  amountAtomic: "5000",
  spendCeilings: { buyerAtomic: "15000", walletAtomic: "25000" },
  qualityValidator: (body) => ({
    ok: typeof (body as { result?: unknown }).result === "string",
    reason: "missing_result_string",
  }),
  failMode: "fail-open",
}), (_req, res) => {
  res.json({ result: "inference output" });
});

That gives you:

spend ceilings per buyer / wallet / agent / api key
replay anomaly logging
quality validation and dispute tagging
/guard/leaderboard, /guard/reputation/:providerId, /guard/compare, /guard/quote/best
receipt verification endpoints at /guard/receipt/:receiptId/verify

Use examples/dna-guard-seller.ts for the full runnable example.

Settlement Modes

| Mode | Per-TX Solana Fee | Best For | How It Works | |------|-------------------|----------|-------------| | Transfer (default) | ~$0.0001 | Paid requests | On-chain USDC SPL transfer, verified by RPC and bound to the quote by an SPL Memo | | Stream | ~$0.0001 | Continuous access | Streamflow stream, verified when the seller passes a streamflowClient | | Netting (development only) | None | Local testing | Off-chain ledger entry accepted without verification; refused in production; no on-chain settlement of net totals |

Optional Dark Null Privacy Path

The normal DNA path stays default:

quote -> commit -> payment proof -> signed receipt -> paid unlock

The optional Dark Null path adds a private receipt request after the signed DNA receipt:

signed DNA receipt -> createDarkNullPrivacyRequest() -> Dark Null private receipt summary

import {
  createDarkNullPrivacyRequest,
  verifyDarkNullPrivacyRequest,
} from "@parad0x_labs/x402";

const request = createDarkNullPrivacyRequest({
  signedReceipt,
  target: {
    cluster: "devnet",
    programId: "35GMe13ExGB1JGp1wZGrEvHfQnENKADroDQApeziKuwV",
    manifestLabel: "canonical-devnet-root-2",
  },
  settlementSlot: 434395918,
  confirmationStatus: "finalized",
});

if (!verifyDarkNullPrivacyRequest(request).ok) {
  throw new Error("Dark Null privacy request failed verification");
}

Use it for privacy-sensitive paid unlocks. Do not put Dark Null proving in the live per-request hot path.

Devnet is the current Dark Null evidence lane. Mainnet-beta use requires promoted Dark Null deployment evidence and hosted enablement.

Architecture

Agent (buyer)                         API Provider (seller)
     |                                      |
     |  1. GET /api/inference               |
     |------------------------------------->|
     |  2. 402 Payment Required             |
     |<-------------------------------------|
     |  3. POST /commit (lock quote)        |
     |------------------------------------->|
     |  4. Pay (netting/transfer/stream)    |
     |------------------------------------->|
     |  5. POST /finalize (submit proof)    |
     |------------------------------------->|
     |  6. Receipt + access                 |
     |<-------------------------------------|
     |                                      |
     |  Receipts anchored on Solana via a   |
     |  configured receipt_anchor program   |

Project Structure

x402/
├── src/
│   ├── cli.ts                 # `dna-x402` CLI (`demo` + `init`)
│   ├── server.ts              # Main x402 payment server
│   ├── client.ts              # Agent SDK (fetchWith402, marketCall)
│   ├── catalog.ts             # Tool catalog — cost estimation + balance coverage
│   ├── streaming.ts           # Streamflow integration for streaming payments
│   ├── demo/                  # Zero-config buyer/seller demos for transfer/netting/stream
│   ├── sdk/
│   │   ├── seller.ts          # Self-contained seller SDK (start here)
│   │   ├── guard.ts           # DNA Guard middleware + provider reputation API
│   │   ├── paywall.ts         # Express payment middleware
│   │   └── webhook.ts         # HMAC webhook delivery with retries
│   ├── market/
│   │   ├── analytics.ts       # Trending, top-selling, revenue, on-sale, price history
│   │   ├── reputation.ts      # Seller reputation scoring (0-100, bronze/silver/gold)
│   │   ├── badges.ts          # Auto-awarded performance badges
│   │   ├── ranking.ts         # Weighted quote ranking (price/latency/reputation)
│   │   ├── orders.ts          # Limit order book with auto-execution
│   │   ├── bundles.ts         # Multi-step capability chains
│   │   ├── heartbeat.ts       # Real-time shop load monitoring
│   │   ├── policy.ts          # Smart routing with preferences and denylists
│   │   ├── import/            # OpenAPI + MCP auto-importers
│   │   └── templates/         # Pre-built shop configs (research, ops, action)
│   ├── pricing/
│   │   └── surge.ts           # Dynamic surge pricing (0.8x–2.5x)
│   ├── x402/
│   │   ├── doctor.ts          # x402 dialect diagnostics + fix suggestions
│   │   ├── errors.ts          # 25+ structured error codes with hints
│   │   └── compat/            # Multi-dialect parser (Coinbase, Memeputer, etc.)
│   ├── verifier/
│   │   ├── splTransfer.ts     # On-chain USDC transfer verification
│   │   ├── streamflow.ts      # Stream payment verification
│   │   ├── replayStore.ts     # Replay keys: Postgres when a database URL is set, else in-process
│   │   └── rpcClient.ts       # Cached RPC with circuit breaker
│   ├── packing/
│   │   └── anchorV1.ts        # Binary packing + hash-chain accumulator
│   ├── logging/
│   │   └── audit.ts           # NDJSON corporate audit logger
│   ├── bridge/liquefy/        # Vault exporter, sidecar, CLI, adapter
│   ├── admin/                 # Admin API (audit, receipts, pause controls)
│   ├── bench/                 # Compute profiling, tx metrics, thresholds
│   └── middleware/             # HTTPS enforcement, trace ID injection
├── examples/
│   ├── sell-compute.ts        # Runnable seller demo (CLI-compatible)
│   ├── dna-guard-seller.ts    # Add spend caps, quality checks, and reputation APIs
│   ├── buyer-agent.ts         # Runnable buyer demo (pairs with sell-compute)
│   ├── seller-api.ts          # API accepting payments (advanced)
│   └── liquefy-gated-vault.ts # Liquefy + DNA integration
├── test-mainnet/
│   ├── mayhem-50.mjs          # 50-agent stress test
│   └── MAYHEM_50_REPORT.md    # Test results
└── AGENTS.md                  # AI agent quick reference

Running the Server

git clone https://github.com/Parad0x-Labs/dna-x402
cd dna-x402/x402
npm install
cp .env.example .env       # Configure your wallet + RPC
npm run build
npm start

If you only want a local buyer/seller proof without running the full server, prefer:

node dist/cli.js demo seller --mode netting --port 3000
node dist/cli.js demo buyer --mode netting --base-url http://127.0.0.1:3000

DNA Guard Commands

npm run test:guard
npx tsx examples/dna-guard-seller.ts

Main x402 server integration is now built in behind config flags. When DNA_GUARD_ENABLED=1, createX402App() mounts /guard, enforces spend ceilings during quote/finalize flows, records receipt verification, and persists ledger state if DNA_GUARD_SNAPSHOT_PATH is set.

On the built-in protected routes (/resource, /inference, /stream-access, and audit fixtures), a finalized x-dnp-commit-id is now treated as a single-use delivery token. Successful delivery consumes it; failed delivery can be retried after a 5xx.

DNA_GUARD_ENABLED=1
DNA_GUARD_FAIL_MODE=fail-closed
DNA_GUARD_SNAPSHOT_PATH=./state/dna-guard.json
DNA_GUARD_BUYER_CEILING_ATOMIC=500000
DNA_GUARD_WALLET_CEILING_ATOMIC=1000000

For custom servers, you can also use the file-backed ledger helper directly:

import { createDnaGuard, createFileBackedDnaGuardLedger } from "@parad0x_labs/x402";

const ledger = createFileBackedDnaGuardLedger({
  snapshotPath: "./state/dna-guard.json",
  windowMs: 86_400_000,
});
const guard = createDnaGuard({ ledger });

Key routes after mounting app.use("/guard", guard.router()):

GET /guard/summary
GET /guard/leaderboard
GET /guard/score/:providerId
GET /guard/reputation/:providerId
GET /guard/compare?providers=provider-a,provider-b
GET /guard/quote/best?providers=provider-a,provider-b
GET /guard/receipt/:receiptId/verify
POST /guard/receipt/:receiptId/verify

Liquefy Integration

DNA integrates with Liquefy for archiving payment data into verified .null vaults.

Export Payment Data to Liquefy Vault

# One-shot export
curl -s http://localhost:8080/admin/audit/export | \
  npx tsx src/bridge/liquefy/cli.ts --stdin --out ./vault-staging/run-001

# Pack with Liquefy
python tools/tracevault_pack.py ./vault-staging/run-001 --org dna --out ./vault/run-001

DNA Guard audit events archive through the same bridge, including:

spend blocks
replay alerts
validation failures and disputes
receipt verified / invalid states
fail-open and runtime-error signals

Live Sidecar (Auto-Archive)

import { LiquefySidecar } from "@parad0x_labs/x402";

const sidecar = new LiquefySidecar({
  outDir: "./vault-live",
  cluster: "devnet",
});
sidecar.attachAuditLogger(auditLogger);
sidecar.startPeriodicFlush();

Payment-Gated Vault Access

Use DNA to monetize Liquefy vault operations. See examples/liquefy-gated-vault.ts for a complete example.

Market Intelligence API

Real-time analytics on every trade flowing through DNA:

| Endpoint | What It Returns | |----------|----------------| | GET /market/trending?window=1h | What's hot — demand velocity vs previous period | | GET /market/top-selling?window=24h | Most transactions by shop/endpoint | | GET /market/top-revenue?window=24h | Highest earning shops | | GET /market/on-sale?window=24h | Price drops detected | | GET /market/price-history?endpointId=X | Price chart for any endpoint | | GET /market/snapshot | Full dashboard — demand velocity, median prices, seller density, volatility, recommended providers |

Agents use this to shop smart — compare providers, find deals, track trends, and make data-driven purchasing decisions. All programmatic, no human needed.

Historical Mainnet Reports

This repo includes checked-in mainnet test artifacts for the payment rail flows. Summary from the tracked 50-agent stress report (2026-02-25):

| Metric | Result | |--------|--------| | Agents | 50 (30 netting + 20 transfer) | | Total Trades | 80 | | Tests Passed | 84/84 (100%) | | On-Chain USDC Transfers | 20 | | Receipts built, chained and batched off-chain | 80/80 | | Receipts anchored on-chain | 0/80 (no anchor transaction in this run) | | Amount Range | $0.00001 — $2.00 |

Full report: test-mainnet/MAYHEM_50_REPORT.md.

API Reference

See AGENTS.md for the complete API reference and copy-paste integration guide.

License

MIT — Parad0x Labs