Implementation reference

Reference

Concrete endpoints, headers, JSON shapes, CLI entry points, and operational handles for the current implementation. Public protocol names are d402; legacy dnc aliases remain where compatibility requires them.

HTTP endpoints

Method	Path	Response
GET	`/health`	Gateway liveness and public policy.
GET	`/.well-known/d402-gateway.json`	Discovery document for clients.
GET	`/.well-known/dnc-gateway.json`	Legacy compatibility discovery endpoint.
GET	`/capabilities`	Indexed capability registrations and gateway-accepted manifests.
GET	`/healthz`	Simple readiness probe for public indexes such as Zero.
GET	`/openapi.json`	OpenAPI 3.1 document with payment metadata.
POST	`/tasks`	`402` challenge, `200` sync result, or `202` async status.
GET	`/tasks/{taskId}`	Task record.
GET	`/tasks/{taskId}/result`	Accepted result or `202`.
GET	`/tasks/{taskId}/receipt`	Validation and settlement receipt.

Headers

Header	Direction	Purpose
`PAYMENT-REQUIRED`	Gateway -> client	Base64 JSON x402-style challenge.
`PAYMENT-SIGNATURE`	Client -> gateway	Base64 JSON payment payload supplied by x402 wallet/client.
`PAYMENT-RESPONSE`	Gateway -> client	Base64 JSON settlement response.
`Authorization: Payment ...`	Client -> gateway	Solana direct payment proof body.
`x-d402-idempotent-replay`	Gateway -> client	Current implementation marker for accepted same-task replay.
`x-dnc-idempotent-replay`	Gateway -> client	Legacy compatibility marker for accepted same-task replay.

Health response

GET /health

{
  "ok": true,
  "nodeId": "gateway:abc123",
  "policy": {
    "price": "$0.01",
    "capabilityId": "web.page_to_markdown@1",
    "mode": "single",
    "fanout": 1,
    "quorum": 1,
    "deadlineMs": 30000,
    "allowAsync": true,
    "paymentRouter": "channel",
    "creatorCommission": {
      "pricingMode": "included",
      "scope": "exact-manifest",
      "maxRateBps": 2000,
      "payoutRail": "solana",
      "requiresEscrowForDirectProviderPayTo": true
    }
  }
}

Task request

POST /tasks

{
  "sync": true,
  "input": {
    "url": "https://example.com",
    "timeoutMs": 10000
  },
  "payment": {
    "refundAddress": "BuyerRefundWalletWhenEscrowIsUsed"
  }
}

Settlement receipt shape

GET /tasks/{taskId}/receipt

{
  "taskId": "task:...",
  "validationReceipt": {
    "status": "accepted",
    "acceptedClaimCids": ["sha256:..."],
    "rejectedClaimCids": []
  },
  "settlement": {
    "payouts": [
      {
        "account": "WorkerWallet...",
        "workerId": "node:worker",
        "amount": 0.009,
        "grossAmount": 0.01,
        "reason": "accepted-result"
      },
      {
        "account": "CreatorWallet...",
        "amount": 0.001,
        "grossAmount": 0.01,
        "reason": "creator-commission",
        "rateBps": 1000,
        "rail": "solana",
        "manifestCid": "sha256:...",
        "registrationCid": "sha256:...",
        "publisher": "node:publisher",
        "namespace": "example"
      }
    ],
    "refunds": []
  }
}

CLI commands

Command	Purpose
`d402 node`	Start a peer, worker, gateway, or bootstrap role.
`d402 task`	Submit a task through the peer network.
`d402 http-task`	Call the HTTP gateway and inspect payment challenges.
`d402 x402-task`	Use a real buyer wallet to complete x402 payment and retry.
`d402 solana-task`	Inspect or complete Solana direct payment.
`d402 solana-finalizer`	Replay persisted Solana task escrow finalization.
`d402 solana-channel-maintainer`	Publish roots, withdraw claims, and reclaim safe rent.
`d402 capability template`	Create a new capability manifest skeleton.
`d402 capability validate`	Validate capability manifest shape and CID.
`d402 capability register`	Create a signed registration envelope, including optional creator commission terms.
`d402 capability implementation create`	Create a signed runner package/release manifest for workers to install or audit.
`d402 capability implementation install`	Verify and install a runner implementation with local env substitution.
`d402 ops-status`	Inspect gateway safety state.
`d402 ops-monitor`	Run continuous safety monitoring and alert dedupe.
`d402 devnet`	Run a local multi-process TCP devnet.

Common environment variables

Name	Use
`D402_BUYER_PRIVATE_KEY`	EVM buyer key for x402 test/client flows.
`D402_PROVIDER_PAYOUT_WALLET`	EVM provider payout wallet.
`D402_X402_NETWORK`	EVM CAIP-2 network, for example `eip155:8453`.
`D402_ESCROW_FACTORY_ADDRESS`	Base escrow factory contract address.
`D402_ESCROW_TX_PRIVATE_KEY`	Gas signer for escrow settlement transactions.
`D402_SOLANA_RPC_URL`	Solana RPC endpoint.
`D402_SOLANA_USDC_MINT`	Solana USDC mint.
`D402_SOLANA_ESCROW_PROGRAM_ID`	Solana escrow/channel program ID.
`D402_MAX_CREATOR_COMMISSION_BPS`	Gateway cap for signed creator commissions. Defaults to `2000`.
`D402_SAFETY_MAX_TASK_BUDGET`	Gateway per-task budget cap.
`D402_SAFETY_MAX_CHANNEL_BALANCE_ATOMIC_UNITS`	Per-channel balance cap.

Known public constants

Base USDC: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
Solana USDC: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
Solana deployed program ID: GG8giaUFeegrwD2T2fuHdSvriMsXBi12fmQ4edtFas2e
Initial capability: web.page_to_markdown@1
Creator commission schema: d402.creator_commission@1
Default maximum creator commission: 2000 bps, or 20%
Preferred discovery path: /.well-known/d402-gateway.json