Receipts

A receipt is proof that one execution settled. When a transfer, withdrawal, swap, limit order or deposit completes, the API writes it as its own leaf in the witnessed transparency log, with the action execute.receipt. Anyone who holds the receipt can check it against the log without an API key and without trusting the API operator. A receipt is made to be handed over, for example to a merchant who was paid. It names no agent, account or key, so the holder cannot link it to the payer or to other receipts.

At a glance

Which executions: transfer, withdraw, swap, limit_order and deposit, once they settle. Not shield, unshield, native NEAR, or EVM and Solana signing.
Read one: GET /v1/agents/{agent_id}/operations/{correlation_id}/receipt, or api.getReceipt(). List them: GET /v1/agents/{agent_id}/receipts, or api.listReceipts(). Both need your partner API key.
Label a payment: set reference on a transfer or withdrawal. The payee checks it. Set a private note on any execution for the account’s own record.
Verify: verifyReceipt(), or verifyPaymentReceipt() for a payment you expect. Both run against a trusted checkpoint and the log’s public tiles.

getReceipt, listReceipts, verifyReceipt, verifyPaymentReceipt and logTileReader are in SDK 0.9.0 and later.

Label a payment

Two optional fields on a request tie an execution to something you track.

Field	On	Seen by	Description
`reference`	`transfer`, `withdraw`	The payee, in the receipt	1 to 128 printable ASCII characters without spaces, such as an order id or `sha256:<hex>` of the payment terms. The API does not check that it is unique. It is never sent on chain.
`note`	`transfer`, `withdraw`, `swap`, `limit_order`, `deposit`	The account’s owner only	The agent’s own words for why it runs the execution: 1 to 500 characters on one line. It is never sent to the provider or on chain and never appears in a receipt.

Both are part of the request’s Idempotency-Key hash, so a retry must send the same values. A merchant issues a unique reference for each order, the payer sets it on the payment, and the merchant later checks that a receipt carries it. The receipt does not say who paid. The reference is what ties the payment to the order.

const paid = await assistant.transfer(agentId, {
  asset: "nep141:usdc.near",
  amount: "2500000",
  recipient: "shop.near",
  reference: "order-42", // shared with the payee through the receipt
  note: "Paying order 42, the pizza the owner asked for", // the account's own record only
});

Read a receipt

An execution has a receipt once its status reads SUCCESS. For a limit order, SUCCESS means the order was funded and placed, not filled.

// One execution
const item = await api.getReceipt(agentId, paid.correlation_id);

if (item.receipt === null) {
  // PENDING: no published checkpoint covers it yet. Read it again later.
  // UNLOGGED: recorded before the log started. It never gets a receipt.
} else {
  const json = JSON.stringify(item.receipt); // give this to the payee
}

// Every settled transfer, newest first. Omit `type` for every type.
let cursor: string | undefined;
do {
  const page = await api.listReceipts(agentId, { type: "transfer", limit: 50, cursor });
  for (const entry of page.data) console.log(entry.correlation_id, entry.status, entry.details);
  cursor = page.next_cursor ?? undefined;
} while (cursor);

curl "$NEAR_INTENTS_AGENT_API_URL/v1/agents/$AGENT_ID/operations/$CORRELATION_ID/receipt" \
  -H "X-API-Key: $NEAR_INTENTS_AGENT_API_KEY"

curl "$NEAR_INTENTS_AGENT_API_URL/v1/agents/$AGENT_ID/receipts?type=transfer&limit=50" \
  -H "X-API-Key: $NEAR_INTENTS_AGENT_API_KEY"

The list is newest first. type is one of transfer, withdraw, swap, limit_order or deposit, limit is 1 to 100 (default 25), and cursor takes the previous page’s next_cursor. With type, a page can hold fewer than limit items, or none, while next_cursor is set. Keep paging until it is null. Each item has:

Field	Description
`correlation_id`	The execution’s `op_…` id
`type`	`transfer`, `withdraw`, `swap`, `limit_order` or `deposit`. It decides the fields of `details`.
`status`	`PROVEN` once a published checkpoint covers the receipt, `PENDING` before that, `UNLOGGED` for an execution recorded before the log started
`details`	The account’s own view: the terms the receipt commits to, plus what only the account sees (see below)
`receipt`	The JSON to hand over: `{ version: 1, origin, leaf_index, opening, terms }`. `null` unless `status` is `PROVEN`.

details carries the terms below, and also settled_at, usd_value, note, grant_id and policy_epoch, and for a deposit deposit_address and deposit_tx_hash. None of those are in the receipt. usd_value is the API’s valuation of the requested amount when the execution was dispatched, from its cached price, in USD with six decimals, rounded up. It is not a quote or a settlement price, and it is absent when the API held no price. An execution that has not settled, failed, or is of another type answers 409 receipt_not_available. Both endpoints answer 501 transparency_log_disabled when the deployment runs without the log. The list leaves out executions without a receipt. Prove those with the operation proof.

What a receipt commits to

The receipt’s terms are canonical JSON: the type, the settlement identifiers the provider reported, and the fields of that type. The opening commits to the terms, the execution’s correlation_id (random per execution) and the time.

`type`	Fields
`transfer`	`asset`, `amount`, `recipient`, `confidential`, `reference?`
`withdraw`	as a transfer, plus `chain`, `memo?` and `amount_out?`
`swap`	`origin_asset`, `destination_asset`, `amount`, `min_amount_out?`, `confidential`, `amount_out?`
`limit_order`	`origin_asset`, `destination_asset`, `amount`, `side`, `price`, `quantity`, `deadline?`, `confidential`, `order_id`, `amount_out?`
`deposit`	`origin_asset`, `destination_asset?`, `amount?`, `confidential`, `deposited_amount?`, `amount_out?`

The settlement identifiers are intent_hash, transfer_intent_hash, tx_hash, destination_tx_hash, settlement_tx_hash and receipt_hash, whichever the provider reported for the route. A receipt always names at least one, or a limit order’s order_id. asset and origin_asset are the asset as requested. A NEAR withdrawal to chain near delivers native NEAR whatever was requested.

What it leaves out

A receipt deliberately omits the tenant, agent id, NEAR account, wallet id, key id, grant and policy epoch, the request hash, the provider’s request ids, fees, usd_value and the note. A deposit’s receipt also leaves out the deposit address and the transaction that paid it, because 1Click’s public status ties either one to the account it credits. A public settlement hash can still be looked up on chain, where the paying account is visible. A confidential route’s intent hash names no public transaction.

What it proves

A verified receipt proves that the API’s append-only log records the execution as settled, with these terms, at that time. It does not prove who paid, and the same receipt can be shown twice, so a payee should accept each correlationId once.

Withdrawal: amount is what the account was debited. The bridge or network fee comes out of it, so the recipient receives less, in the destination chain’s units. amount_out states what the provider reported delivering, when it reported it. To confirm an exact arrival, check amount_out or the destination chain.
Limit order: the order was funded and placed under order_id. It does not prove a fill. Read fills from the order, see Limit Orders.
Deposit: funds arrived and were credited to the account. It does not say who sent them.
Confidential transfer: it counts as settled when the provider reports success with an intent hash. Nothing checks it independently on chain.

Receipts live in the audit log, so they last as long as it keeps events: 90 days. An execution settled before receipts were introduced has none. Read the receipts you need to keep while they are available. A receipt you already hold keeps verifying.

Verify a receipt

The holder needs no API key. verifyReceipt takes a trusted checkpoint, which must come from the witness or from state the verifier kept itself, never from the receipt’s source, and a tile reader for the log’s public tiles. Pin the origin and witness key as on Transparency Proofs.

import {
  fetchWitnessCheckpoint,
  LogUnavailableError,
  logTileReader,
  NoteError,
  ProofError,
  ReceiptNotCoveredError,
  verifyPaymentReceipt,
} from "@near-intents-agent-api/sdk";

const ORIGIN = "api.agentsonintents.com/log";
const WITNESS_PUBLIC_KEY = "598165a18b588f504e159c0e2573d73983ae22bf15cf80d36902276d63a11101";

const trusted = await fetchWitnessCheckpoint("https://api.agentsonintents.com", ORIGIN, WITNESS_PUBLIC_KEY);
const readTile = logTileReader("https://log.agentsonintents.com/");

try {
  const payment = await verifyPaymentReceipt(receipt, {
    origin: ORIGIN,
    trusted,
    readTile,
    expect: { recipient: "shop.near", asset: "nep141:usdc.near", amount: "2500000", reference: "order-42" },
  });
  // Accept payment.correlationId once. The verifier keeps no record of what it accepted.
} catch (error) {
  if (error instanceof ReceiptNotCoveredError || error instanceof LogUnavailableError) {
    // Retry. The trusted head is older than the receipt (fetch a newer one), or the log did not
    // answer or did not serve a tile yet. Neither says anything about the receipt.
  } else if (error instanceof NoteError || error instanceof ProofError) {
    // Reject. The receipt does not prove this payment.
  } else throw error; // TypeError: `expect` is incomplete
}

Two functions, for two jobs:

verifyReceipt(receipt, { origin, trusted, readTile }) checks any receipt and returns its typed terms (terms.type picks the fields), correlationId, settledAt and leafIndex. It rebuilds Merkle inclusion from the log’s tiles against the trusted checkpoint. It accepts only a leaf with the fields of a receipt, so an execution’s own settled event is refused, and it requires terms that name a settlement.
verifyPaymentReceipt(receipt, { origin, trusted, readTile, expect }) runs those checks, then accepts only a transfer or withdrawal with exactly the expect you owe.

What `expect` must match

Field	Rule
`recipient`, `asset`, `amount`, `reference`	Required, non-empty strings, matched exactly. `asset` is compared as requested, so `near` and `nep141:wrap.near` differ. `amount` is in atomic units. A missing one throws `TypeError` before anything is read.
`confidential`	Omit it to accept a confidential payment only, the account’s default. A payment from the legacy public balance (a withdrawal sent with `confidential: false`) matches only `confidential: false`. A confidential payment completes on the provider’s word, with nothing to check on chain.
`chain`	Set it for a withdrawal. Without it only a transfer matches.
`memo`	A withdrawal’s memo, exactly as requested. Without it a withdrawal that has a memo never matches, and `""` matches only an explicit empty memo.

On success it returns the verified payment: correlationId, type, settledAt, the terms, chain, memo and amountOut when present, the settlement hashes and leafIndex.

Errors

Error	Meaning
`ReceiptNotCoveredError`	The trusted checkpoint does not cover the receipt’s leaf yet. Fetch a newer one and verify again.
`LogUnavailableError`	The log did not answer, or did not serve a tile that the trusted tree contains. Verify again later.
`NoteError`, `ProofError`	The receipt does not prove a settled execution, or not the payment you expect. Reject it.

To check many receipts, fetch the witness head once, build one tile reader, and verify each receipt against that head.

Agent API

Quickstart

Guides

Trust & Verification

API Reference

Label a payment

Read a receipt

What a receipt commits to

What it leaves out

What it proves

Verify a receipt

What `expect` must match

Errors

Next steps

Transparency Proofs

Executions

Label a payment

Read a receipt

What a receipt commits to

What it leaves out

What it proves

Verify a receipt

What expect must match

Errors

Next steps

Transparency Proofs

Executions

What `expect` must match