> 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/api-reference/wallet-transaction-intents-and-solana-pay.md). # Wallet, transaction intents & Solana Pay Preview verified-wallet, transaction-intent, signature, Solana Pay, chain-effect verification, settlement and reconciliation contracts. **Status:** `Preview` This page documents intended server-authoritative wallet and transaction contracts. Route existence or a working wallet adapter does not by itself make the financial flow `Live` or `Verified`. ## Authority boundary ``` signed session → server authorization → verified wallet where required → quote / policy validation → TransactionIntent → explicit wallet signature → submission → chain confirmation → effect verification → settlement → reconciliation ``` The states are deliberately separate. ``` wallet connected ≠ authenticated wallet verified ≠ authorized for every operation signature ≠ settlement chain confirmation ≠ verified business effect ``` ## Identity challenge ```http POST /api/v1/wallet/challenge POST /api/v1/wallet/verify ``` `POST /wallet/challenge` accepts a validated Solana public key and creates a short-lived, purpose-bound challenge for the authenticated account. `POST /wallet/verify` accepts the challenge identity and exact signature. Successful verification creates a server-owned wallet-link record for the authenticated user/tenant. Wallet verification proves control of one public address. It does not create the signed application session, assign a role, grant a SaaS entitlement or authorize arbitrary transfers. ## Transaction intent ```http POST /api/v1/transactions/intent GET /api/v1/transactions/:id ``` `POST /transactions/intent` requires a stable operation-scoped `Idempotency-Key` for duplicate-sensitive flows. The server freezes the concrete operation before wallet authorization, including the applicable fields for the domain: ``` actor/account network / cluster payer recipient / program asset / mint amountAtomic explicit decimals fees quote/policy/version business reference purpose / transaction kind expiry ``` The client cannot authorize a different recipient, amount, mint or purpose simply by signing a different payload. ## Submission ```http POST /api/v1/transactions/:id/submit ``` Submission records the signature against the existing intent and advances the authorization/network state to submitted. It does **not** mark the business operation settled. A submitted signature may still fail, expire, land on the wrong cluster, produce the wrong economic effect or require stronger confirmation. ## Chain status and reconciliation ```http POST /api/v1/transactions/:id/chain-status ``` Protected chain reconciliation advances monotonic network state through processed, confirmed, finalized or failed where appropriate. Before settlement, SONIC verifies expected effects such as: ``` cluster transaction success payer / signer where relevant recipient mint / asset atomic amount reference / memo / business binding where required non-duplication ``` Each business operation defines its settlement threshold. A normal user operation may settle at confirmed where policy permits; elevated treasury/reward flows may require finalized. ## Solana Pay requests ```http POST /api/v1/solana-pay/requests GET /api/v1/solana-pay/requests/:intentId ``` `POST /solana-pay/requests` accepts an existing server-authoritative `transactionIntentId`. SONIC derives the Solana Pay URI from that intent instead of trusting caller-supplied recipient/amount fields. A response may include the URI, QR representation, deterministic reference, atomic/display amount, recipient, mint, expiry and verification requirements. The QR is payment-request transport, not settlement proof. Goods, licenses, rewards or other irreversible business state remain blocked until the resulting chain transaction passes required effect verification and reconciliation. ## Protocol capability registry ```http GET /api/v1/integrations/solana ``` The integration registry returns safe capability/deployment status for configured Solana features such as Solana Pay, CCTP, x402 and ZK/confidential-balance integrations where supported. Product feature flags, provider configuration and protocol deployment state remain independent. ``` configured adapter ≠ verified deployment ≠ live product capability ``` ## Idempotency The same logical financial operation must not create multiple intents, submissions or settlements because a client retries after a timeout. If an idempotency key is reused with materially different economic input, the server rejects the conflict. ## Security invariant ``` verified session authority + verified wallet where required + immutable TransactionIntent + explicit signer approval + verified network effect + single settlement + reconciliation = valid wallet-backed SONIC operation ``` --- # 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/api-reference/wallet-transaction-intents-and-solana-pay.md?ask=&goal= ``` `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.