> For the complete documentation index, see [llms.txt](https://sonic-ai-works.gitbook.io/sonic-networks-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://sonic-ai-works.gitbook.io/sonic-networks-docs/documentation/developers/finance-and-protocols/web3-payment-adapters.md).

# Web3 Payment Adapters

Fully wired wallet, Solana Pay, CCTP, x402 and ZK adapters with explicit intent, verification, settlement and reconciliation boundaries.

Wallet ownership, transaction authorization, provider execution and business settlement are separate trust boundaries.

```
Product action
→ server validation
→ EconomicOperation
→ immutable quote/policy snapshot
→ TransactionIntent / PaymentIntent
→ wallet or protocol authorization
→ submit
→ confirm
→ verify actual effect
→ settle
→ reconcile
```

## Shared adapter contract

Protocol adapters translate provider-specific requests and responses. They do not own SONIC pricing, fees, entitlements, credit balances, treasury accounting or final settlement rules.

Every adapter documents:

* capability and network support;
* trust level;
* expected inputs/outputs;
* retry policy;
* idempotency requirements;
* failure states;
* feature flag;
* provider health behavior;
* reconciliation requirements.

## Solana Pay + QR

Solana Pay URLs and QR codes are derived only from an existing authenticated `PaymentIntent` or `TransactionIntent` containing the server-authoritative recipient, mint, atomic amount, decimals, expiry and unique reference.

```
Quote
→ PaymentIntent
→ Solana Pay URL / QR
→ Wallet
→ Signature
→ Solana confirmation
→ Verify recipient + mint + amount + reference
→ Idempotent settlement
```

**QR is transport, not settlement truth.** A displayed signature is also insufficient until the intended on-chain effect is verified.

## CCTP

CCTP is an optional native-USDC interoperability rail. The transfer operation persists source submission, source burn confirmation, attestation state, destination mint submission, destination confirmation, verification, settlement and reconciliation.

```
CREATED
→ SOURCE_READY
→ BURN_SUBMITTED
→ BURN_CONFIRMED
→ ATTESTATION_PENDING
→ ATTESTED
→ DESTINATION_MINT_SUBMITTED
→ DESTINATION_MINT_CONFIRMED
→ VERIFIED
→ SETTLED
→ RECONCILED
```

A confirmed source burn is **not** destination settlement. If the source completes and destination processing is delayed, the operation remains recoverable and is resumed by verification/reconciliation workers.

Cross-chain checkout keeps `checkoutId`, `paymentIntentId`, `crossChainOperationId` and `settlementId` separate. CCTP is transport; the checkout service still decides when the order is paid.

## x402

x402 is used only for machine-payable resources explicitly published by the SONIC API.

```
HTTP request
→ resource policy
→ immutable resource-price version
→ 402 payment requirement
→ payment verification
→ PaymentReceipt
→ Entitlement
→ resource execution
```

Supported entitlement styles may include `PAY_PER_REQUEST`, `SESSION_ENTITLEMENT` and `USAGE_BUNDLE`.

The x402 layer requires replay protection, request/resource binding, expiry, idempotent fulfillment, usage counters and rate limits. x402 access remains separate from normal SaaS subscriptions and AI Credit balances unless the purchased product explicitly grants credits.

## ZK proofs

ZK support is a pluggable proof-verification layer for defined product requirements such as eligibility, selective disclosure, reward qualification or future privacy-preserving governance.

```
Proof Scheme
→ Verifier
→ Versioned Verification Policy
→ Business Entitlement
→ Economic Operation if value must move
```

A valid proof may establish `eligible = true`; it does not establish payment, wallet authorization, claim settlement or reward distribution.

Proof records store verifier/policy version, public-input hash, verification time and expiry where applicable. Private witness material is not persisted merely for convenience.

## Retry policy

Safe retries: reads, quote lookup, transaction lookup, payment verification and reconciliation.

Potentially dangerous retries: transaction submission, destination mint submission, treasury transfers, burns, vesting creation and liquidity deployment. An uncertain write is inspected before any resubmission.

## No fabricated balances

Missing/unavailable provider data is `null`/unavailable. A displayed zero is valid only when the configured authoritative provider returned zero.

## Commercial corrections

Automatic commercial refunds are disabled. Exceptional corrections require explicit authorized reversal/ledger workflows. AI generation failures release pending credit reservations rather than creating a false settled charge.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://sonic-ai-works.gitbook.io/sonic-networks-docs/documentation/developers/finance-and-protocols/web3-payment-adapters.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.