---
title: "Report an outcome for an operation."
method: POST
path: "/v1/receipts"
tags: ["Receipts"]
---

# Report an outcome for an operation.

`POST /v1/receipts`

## Request

- Base URL: `https://api.fidren.net`
- URL: `https://api.fidren.net/v1/receipts`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

Appends one link to the operation's hash chain. The server computes `prev_hash` and `hash`; a caller cannot choose them. Lifecycle transitions are enforced, so an operation cannot be reported delivered without having been accepted.

## Request body

- ReceiptRequest
  - `operation_id` string, required
  - `address` string, required: The reporting address — this side's own address. A signature, if given, must be produced by it.
  - `chain` 'base' | 'polygon', required
  - `side` 'PAYER' | 'PAYEE', required: Which end of the operation is reporting. Each side keeps its own hash chain, and the two accounts are compared rather than merged.
  - `counterparty_address` string, nullable: The other end, as this reporter names it.
  - `status` 'REQUESTED' | 'ACCEPTED' | 'DELIVERED' | 'CONCLUDED' | 'FAILED' | 'DISPUTED' | 'REFUNDED', required
  - `signature` string: Optional 65-byte `personal_sign` signature over the statement returned by POST /v1/receipts/signing-message. Stored only if it verifies against `address`; an unverifiable one is reported back and the receipt is recorded without it.
  - `amount_cents` integer, nullable
  - `currency` string
  - `tx_hash` string, nullable
  - `occurred_at` string, date-time, required

## Response `201`

The stored receipt.

- Receipt
  - `id` integer, required
  - `operation_id` string, required
  - `address` string, required
  - `chain` string, required
  - `side` 'PAYER' | 'PAYEE', required
  - `counterparty_address` string, nullable, required
  - `status` 'REQUESTED' | 'ACCEPTED' | 'DELIVERED' | 'CONCLUDED' | 'FAILED' | 'DISPUTED' | 'REFUNDED', required
  - `amount_cents` integer, nullable, required
  - `currency` string, nullable, required
  - `tx_hash` string, nullable, required
  - `occurred_at` string, date-time, required
  - `prev_hash` string, nullable, required
  - `hash` string, required
  - `signature` string, nullable, required: The reporter's signature over this receipt, or null. Non-null means it was checked and matched: anyone holding this row can recompute the hash, rebuild the statement and recover the signer without trusting Fidren or the key that submitted it.
  - `signed` boolean, required: Whether authorship rests on a signature from the address rather than on the API key that submitted the report.
  - `corroboration` object: The operation's corroboration verdict as it stands after this receipt was written — the same verdict `GET /v1/operations/{operation_id}/receipts` reports. Present on every `POST /v1/receipts` response; absent from the receipts listed inside a `ReceiptChain`, which carries the verdict once at its top level. `CONTRADICTED` is adverse evidence, not an error to reconcile.
    - `state` 'SINGLE_SIDED' | 'CORROBORATED' | 'CONTRADICTED', required
    - `disagreements` string[], required
    - `both_signed` boolean, required
  - `signature_error` string: Why the supplied `signature` was not accepted. Present on a `POST /v1/receipts` response only when a signature was sent and did not match `address` when checked; absent when none was sent or it matched. The receipt is still recorded — with `signature: null` and `signed: false`, attributed to the API key rather than to the address. Prose; do not parse it.

## Other responses

- `400`: The request was rejected by validation.
- `401`: No usable access path. Either a key was presented and is not valid, or no key was presented, the free allowance is spent, and x402 charging is off. A presented key never falls back to the free tier or to being charged.
- `403`: The API key is valid, but its organization is not currently permitted to make this request. Do not rotate the key: it is not the problem.
- `409`: The receipt chain moved during the write; re-read and retry.
- `429`: Rate limit exceeded. Retry after the number of seconds in `Retry-After`.
- `503`: A required dependency is unavailable. Safe to retry.

---

[API](https://skmtc.dev/fidren/apis/fidren-decision-api.md) · [All operations](https://skmtc.dev/fidren/apis/fidren-decision-api/llms.txt) · [OpenAPI document](https://skmtc.dev/fidren/apis/fidren-decision-api/revisions/d4b4dafcb345?raw)