Settle an invoice with on-chain proof.

post

http://localhost:3001/v1/payment-requests/{paymentRequestId}/settle

The payee agent calls this after the payer's on-chain transfer
confirms. The backend verifies the supplied (txHash, payerAddress,
amountUsdcVerified) tuple against transactions before flipping
the invoice to settled and firing invoice.settled. Verification
failures fire invoice.settlement_failed.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Path Params

paymentRequestId

uuid

required

Internal UUID of the invoice (NOT the public hosted-URL token).

Body Params

The payer-side agent calls this endpoint
after broadcasting payment to claim settlement. The backend MUST
verify the tuple against transactions before marking the invoice
settled - server is the trust anchor, agent is untrusted input.

txHash

string

required

^0x[0-9a-fA-F]{64}$

Hash of the on-chain transfer that paid the invoice.

payerAddress

string

required

^0x[0-9a-fA-F]{40}$

Address that sent funds. Must match transactions.from_address.

amountUsdcVerified

string

required

^[0-9]+(?:\.[0-9]+)?$

USDC amount the payer claims they sent (human-readable, e.g.
"0.10"). Backend converts to wei and rejects on mismatch.

Headers

X-Network

string

enum

required

Selects the network slice the request targets. Workspace-scoped
responses are filtered to this network; chain-bound writes are
stamped with it. Required on every non-admin workspace-scoped
operation.

Allowed:

Responses

403

Agent mismatch (invoice belongs to a different agent), or the
caller's key is not agent-scoped.

409

Invoice is no longer in open state, OR on-chain verification
failed (tx not found / unconfirmed, recipient mismatch, amount
mismatch). The error code distinguishes the case:
payment_request.not_settleable,
invoice.settlement_unconfirmed,
invoice.settlement_recipient_mismatch,
invoice.settlement_amount_mismatch.

Language

Credentials

URL

Loading…

Response

Click Try It! to start a request and see the response here! Or choose an example:

application/json

200Invoice settled.

400Validation, malformed input, or missing/invalid X-Network.

401Missing or invalid bearer token / API key.

404Resource id resolved to no row, or row was scoped out by workspace.