Skip to content

Crypto payments & custody

Crypto stays available when its independent readiness gates are healthy. New direct deposits and x402 can be stopped separately without disabling receipt reconciliation, customer billing reads, or sweep reconciliation.

Run the structured report before enabling or restoring either path:

Terminal window
frameworks crypto readiness --output json

After deploying Gateway/Commodore changes, also verify that public wallet onboarding is not behind an authentication or payment wall:

Terminal window
frameworks crypto smoke --base-url https://bridge.frameworks.network --output json

The smoke command checks published wallet/x402 metadata and issues an expiring challenge for a fixed non-customer address. It does not sign or consume the challenge, create an account, use a customer wallet, or move funds.

Production eligibility requires the HD watch-only xpub, configured finalized heads and healthy scanner cursors, the embedded x402 v2 exact facilitator, complete supplier identity/registration/country configuration, effective VAT rates, non-zero treasury addresses, and dedicated gas-only relayers. The live report also proves the x402 and sweep-relayer accounts can fund at least one transaction at the current bounded fee ceiling.

An absent gate keeps the affected method hidden/fail-closed. It is not a warning that operators may ignore.

  • CRYPTO_DEPOSITS_ENABLED=false stops new direct-deposit addresses.
  • X402_PAYMENTS_ENABLED=false stops new x402 quotes and settlement.

Keep the scanner and reconcilers running. A provider/RPC timeout is an unknown outcome, never proof that settlement failed; retries use the persisted quote, authorization nonce, provider transaction, and mutation-result records.

purser.crypto_accounting_anomalies holds conditions that cannot be repaired safely from RPC state alone, including a consumed USDC authorization without a recoverable transaction hash and a late settlement with no matching ledger reversal. Readiness reports the unresolved count. Never “resolve” an item by editing a balance or settlement row; use an audited compensating operation backed by canonical evidence.

Credits are issued only after consensus-labelled finality and a canonical block hash check. Allocated deposits continue to be rechecked. A later canonical mismatch reverses prepaid credit, reopens/claws back invoice allocation, creates a linked credit note where a customer document exists, and lets ordinary prepaid admission block on the resulting balance. There is no paid-request bypass.

Authenticated document downloads are available through /v1/billing/documents. Purser tenant-scopes every invoice, simplified invoice, confirmed-payment receipt, and credit note, renders only persisted evidence, and returns an integrity hash. Database deletion guards retain these source records for at least ten years. Confirmed top-up is the VAT tax point; each document records the effective rate source and customer location. New instructions retain an immutable exclusive-crypto-advance-v3 assessment with the supplier/customer identity, accepted treatment, location evidence, and the VIES proof actually used. Gross payment and net service credit are distinct; a EUR 100 net advance with 21% VAT collects EUR 121. Effective rates are retained at the tax point. Changing a billing profile, supplier configuration or VIES availability cannot erase an already-received payment’s document.

New instructions require a billing country and a personal/business classification (a submitted VAT claim also identifies a business claim). Personal profiles need no company name or VAT number. Business profiles and payments over EUR 100 require a full invoice identity. Older quotes settle under their versioned legacy rules; non-EU legacy treatment is explicitly marked for review, not reused to authorize new quotes.

Late receipts retain their accepted payment and tax evidence; missing or unusable proof is retained for review rather than silently changing the claim. Expired or revoked evidence is marked CRYPTO_TAX_REVIEW_REQUIRED in the financial audit. The original quote assessment and confirmation evidence remain available for correction review.

The Dutch supplier service policy charges Dutch VAT to Dutch customers and EU consumers. EU business reverse charge requires validated VAT evidence. Non-EU services state that Dutch VAT is outside scope. National numbers and Greek GR/EL prefixes are normalized before validation. Invalid claims or unavailable verification are returned before a new purchase is accepted. The recurring collection fallback and operator review workflow are described in Billing financial evidence. These checks supplement the global crypto readiness report.

Purser is watch-only. Automatic hot-wallet sweeping is deliberately out of scope. Operators use:

Terminal window
frameworks crypto sweep plan --network base --out manifest.json --persist
frameworks crypto sweep sign --manifest manifest.json --out signed.json \
--treasury-allowlist treasuries.json --secret-fd 3 \
--max-fee-gwei 5 --max-priority-fee-gwei 2
frameworks crypto sweep broadcast --bundle signed.json --execute --ack <checksum>
frameworks crypto sweep reconcile --batch-id <batch-id>
frameworks crypto sweep release --batch-id <batch-id> --reason "expired ceremony"

Signing is performed offline with an xprv supplied through a file descriptor and independent operator-selected fee ceilings. Broadcast rechecks chain, token, treasury, balance, nonce/authorization state, and fee bounds. Repeating broadcast replays the persisted transaction intent; it does not allocate another relayer nonce.

Release is dry-run by default. Execute only with --execute --ack <manifest-checksum> from the dry-run output. Canonically safe claims become replannable; unresolved signed/broadcast claims are quarantined, never blindly released.

To rotate the generated-address key, create a new account-external xpub offline, then run:

Terminal window
frameworks crypto wallet rotate --xpub-file new-deposit.xpub --network mainnet

Only future addresses use the new key. Historical addresses retain their original xpub and are planned in separate signing-key batches. Keep every retired xprv offline until no remaining sweep manifest uses it.

For the two-person evidence checklist, failure recovery, and incident-specific procedures, use the repository runbooks docs/operations/sweep-ceremony.md and docs/operations/crypto-incidents.md shipped with the same release.