Skip to content
Directory

Use Cases

x402 payments with sub-payments

The x402 protocol adds native payments to HTTP via the 402 Payment Required status code. A server returns a 402 with payment instructions; the client pays and retries the request.

Directory makes x402 sub-payments possible. An operator node can split incoming payments across multiple addresses at the domain — writers, contributors, the platform — all resolved through the same node.

How it works

A media company runs a Directory node at publisher.com. The domain is payable. Writers have individual addresses.

publisher.com          → company treasury
alice@publisher.com    → Alice (staff writer)
bob@publisher.com      → Bob (contributor)

When a reader hits a paywalled article, the server returns a 402 with Directory addresses as payment targets:

HTTP/1.1 402 Payment Required
X-Payment: directory


{
  "price": "0.50",
  "currency": "USDC",
  "payments": [
    { "address": "publisher.com", "split": 0.70 },
    { "address": "alice@publisher.com", "split": 0.20 },
    { "address": "bob@publisher.com", "split": 0.10 }
  ]
}

The client resolves each address through the same Directory node, gets signed routing contracts for each, verifies the signatures, and executes the transfers. 70% goes to the company, 20% to the writer, 10% to the editor — all in a single page load.

Why Directory matters here

Without Directory, the server would have to embed static wallet addresses in the 402 response. Those addresses are chain-specific, can’t be rotated, and leak on-chain identity. If Alice changes wallets, every article she ever wrote has stale payment instructions.

With Directory:

  • The publisher controls routing for everyone. Alice changes her wallet? The publisher updates her YAML file. Every future resolve returns the new destination. Old articles don’t need updating.
  • Chain-agnostic. The client resolves against what it can send. Has USDC on Base? The node returns Base addresses. Has ETH? Returns ETH addresses. The 402 response doesn’t need to know.
  • Ephemeral destinations. The publisher can generate unique deposit addresses per article view for privacy and reconciliation.
  • Signed contracts. The client can verify that the payment instructions came from publisher.com and haven’t been tampered with by a CDN or proxy.

Other split payment scenarios

The same pattern works anywhere value splits across a domain:

  • SaaS platforms — platform.com takes a platform fee, seller@platform.com gets the rest.
  • DAOs — dao.org routes to the treasury, contributor@dao.org routes to individual contributors.
  • Agencies — agency.com takes a cut, freelancer@agency.com gets paid directly.
  • Music — label.com takes distribution, artist@label.com gets royalties.
  • Open source — project.org routes to the project fund, maintainer@project.org routes to the maintainer.

AI agent payments

AI agents need to pay for services programmatically. Directory addresses are HTTPS-native — no wallet SDKs, no chain-specific libraries, just POST /resolve.

An agent that needs to pay for an API call:

const contract = await fetch('https://api.provider.com/resolve', {
  method: 'POST',
  body: JSON.stringify({ address: 'api.provider.com' }),
});

The provider’s node returns a signed routing contract. The agent verifies it, sends payment, and proceeds. The provider can rotate deposit addresses, change chains, or adjust pricing without the agent needing to update anything.

Payroll

A company runs a node at company.com. Every employee has an address: alice@company.com, bob@company.com. Employees configure their own routing preferences — which wallet, which chain, whether to split between crypto and fiat.

The payroll system resolves each address at pay time, gets fresh routing contracts, and executes transfers. If an employee switches from Ethereum to Solana between pay periods, the next payroll run picks it up automatically. No HR ticket. No manual wallet update.

Invoicing

An invoice includes a Directory address instead of bank details:

Pay to: acme.com
Amount: $5,000 USD

The payer’s software resolves acme.com, gets a signed routing contract with ACH details or a crypto address, verifies the signature against Acme’s DNS-published key, and initiates the transfer. Acme can change their banking details at any time without reissuing invoices.

Point of sale

A payment terminal resolves store.com or cashier@store.com at the time of sale. The routing contract is valid for 5 minutes — long enough for the customer to scan and pay, short enough that stale instructions never accumulate. The store can route different registers to different accounts, rotate deposit addresses per transaction, or switch chains without touching the terminal software.