Stablecoin Settlement Audit

Paying carriers in USDC settles in seconds; finding out a month later that an invoice was paid twice, short by a fee, or to a lookalike address does not. This skill reconciles invoices against the transfers that actually landed on chain, with the same discipline as the other logistics skills: exact arithmetic, stated rules, one shipper at a time, and no guessing.

The matching rules do not depend on the network. Reading payments directly from a chain (--rpc) currently supports USDC on Solana; for any other network, export the transfers to a file.

Principles

1. Read-only, always. Never ask for, accept, or handle a private key, seed phrase or wallet export. The audit needs public addresses and public transactions, nothing else. If the user offers a key, tell them to keep it and not to paste it anywhere.
2. Exact money. Amounts are integers in the token's smallest unit (USDC: 6 decimals). Never round; an amount with too many decimals is an error to report, not to fix.
3. A payment to the wrong address is not a payment. A transfer that cites an invoice but went to an address other than the invoice's payee is reported first, as wrong_payee — the signature of address substitution — and the invoice stays unpaid.
4. Reference before amount. A memo naming the invoice is strong evidence; a matching amount alone is weak and is listed as matched_by_amount for a person to confirm. Two candidates means no match, never a guess.
5. One shipper at a time. Invoices spanning shippers are refused unless --owner or --all-owners is given. A client-facing report never lists transfers it cannot tie to that shipper's invoices; --all-owners output is marked not for client distribution.
6. Incomplete data is said out loud. If any transaction could not be read from the chain, the result carries incomplete: an invoice shown as unpaid may have been paid in it.

Workflow — order matters

1. Get invoices: invoice_id, payee_wallet, amount (USD), and ideally due_date, carrier, owner_id.
2. Get payments, either an export (signature, to_owner, amount or amount_raw, memo, mint, block_time) or read them read-only: python scripts/settlement_audit.py --invoices invoices.csv --rpc <https URL> --owner <shipper> Without --rpc, pass --transfers transfers.csv.
3. Report in this order: payments to the wrong address; duplicates and overpayments; shortfalls and overdue invoices; then amount-only matches to confirm. Quote the summary totals and the assumptions block.
4. If incomplete is present, lead with it and do not call any invoice unpaid without that caveat.

Bundled resources

• scripts/settlement_audit.py — the reconciliation. Standard library only (uses certifi for TLS certificates if installed). --demo checks hand-computed values: a 300 shortfall, a 640.50 duplicate, 750 unpaid and overdue, 300 paid to the wrong address.
• references/rules.md — read when the user asks why a payment was or was not matched, or wants different rules.
• agents/openai.yaml — the human-facing entry point.