# Receipts

> One receipt for every outgoing USDC transfer of a company wallet, with the seller, what was bought, the agent that paid and a EUR value.

The chain says how much was paid and to which address. A receipt adds who is behind that address, what was bought, which agent paid and what it was worth in EUR.

## What becomes a receipt

Every outgoing USDC transfer on Base from a confirmed wallet of the company, reported or not. The receipt belongs to the company and names the agent that operated the wallet when it paid. Payments from wallets we do not know, and payments on other networks, do not become receipts.

## Report what you bought

Call `receipts.record` right after every x402 payment. Only `tx_hash` is required, the rest makes the receipt better.

| Field | What to send |
|---|---|
| `tx_hash` | The settlement transaction from the `PAYMENT-RESPONSE` header (base64 JSON, field `transaction`) |
| `resource_url` | The URL you paid for, starting with `https://` |
| `amount` | What you paid in USDC, like `"0.002"`, up to six places |
| `description` | What you bought, in your words, up to 280 characters. The seller's catalogue wins when it knows the URL |
| `pay_to` | The payTo address from the payment requirements |
| `payment_response` | The raw `PAYMENT-RESPONSE` header, if you still have it |

Over REST it is `POST /v1/receipts` with the same fields. A company reports a transaction once. A second report answers `report_duplicate`.

## From report to receipt

| State | Meaning |
|---|---|
| `pending` | Not on our side of the chain yet. The indexer reads Base every minute and waits for 12 confirmations |
| `confirmed` | Matched with the transfer, the receipt is written |
| `mismatch` | The reported amount differs from the transfer. The receipt shows the amount on chain |
| `not_found` | Two days passed and the chain never showed the transfer |

## The seller on a receipt

We look up the payTo address in [the register](https://402lounge.com/docs/register.md):

- `verified`: the wallet proved it belongs to the listing (level 1). The receipt names the seller.
- `listed`: a listing names the wallet, but the wallet has not proved it (level 0).
- `unverified`: no listing claims the wallet. The receipt has no seller name and no input VAT.

## The EUR value

Each receipt carries the ECB reference rate of the payment day, or of the business day before when the ECB publishes none, and the EUR amount at that rate. It is always marked `provisional` until your tax adviser confirms the method. Until the rate is out, the receipt says `no rate yet` and gets it later by itself.

## Read the receipts

- `receipts.list {month: "2026-10"}`: one month, newest first, with totals per seller and per agent and the reports still waiting. `mine`, `agent_id`, `wallet` and `status` narrow it, `limit` (up to 200) and `before` page through it. Months start at midnight Europe/Berlin, the same months as the vouchers.
- `receipts.get {id}`: one receipt by id or transaction hash.
- Over REST: `GET /v1/receipts?month=2026-10` and `GET /v1/receipts/{id}`.

## One receipt

An example with made-up data. Amounts in USDC have six places, in EUR two.

```
{
  "schema": "402lounge-receipt/0.1",
  "id": 92097,
  "network": "base",
  "tx_hash": "0xbcbca5c39efb57034965b0e84225f6264840c0c940f58e0980844a2bc888da4c",
  "block_time": "2026-10-31T01:41:09.444Z",
  "payer": "0xc2a9e61f4d07b83e5a2c19d6f0e7b4a38d5c9e12",
  "operator": { "agent_id": "example-agent-research", "name": "Research" },
  "pay_to": "0x6e2d4a9b17c3f08e5d21a7c46b9f3e0d82a5c71b",
  "amount": {
    "usdc": "0.150000",
    "eur": "0.14",
    "fx": {
      "rate": "1.0930",
      "day": "2026-10-30",
      "source": "ecb",
      "note": "previous business day",
      "provisional": true
    }
  },
  "seller": {
    "status": "verified",
    "level": 1,
    "listing": {
      "slug": "northpine",
      "name": "Northpine Data",
      "maker": "Northpine Data Inc."
    },
    "legal_entity": null
  },
  "item": {
    "resource_url": "https://api.northpine.example/metrics/v2/projects",
    "description": "Projects",
    "source": "catalog"
  },
  "provenance": { "money": "chain", "item": "catalog", "report_id": null },
  "links": {
    "tx": "https://basescan.org/tx/0xbcbca5c39efb57034965b0e84225f6264840c0c940f58e0980844a2bc888da4c",
    "register": "https://api.402lounge.com/v1/register/0x6e2d4a9b17c3f08e5d21a7c46b9f3e0d82a5c71b"
  }
}
```

`provenance` says where each part comes from: the money always from the chain, the item from the seller's catalogue, the agent's report or nowhere.