# OnChainDiligence

Independent payment evidence for autonomous agents.

Use OnChainDiligence (OCD) to:

- inspect a proposed payment against explicit user rules before sending;
- retrieve existing signed OCD receipts;
- verify receipt proofs;
- independently observe a supported payment that already happened, and create or reuse a signed observation receipt.

An agent can ask OCD to independently create evidence for a completed transaction over MCP or HTTP. OCD does not send payments, hold wallet keys or authorize spending. It is not a wallet, an executor or a credential store. Use it from an AI/coding agent that can access the documented MCP, A2A or HTTP surface; A2A v1 offers inspection, retrieval and verification only.

## Decision guide

| Situation | Do this |
|---|---|
| Proposed payment and explicit rules | `inspect_payment` |
| Completed supported payment and the exact transaction reference | `create_payment_receipt` (MCP), or `POST /observe-payment` (HTTP, no MCP) |
| You have an `OCD-RCP-...` ID and want its contents | `get_receipt` |
| You want cryptographic proof status of a receipt | `verify_receipt` |
| You want to send money | OCD is not the executor. Use the user's authorized wallet or payment system. |

For A2A, discover the Agent Card below and choose its advertised `inspect-payment`, `get-receipt` or `verify-receipt` skill. Receipt creation requires MCP or HTTP, not A2A v1.

## Live surfaces

### Public MCP (free, no account, no API key)

`https://mcp.onchaindiligence.com/public/mcp` (Streamable HTTP)

Exactly four tools:

- `inspect_payment`
- `get_receipt`
- `verify_receipt`
- `create_payment_receipt`

`create_payment_receipt` creates evidence for a completed payment. It does not execute payments. The public MCP never sends payments, signs wallet transactions, holds funds or authorizes spending.

### A2A (free, public evidence access)

Agent Card: `https://mcp.onchaindiligence.com/.well-known/agent-card.json`

Endpoint: `https://mcp.onchaindiligence.com/a2a`

Protocol: A2A 1.0 / JSON-RPC.

Exactly three advertised skills:

- `inspect-payment`
- `get-receipt`
- `verify-receipt`

Discover the Agent Card, read the skill descriptions/examples, and construct the request for the user's goal. A2A is a separate protocol adapter over existing OCD evidence logic, not a replacement for MCP. A2A v1 does not expose receipt creation, payment execution, wallet signing, private/workspace tools, paid x402 tools or agent provenance mutation. It does not authorize spending.

Calling OCD through A2A does not establish that the caller made the payment, controls a wallet, or has the identity it claims. Provider claims remain separate from independent settlement evidence; `VALID` retains the narrow cryptographic meaning described below.

### Completed-payment HTTP evidence (free, no account, no API key)

`POST https://mcp.onchaindiligence.com/observe-payment`

OCD independently observes a completed, supported transaction and creates a signed observation-only receipt, or returns the existing one for that network and transaction.

MCP `create_payment_receipt` and HTTP `/observe-payment` are two interfaces to the same observation-receipt capability, with the same semantics, networks and receipts. Use the HTTP route when you have no MCP client.

Supported networks:

| Network | Asset | `network` value |
|---|---|---|
| Base | USDC | `eip155:8453` |
| Ethereum | USDC | `eip155:1` |
| Tempo | pathUSD | `eip155:4217` |
| Arc | USDC | `eip155:5042` |
| Solana | USDC | `solana:mainnet` |

Arc: OCD reads Arc's native USDC system Transfer stream at 18-decimal precision, for transactions at or below the finalized (committed) head. That stream is not an ordinary ERC-20 contract.

## Before a payment: `inspect_payment`

Call it with the proposed `action` (`kind: "PAYMENT"`, `network`, `asset`, `amount`, `recipient`, optional `sender` and `resource`) and the user's `policy` (for example `max_amount`, `allowed_networks`, `allowed_assets`, `expected_recipient`). It is deterministic: no external lookups, no signing, no payment.

Result: `ALLOW`, `REQUIRE_APPROVAL` or `BLOCK`.

`ALLOW` is a comparison of the proposal against the supplied rules. It does not authorize wallet spending, does not prove the payment is safe or compliant, and does not send anything. The agent or executor remains responsible for execution and for the user's approval.

## After a payment: `create_payment_receipt` or `POST /observe-payment`

`create_payment_receipt` takes exactly `network` and `transaction_reference` (an EVM transaction hash or a Solana signature) and nothing else. It independently observes that completed transaction and creates a signed OCD observation receipt, or returns the existing one. It returns a state (`RECEIPT`, `PENDING`, `UNAVAILABLE` or `INVALID_INPUT`), and for a receipt the `receipt_id`, `existing`, `decision`, `settlement_status` and `receipt_url`, all read from the signed receipt.

It never sends payment, signs a wallet transaction, authorizes spending, establishes that the requesting AI agent made the payment, proves wallet ownership, infers provider identity, or proves merchant or service delivery.

Pending (`PENDING`) or unavailable (`UNAVAILABLE`): retry the SAME network and transaction reference later. Never repeat the payment.

The HTTP equivalent is `POST /observe-payment`. Minimal request:

```json
{ "network": "eip155:5042", "transaction_hash": "0x..." }
```

```bash
curl -s -X POST https://mcp.onchaindiligence.com/observe-payment \
  -H "Content-Type: application/json" \
  -d '{"network":"eip155:5042","transaction_hash":"0x<64 hex characters>"}'
```

`transaction_hash` is an EVM transaction hash, or a Solana transaction signature. Optional `expected_recipient`, `expected_asset` and `expected_amount` are your own claims, compared against what OCD observes and never treated as evidence.

Responses:

| Status | Meaning | What to do |
|---|---|---|
| 200 | Signed receipt created, or the existing receipt for that transaction (a header marks an existing one) | Keep the `OCD-RCP-...` ID |
| 425 | Not found yet, or not enough confirmations | No receipt was issued yet. Retry the SAME request later. |
| 503 | RPC or signing temporarily unavailable | Retry the SAME request later. |
| 400 | Invalid input, or an unsupported network or asset | Fix the input. Do not retry unchanged. |
| 429 | Rate limited | Slow down, then retry. |

If observation is pending, never resend the payment. The payment already happened; only the evidence request is retried. This applies equally to `create_payment_receipt`. If a response is lost or unexpected, retry the same request: it returns the existing receipt if one was created.

## Receipts

A receipt ID looks like `OCD-RCP-XXXX-XXXX-XXXX-XXXX`. Keep retrieval and verification separate.

1. `get_receipt` with `receipt_id` returns the signed receipt.
2. `verify_receipt` with `receipt_id` (or a signed `envelope`) returns `VALID`, `INVALID` or `UNVERIFIABLE`.

`VALID` means the receipt bytes, digest and signature are consistent under the OCD verifier contract. `VALID` does not by itself prove:

- authorization of the payment;
- safety or compliance;
- payment success, unless the receipt's settlement evidence says so;
- service delivery;
- real-world identity;
- agent identity;
- provider honesty.

Receipt page: `https://onchaindiligence.com/r/<receipt_id>`. Receipts are unlisted, not private: anyone with the exact ID can retrieve and verify one.

## Observation receipt semantics

A receipt created after a payment, without an OCD preflight, has `decision: UNKNOWN` and `authorized: null`. That is correct: OCD did not establish a pre-payment policy decision. Never describe it as `ALLOW`.

It can still independently establish facts, when the receipt actually contains them: the transaction was found, execution did not revert, a supported stablecoin transfer was observed, and settlement is confirmed. When a transaction holds several transfers and nothing identifies the intended one, sender, recipient and amount are left empty, not guessed.

## Agent identity boundary

An agent calling OCD does not mean that agent caused the payment. Do not infer "Claude paid", "ChatGPT paid", "Gemini paid" or "this MCP client was the payer" from a transaction reference or a receipt request. Signed agent provenance is a separate evidence mechanism, and an observation receipt does not supply it.

## Wallet Evidence (dashboard)

`https://app.onchaindiligence.com/#wallet-evidence`

A user connects a wallet or pastes an address and explicitly reads bounded recent activity on Base, Tempo and Arc. Classifications:

- Agent-linked
- OCD-linked
- Saved receipt
- Unlinked

Unlinked stays Unlinked. For a supported observed payment, the user can explicitly create a signed observation receipt. That receipt does not turn the transaction into Agent-linked or OCD-linked.

## Security

Never send OCD private keys, seed or recovery phrases, wallet signing credentials, API secrets unrelated to OCD, or payment authorization tokens. OCD never needs them to inspect or observe a public transaction. Do not put secrets in receipt IDs, transaction references or resource URLs.

## Examples

Inspect a proposed payment (arguments for the `inspect_payment` tool):

```json
{
  "action": { "kind": "PAYMENT", "network": "eip155:8453", "asset": "<USDC contract address>", "amount": "0.001", "recipient": "0x<recipient>" },
  "policy": { "max_amount": "1", "allowed_networks": ["eip155:8453"], "expected_recipient": "0x<recipient>" }
}
```

Create evidence for a completed Arc payment: call `create_payment_receipt` with `{ "network": "eip155:5042", "transaction_reference": "0x<64 hex characters>" }`, or send the curl request above with your own transaction hash.

Retrieve and verify a receipt: call `get_receipt` and then `verify_receipt` with `{ "receipt_id": "OCD-RCP-ZJZX-NR63-YQHY-MK6A" }`. That ID is an example observation-only Arc receipt (1 USDC, decision `UNKNOWN`, settlement `CONFIRMED`, proof `VALID`). Reading it does not mean the caller made that payment: <https://onchaindiligence.com/r/OCD-RCP-ZJZX-NR63-YQHY-MK6A>

## Links

- Docs: https://onchaindiligence.com/docs
- Past-payment receipt API: https://onchaindiligence.com/docs#observe-payment
- Create a receipt in the browser: https://onchaindiligence.com/create-receipt
- Machine-readable index: https://onchaindiligence.com/llms.txt