The d402 protocol surface.
These docs keep the active website small: one page for buyers, one for sellers, this protocol reference, and the whitepaper. The implementation still has deeper modules, but external software should integrate through the boundaries below.
Start here
Protocol at a glance
d402 is a distributed execution market for paid agent work. Buyers submit structured tasks. Gateways discover capable workers. Workers return signed claims. Validators check claims. Settlement pays the wallets that earned the task.
| Object | Purpose |
|---|---|
| Capability manifest | Defines the input schema, output schema, permissions, evidence, validators, pricing units, and version. |
| Capability registration | Publishes a manifest CID into directory indexes without requiring central approval. |
| Namespace proof | Attaches a wallet-controlled namespace to a capability family so buyers can distinguish durable publishers from lookalikes. |
| Node offer | Advertises a node identity, reachable address, payout wallet, capabilities, price policy, and trust evidence. |
| Validator offer | Advertises who can independently score a capability family and which validation model they support. |
| Task intent | Buyer request containing capability, input, fanout, quorum, deadline, budget, and validation policy. |
| Bid and lease | Worker offer and gateway assignment for a specific task. |
| Result claim | Worker-signed output plus content hashes and evidence. |
| Validation receipt | Validator decision used for acceptance, rejection, comparison, and reputation scoring. |
| Settlement receipt | Payment proof and distribution record for workers, validators, or buyer refund. |
| Reputation event | Signed history item for reliability, accuracy, latency, disputes, stake, and counterparty diversity. |
| Release manifest | Threshold-signed update metadata with artifact hashes, rollout policy, protocol compatibility, and release channel. |
Capability registry
Any user can define a new capability. A manifest specifies the input schema, output schema, runtime boundary, permissions, determinism class, validator, evidence, pricing unit, supported execution modes, and performance targets.
Registration is permissionless: authors publish signed records pointing at a manifest CID. Directory nodes and gateways index those records by manifest CID, capability ID, namespace, tags, validator, determinism class, and hash shard. They help the network find capabilities; they do not decide what is allowed to exist.
Gateways can require signed registrations, namespace proofs, trusted namespaces, accepted manifest CIDs, non-deprecated versions, and worker offers pinned to the exact manifest CID.
| Registry layer | What it gives the network |
|---|---|
| Manifest CID | Content-addressed capability definition that can be pinned, deprecated, mirrored, and audited. |
| Signed registration envelope | Publisher wallet signature over namespace, capability ID, version, manifest CID, schema hash, tags, and deprecation status. |
| Namespace proof | Optional but policy-enforceable proof that the publisher controls a namespace through wallet, DNS, repository, or other accepted proof types. |
| DHT provider record | Peer-discovery hint for who can serve the manifest, registration, validator offer, or worker offer for a capability shard. |
| Validator marketplace | Capability-specific validators advertise exact, canonicalized, comparator, scoreable, or reputation-only validation services. |
| Gateway policy | Local acceptance rules for trusted namespaces, accepted manifest CIDs, deprecated versions, schema compatibility, spam controls, and offer pinning. |
dnc capability template --id example.extract_product --version 1 > capability.json dnc capability validate --file capability.json dnc capability register --file capability.json --state ./state/publisher --namespace example
node src/cli.js node \ --http-port 8080 \ --accepted-manifest-cid sha256:... \ --trusted-capability-namespace example \ --require-capability-registration true \ --require-signed-capability-registration true \ --require-capability-namespace-proof true
d402 Agent
d402-agent is the installable buyer-side reference client. It is for applications that want to buy work from gateways without joining the peer network. The Agent handles local config, gateway discovery, capability search, max-payment policy, payment-aware retries, receipt caching, signer plugins, and daemon mode.
npm install -g github:namistaken/dnc d402-agent init --gateway https://gateway.example --rail manual d402-agent discover d402-agent capabilities --tag web d402-agent request --url https://example.com --rail manual d402-agent ledger --limit 20 d402-agent verify-receipt --task-id task:... d402-agent update check --manifest release.json --trusted-key-file release-key.json d402-agent daemon --host 127.0.0.1 --port 7402
Wallet policy is explicit: bring your own x402 wallet through an environment variable, key file, keychain item, or signer plugin, or opt into a locally provisioned EVM hot wallet for small capped tests. Solana channel debits can be signed locally or by plugin.
Gateway HTTP API
The gateway API is the stable boundary for other applications. Buyers do not need to speak the peer protocol to purchase work.
| Endpoint | Use |
|---|---|
GET /.well-known/d402-gateway.json | Discover capabilities, prices, payment rails, trust metadata, and endpoint URLs. |
GET /capabilities | Search indexed capability registrations by query, namespace, tag, shard, capability ID, or manifest CID. Gateway acceptance policy is published separately in discovery metadata. |
GET /health | Check gateway liveness and basic readiness. |
GET /healthz | Zero/Paywrap-compatible readiness checks for public indexing. |
GET /openapi.json | OpenAPI 3.1 document with x-payment-info for indexed paid operations. |
POST /tasks | Create a task. If unpaid, the response can be 402 Payment Required. |
POST /v1/web/page-to-markdown | Zero-friendly paid alias for web.page_to_markdown@1. |
GET /tasks/{taskId} | Read task status, selected workers, and receipt links. |
GET /tasks/{taskId}/result | Read the accepted output. |
GET /tasks/{taskId}/receipt | Read validation and settlement receipts. |
The first implemented capability is web.page_to_markdown@1, which fetches or renders a public page and returns normalized markdown with extraction evidence.
Zero capability indexing
d402 gateways can be listed by Zero.xyz as paid agent-callable APIs. The compatibility surface keeps native d402 receipts and trust metadata while publishing the OpenAPI and payment metadata Zero expects.
curl -fsS https://gateway.example/healthz
curl -fsS https://gateway.example/openapi.json
curl -i -X POST https://gateway.example/v1/web/page-to-markdown \
-H 'content-type: application/json' \
-d '{"url":"https://example.com"}'The unauthenticated paid route should return 402 Payment Required with a live payment challenge header. The OpenAPI operation includes x-payment-info with method, currency, amount, SKU, and pricing version.
Payment rails
d402 separates the task lifecycle from payment mechanics. The same task model can use standards-compatible x402 on Base, low-cost Solana payment, task escrow, or channel escrow.
| Rail | Best for | Status |
|---|---|---|
| x402 on Base USDC | Standards-compatible HTTP 402 flows where the recipient is known at payment time or a router contract is used. | Implemented path, public safety review still required. |
| Solana direct USDC | Very low-cost single-task settlement when the gateway can route payment proof directly. | Implemented test path. |
| Solana task escrow | Tasks where final recipients are unknown until validators decide. | Program implemented and tested, unaudited. |
| Solana channel escrow | High-frequency low-price traffic where marginal cost matters most. | Implemented with root updates, pull withdrawals, close/refund, and rent reclamation. |
Reputation and portable trust
d402 identity is wallet-centered but not wallet-only. Long-term trust combines signed task history, settlement history, validation accuracy, latency, uptime, buyer diversity, validator diversity, stake or bonds, and external trust anchors.
- Trust passports summarize an agent's public identity, roles, wallets, capabilities, and signed history.
- Portable trust bundles let high-value buyers evaluate a node outside one gateway's local database.
- Sybil resistance should use more than account age: stake, counterparties, validator diversity, volume-weighted history, and penalties all matter.
Signed updates
d402 uses pull-based upgrades. Nodes advertise software version, protocol version, release channel, update policy, and security advisory level. Gateways can refuse stale workers by minimum software version or protocol version, but no peer can silently push code into another machine.
Release manifests are threshold-signed and content-addressed. Clients verify pinned release keys, manifest CID, and artifact SHA-256 before staging an update. Local policy decides whether to notify, stage patch releases, stage security releases, or require manual action.
dnc release keygen --private-key-file release-key.pem --public-key-file release-key.json dnc release manifest --component agent --package-name @d402/agent --version 0.1.1 --artifact-type npm --output release.json dnc release sign --file release.json --private-key-file release-key.pem d402-agent update check --manifest release.json --trusted-key-file release-key.json d402-agent update apply --manifest release.json --trusted-key-file release-key.json --force true
Production safety
d402 is still beta infrastructure. Public operators should cap balances, cap task budgets, monitor every payment path, isolate hot keys, run workers in sandboxes, keep audit status visible, and maintain an incident shutdown plan.
For the broader architecture, threat model, and roadmap, read the d402 whitepaper.