Open data, priced per request,
paid by the agent that wants it.

What this is

dataduct ingests open datasets — public-domain and permissively-licensed — into its

own store, and sells individual records to whoever asks. Payment happens in the

request itself over x402: no account, no API key, no contract,

no minimum. An agent that has never seen this service before can discover a price

and complete a purchase in two HTTP round trips.

We are not selling the data. The data is open and you can go and get it yourself.

We are selling access and curation: one cleaned, deduplicated, licence-checked

copy behind a uniform interface, so you don't write and maintain 24 different

ingest pipelines against 24 providers who each change their formats without notice.

What you can rely on

You are never charged for a response you didn't get. Settlement runs only after

the handler produces a 2xx. A 404, a 400 or a 500 costs you nothing, and a

capability this deployment doesn't offer returns 501 *before* any payment is

requested.

A failed settlement gets you nothing. If your payment doesn't settle, you get

402 and no data — never a record you didn't pay for, and never a receipt for a

payment that didn't happen.

Retries don't double-charge. Present the same authorization for the same

resource and the original receipt is replayed rather than a second settlement

attempted. If your connection drops after paying, just retry.

Licence obligations travel with the data. Records that can't prove their licence

never reach the store, and a record from a CC-BY or OGL source carries the exact

attribution string you must pass downstream. That is a real obligation on you, not

a courtesy field.

What this isn't, yet

This deployment is not open for business. Pricing is placeholder, no payment

facilitator has been selected, and the analytical query tier is switched off. The

catalogue below shows exactly what is and isn't available rather than what is

planned — see Availability for the specifics.

The payment flow

Two round trips. The first tells you the price; the second pays it.

1 — Ask, and get a price

Any paid endpoint without an X-PAYMENT header answers 402 with an

x402 v1 challenge:

{
  "x402Version": 1,
  "error": "X-PAYMENT header is required",
  "accepts": [{
    "scheme": "exact",
    "network": "base",
    "maxAmountRequired": "100",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "payTo": "0x209693Bc6afc0C5328bA36FaF03C514EF312287C",
    "resource": "https://api.example.com/v1/nvd/CVE-2024-12345",
    "description": "nvd record CVE-2024-12345",
    "mimeType": "application/json",
    "maxTimeoutSeconds": 60,
    "extra": { "name": "USD Coin", "version": "2" }
  }]
}

Three fields are worth reading carefully, because they are where integrations go

wrong:

• maxAmountRequired is in atomic units. USDC has 6 decimals, so a price of

0.0001 USDC is "100". It is a string because a uint256 does not fit in a

double. Do not parse it as a number.

• asset is the token contract address, not a symbol. It is what your client

signs against.

• extra carries the EIP-712 domain for that token on that chain. It differs

per network — USDC on Base mainnet is "USD Coin", on Base Sepolia it is

"USDC" — and a wrong value produces a signature the facilitator rejects.

2 — Pay, and be served

Sign an EIP-3009 transferWithAuthorization, wrap it in a PaymentPayload,

base64 it, and resend the identical request with an X-PAYMENT header. The

payload decodes to:

{
  "x402Version": 1,
  "scheme": "exact",
  "network": "base",
  "payload": {
    "signature": "0x…",
    "authorization": {
      "from": "0xYourWallet",
      "to": "0x209693Bc6afc0C5328bA36FaF03C514EF312287C",
      "value": "100",
      "validAfter": "1753500000",
      "validBefore": "1753503600",
      "nonce": "0x…32 bytes…"
    }
  }
}

On success you get 200, the record, and an X-PAYMENT-RESPONSE header — base64

of the settlement result:

{ "success": true, "transaction": "0x…", "network": "base", "payer": "0xYourWallet" }

What the server checks before it charges you

The facilitator is treated as a signature and settlement oracle, not as the

authorization decision. Before any facilitator call, the request is rejected

locally if:

Overpayment is accepted. Paying someone else and presenting the receipt here is

not.

Ordering, and why it matters to you

The handler runs first; settlement is the last thing before the body is released.

That single ordering is what produces the guarantees:

• Non-2xx is never settled. If the record isn't in our store you get 404 and

are not charged.

• A failed settlement discards the body. You get 402 and no data.
• Verification moves no funds, so a payment that verifies but cannot settle

costs you nothing.

Idempotency and replay

Payments are keyed on the EIP-3009 nonce.

• Same nonce, same resource — treated as a retry. The stored receipt is

replayed, no second settlement is attempted, and the response carries

X-Payment-Idempotent-Replay: true. Safe to retry after a dropped connection.

• Same nonce, different resource — refused with 402. One authorization buys

one resource.

This is defence in depth rather than the primary control: under the exact scheme

the nonce is consumed on-chain at settlement, so the chain itself rejects a

genuine double-spend.

Status codes

Read these precisely — several mean "not your fault".

The 402/503 split is deliberate: an outage on our side must not look like a

routine payment challenge.

API reference

Base path /v1. Everything under it is payment-gated; everything outside it is free.

GET / — catalogue

Free. Returns every source with its licence tier, registered capabilities, price

bands and whether this deployment will sell it.

{
  "service": "dataduct",
  "x402Version": 1,
  "sourceCount": 24,
  "enabledCount": 3,
  "sources": [{
    "id": "nvd",
    "license_tier": "PD",
    "enabled": true,
    "capabilities": { "lookup": true, "search": false, "query": false, "attribution": false },
    "price": { "lookup": "0.0001", "search": "0.001", "query": "0.002" }
  }]
}

capabilities reflects this deployment, not the code: a capability the connector

registers but which is gated off reads false. Prefer

catalog.json if you are consuming this programmatically — it is

the same data plus resource-id formats and blocked reasons.

GET /readyz — readiness

Free. 200 when the deployment can safely take payment; 503 otherwise, with the

failing check named. **A 402 from a paid route does not imply the payment path

works** — the challenge is emitted before configuration is validated. This is the

endpoint that answers that question.

GET /v1/{source}/{resource} — point lookup

Returns one record. The {resource} format differs per source and is the single

thing most worth checking before you integrate — see the resourceIdFormat field

in catalog.json.

{
  "sourceId": "nvd",
  "recordId": "CVE-2024-12345",
  "license": "PD",
  "fetchedAt": "2026-07-20T06:00:00.000Z",
  "data": { }
}

attribution is present only for CC-BY and OGL sources, and when present it is an

obligation you must carry downstream.

POST /v1/{source}/search — semantic search

{ "query": "privilege escalation in container runtimes", "topK": 10 }

query is required; an empty or missing one is 400. topK is clamped to the

source's configured maximum (25 unless the connector sets otherwise) — values

above it are silently reduced rather than rejected. The response carries

{ source, query, count, results[] }, each result shaped like a lookup response.

POST /v1/{source}/query — analytical

Returns 501 on this deployment, before any payment challenge. No analytical

engine is bound. Twelve connectors register the capability, and it is gated off

for all of them rather than accepting payment for a query it cannot run.

When an engine is bound, request bodies are whitelisted per source — never raw

SQL. Five connectors (usaspending, cvefixes, fdic_ffiec, fred,

sam_fpds) explicitly reject a sql key with 400. Results are clamped to

1,000 rows / 1 MiB by default, tightened per source, and a clamped response sets

truncated: true.

Headers

CORS is open, and X-PAYMENT-RESPONSE / X-Request-Id are exposed, so a

browser-based agent can both send payment and read the receipt.

Errors

Every error body is JSON with an error field. Those that represent a fault on

our side also carry requestId — that is what reconciliation and support are keyed

on, so log it.

Integrate

Try it now, for free

The catalogue, readiness and the 402 challenge all work without paying anything.

# What's available, and what does it cost?
curl -s https://<host>/ | jq '{enabledCount, sources: [.sources[]|select(.enabled)]|map({id,price})}'

# Can this deployment safely take money?
curl -s https://<host>/readyz | jq

# Ask for a record without paying — this is the price quote.
curl -i https://<host>/v1/nvd/CVE-2024-12345

That last call returns 402 with the challenge. Nothing is charged, and you can

call it as often as the rate limit allows to discover pricing.

Build the payment header

The challenge is x402 v1, so the standard clients (x402-fetch, x402-axios)

apply. If you are constructing it yourself, the header is base64 of the payload —

sign the authorization with your wallet, then:

// Build X-PAYMENT from a signed EIP-3009 authorization.
function paymentHeader({ signature, authorization, network = 'base' }) {
  const payload = { x402Version: 1, scheme: 'exact', network, payload: { signature, authorization } };
  const bytes = new TextEncoder().encode(JSON.stringify(payload));
  let binary = '';
  for (const b of bytes) binary += String.fromCharCode(b);
  return btoa(binary);
}

// Read the receipt back off a served response.
function settlement(res) {
  const h = res.headers.get('X-PAYMENT-RESPONSE');
  if (!h) return null;
  const binary = atob(h);
  const bytes = Uint8Array.from(binary, (c) => c.charCodeAt(0));
  return JSON.parse(new TextDecoder().decode(bytes));
}

Take value, to, network and the EIP-712 domain straight from the challenge's

accepts[0] — do not hardcode them. maxAmountRequired is already in atomic

units; pass it through as authorization.value unchanged.

Retry safely

If a request fails after you sent payment, resend it **with the same nonce and the

same URL**. You will get the original receipt back and will not be charged twice.

Changing either the nonce or the resource makes it a new purchase.

Carry attribution downstream

Six sources are CC-BY or OGL. Their responses include an attribution string, and

passing it on is a licence condition — not a formatting nicety.

{
  "sourceId": "onet",
  "recordId": "15-1252.00",
  "license": "CC-BY",
  "attribution": "This product incorporates data from O*NET, developed by the U.S. Department of Labor/Employment and Training Administration (USDOL/ETA), used under the CC BY 4.0 license.",
  "data": { }
}

The guarantee runs the other way too: a record that cannot prove its licence is

dropped before it ever reaches the store, and a CC-BY record that somehow lost its

attribution fails at the serving boundary rather than being served bare. So an

absent attribution on a CC-BY source is a bug worth reporting, not an optional

field.

Rate limits

120 requests per minute per IP on /v1/*. Over the limit returns 429 with

Retry-After: 60. The free catalogue and /readyz are not limited.

Before you build against this

Read Availability. Three sources are currently purchasable, the

analytical tier is off, prices are placeholder, and no payment facilitator is

configured — so the paid path cannot complete end to end today. The free surface,

the challenge format and the record shapes are stable enough to build against.