Docs · Reference

One autonomous payment, end to end.

The production composition for one autonomous payment, using the Commerce SDK. It adds no new wallet, executor or payment route: your executor pays, and OCD records independent evidence around it.

intent + caller policy
  → OCD preflight
  → your executor authorizes and submits
  → optional provider claim
  → OCD chain observation and reconciliation
  → signed Commerce Receipt
  → optional caller-signed Agent Evidence bundle

What each stage establishes

Stage	Establishes	Does not establish
Preflight	The proposal matched your policy (`ALLOW`, `REQUIRE_APPROVAL`, `BLOCK` or `UNKNOWN`).	Wallet authority, or that a payment will happen.
Executor	Its own authorization and submission outcome.	OCD policy approval, or confirmed settlement.
Provider claim	What the provider reported, kept as a claim.	Chain settlement.
OCD observation	The supported on-chain transfer and its finality.	Service delivery, counterparty identity, or why a provider acted.
Receipt proof	The receipt’s integrity and authenticity under the verifier contract.	Safety, compliance, delivery, or the truth of every input.

1. Open one operation with the payment and policy

Install the SDK and the standard x402 client packages. The $0.01 preflight is paid with x402 from a dedicated, low-balance fee wallet you control; its signer is never sent to OCD.

npm install @onchaindiligence/sdk @x402/core @x402/evm @x402/fetch

import { x402Client } from '@x402/core/client'
import { ExactEvmScheme } from '@x402/evm/exact/client'
import { wrapFetchWithPayment } from '@x402/fetch'
import { BASE_USDC, apiPurchasePolicy, createCommerceClient } from '@onchaindiligence/sdk/commerce'
import { NodeFileRecoveryStore } from '@onchaindiligence/sdk/commerce/node'

// Wrap your own dedicated fee-payer signer. Never hard-code a key.
const paidFetch = wrapFetchWithPayment(
  globalThis.fetch.bind(globalThis),
  new x402Client().register('eip155:8453', new ExactEvmScheme(feePayer)),
)

const ocd = createCommerceClient({ recovery: new NodeFileRecoveryStore('./ocd-recovery'), fetch: paidFetch })
const { policy } = apiPurchasePolicy({ maxAmount: '1.00', allowedNetwork: 'eip155:8453', allowedAsset: BASE_USDC })

const operation = await ocd.open({
  intent: 'pay the approved merchant service',
  action: { kind: 'PAYMENT', resource: 'https://merchant.example/agent-service', network: 'eip155:8453',
            asset: BASE_USDC, amount: '0.50', sender: null, recipient: '0x…' },
  policy,
})

The recovery store holds the operation’s recovery credential and finalization capability. They are operational secrets: keep them server-side, never in browser storage, a receipt or an evidence bundle. apiPurchasePolicy is only a starter template; supply your own policy in production.

2. Preflight before reaching an executor

const preflight = await operation.preflight()
if (preflight.kind !== 'ready') {
  // Blocked, approval-required, pending or error: do not call any executor.
  return
}

ready carries an ALLOW decision and its signed preflight receipt, plus a one-time finalization capability. That capability lets you record this lifecycle later; it never permits a payment.

3. Let your executor authorize and submit

// A CommerceExecutor around your own wallet or provider. Adapters exist for
// x402, PayBox, Turnkey, Crossmint, Coinbase CDP and Circle.
const execution = await operation.execute({ executor })
if (execution.kind !== 'execution-recorded') {
  // 'pending' keeps the same execution identity for safe resumption:
  // never create a replacement payment because an outcome is ambiguous.
  return
}

The executor contract is deliberately narrow: prepare() creates a durable payment identity without broadcasting, submit() is called at most once for it, and resume() queries that same identity instead of paying again. OCD never receives the executor’s key, and an OCD ALLOW never overrides the executor’s own rules.

4. Preserve a provider claim, without upgrading it

Existing adapters submit their provider evidence automatically where supported. A provider-neutral integration can submit what the provider reported after a terminal result. It is recorded as a caller-reported provider claim: it neither finalizes the operation nor changes settlement. See provider evidence.

5. Observe and reconcile independently

let finalized = await operation.observeAndFinalize()
while (finalized.kind === 'pending') {
  // Persist and retry the same operation later; the result states the safe next action.
  finalized = await operation.observeAndFinalize()
}
const receipt = finalized.kind === 'receipt-produced' ? finalized.receipt : null

OCD derives the receipt from the bound preflight receipt and its own independent chain observation. It reports the policy decision, executor state, settlement state and the exact preflight-versus-observation checks separately, and states a binding strength — TRANSFER_MATCH_ONLY, EXECUTOR_CORRELATED or PAYMENT_IDENTITY_LINKED — only when the durable binding supports it. Missing provider or chain evidence is an evidence gap, not a contradiction, and no binding level is inferred from matching payment fields alone.

6. Verify and keep the signed receipt

The receipt is a signed public-action-receipt.v1 envelope, safe to share with a second reader. Check it online, or offline with the CLI and OCD’s published key material:

npx -p @onchaindiligence/cli ocd verify commerce-receipt.json --trust ocd-signing-keys.json

Read decision, execution, settlement, checks and limitations separately. VALID verifies integrity and authenticity under the verifier contract only; it does not prove delivery or payment safety. Keys are listed on the keys page.

7. Optional: a portable Agent Evidence bundle

If you need a portable record of the whole run, assemble your own Principal → Agent → Mandate → Run → Evidence → Policy → Decision → Execution graph with @onchaindiligence/agent-evidence, link the receipt, and seal it with your own signer. See Agent Evidence. Never record a provider claim as a chain observation, or a valid receipt as proof of delivery.

A real reference receipt

Receipt OCD-RCP-ASER-TH5K-ZN3B-TVC5 shows the full receipt-side outcome of one real payment: policy ALLOW, execution CONFIRMED, settlement CONFIRMED on Base USDC, the earlier observation retained rather than overwritten, and service delivery not independently verified. It is evidence of that one observed lifecycle, not a guarantee for any other payment.

Ready to try it? Start with the pilot quickstart.