> 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/sonic-swap-api.md). # SONIC Swap API Preview server-authoritative Swap API contracts for trusted tokens, immutable quotes, transaction intents, submission, effect verification, settlement and reconciliation. > **Status: Preview / In Progress** — These contracts describe the intended and partially implemented v1 boundary. They MUST NOT be interpreted as proof of mainnet readiness, verified liquidity or public production availability. Swap is Live only after the canonical **Swap Launch Readiness & Verification** suite reaches `MAINNET_READY` and the feature is explicitly enabled. **Base URL:** `/api/v1` SONIC Swap follows one canonical money path: ``` trusted token selection → signed session / auth context → route-access + entitlement checks → verified wallet → network + balance validation → atomic amount conversion → service-fee + slippage policy → provider route quote → price-impact validation → immutable SwapQuote → TransactionIntent → user review → wallet signature → submission → confirmation → effect verification → settlement → reconciliation → receipt ``` `quote → intent` is mandatory. ## Endpoint summary ```http GET /api/v1/swap/tokens GET /api/v1/swap/settings POST /api/v1/swap/quotes POST /api/v1/swap/intents POST /api/v1/swap/:intentId/submit GET /api/v1/swap/:intentId/status POST /api/v1/swap/:intentId/verify ``` Money-moving or duplicate-sensitive mutations require an operation-scoped `Idempotency-Key`. ## Common authority rules The API evaluates server-derived identity. Browser-provided role, tenant, entitlement or wallet-verification flags are not authoritative. Required boundaries remain separate: ``` authenticated ≠ authorized ≠ route allowed ≠ entitled ≠ wallet verified ≠ transaction authorized ≠ settled ``` A verified wallet proves address control. It does not authorize an arbitrary recipient, mint, amount or route. ## Trusted token identity `GET /api/v1/swap/tokens` returns the active trusted-token registry projection. Canonical identity is: ``` network + mint + token program + verified decimals + registry version ``` Symbol/name/logo/token-list data is display metadata only. ### Response characteristics * user/workspace-sensitive response; * `Cache-Control: private, no-store`; * unresolved/unverified production entries MUST NOT be exposed as executable trusted tokens; * unavailable registry state fails closed. ## `GET /api/v1/swap/settings` Returns effective Swap policy and circuit-breaker state, including: ``` status releaseState swapEnabled network serviceFeeBps feePolicyVersion feeRecipient slippage.defaultBps slippage.minBps slippage.maxBps priceImpact.warningBps priceImpact.hardRejectBps quoteTtlSeconds registryVersion provider states circuit breakers ``` Current economic policy defines the SONIC Swap service fee as: ``` 200 bps = 2% ``` A configured policy is not proof that execution is Live. ## `POST /api/v1/swap/quotes` Creates one immutable, expiring execution proposal. ### Authentication / authorization Requires: * valid signed session; * Swap route/resource access; * Swap entitlement where applicable; * `swap.execute`-equivalent permission; * selected wallet verified for the active principal. ### Request Representative shape: ```json { "inputMint": "", "outputMint": "", "amount": "1.25", "slippageBps": 50, "wallet": "" } ``` `amount` is a human-readable decimal string. The server converts it to atomic `bigint` using authoritative input-token decimals. ### Validation order ``` session/access/entitlement → verified wallet → active Swap policy → trusted input/output identities → network → slippage policy → human-to-atomic conversion → authoritative balance snapshot → SOL execution reserve → 200 bps service fee → executable input → provider route → price-impact policy → immutable quote hash ``` Unavailable balances remain `BALANCE_UNAVAILABLE`; they are never converted to zero. ### Quote contract An executable quote contains at least: ``` quoteId operationId provider network inputMint outputMint grossInputAtomic serviceFeeAtomic executableInputAtomic expectedOutputAtomic minimumOutputAtomic slippageBps priceImpactBps route feeBreakdown feePolicyVersion registryVersion expiresAt quoteHash ``` Material changes require a new quote. This includes token, amount, wallet, network, slippage, routing mode, fee policy or registry version. ### Idempotency The same logical quote creation retry MUST reuse the same `Idempotency-Key`. Retrying with a new key means a new logical request and MAY produce a new market quote. ## `POST /api/v1/swap/intents` Creates the durable authorization boundary from an accepted unexpired quote. ### Request ```json { "quoteId": "q_...", "wallet": "" } ``` ### Required checks * quote exists and is unexpired; * `quoteHash` validates; * quote session/user/tenant authority matches the active session; * wallet has not changed; * fee-policy version still matches; * trusted-registry version still matches; * verified fee recipient is configured. ### Intent contract The `TransactionIntent` binds: ``` operationId intentId quoteId session authority wallet network inputMint / outputMint grossInputAtomic serviceFeeAtomic executableInputAtomic expectedOutputAtomic minimumOutputAtomic slippageBps priceImpactBps feeRecipient feePolicyVersion registryVersion route quoteHash intentHash expiresAt ``` The provider-specific executable quote payload remains server-side. Where an enabled provider supports transaction construction, the intent response may include a prepared transaction for the reviewed intent. Provider payloads never become settlement authority. ## User review requirement Before wallet authorization, the application SHOULD display: ``` You Pay SONIC Service Fee Executable Swap Input Expected Output Minimum Received Slippage Price Impact Route Venue / Routing Fees Estimated Solana Network Fee Estimated Priority Fee Connected Wallet Network Quote Expiry ``` ## `POST /api/v1/swap/:intentId/submit` Submits the exact signed transaction corresponding to the reviewed intent. ### Request Representative shape: ```json { "signature": "", "signedTransactionBase64": "" } ``` ### Rules * wallet/session authority is rechecked; * intent integrity and expiry are rechecked; * an intent already bound to a different signature becomes `REQUIRES_REVIEW`; * RPC submission response is not settlement; * uncertain RPC submission MUST be inspected before retry; * the server MUST NOT blindly submit a second value-moving transaction after ambiguous submission. An uncertain submission uses `SUBMISSION_UNCERTAIN` and a recoverable server-owned state rather than false failure or false success. ## `GET /api/v1/swap/:intentId/status` Returns durable server-owned operation state for the authenticated owner/workspace. Canonical states: ``` CREATED → VALIDATED → QUOTED → INTENT_CREATED → AWAITING_SIGNATURE → SIGNED → SUBMITTED → CONFIRMING → CONFIRMED → VERIFYING → VERIFIED → SETTLING → SETTLED → RECONCILING → RECONCILED ``` Exceptional states: ``` EXPIRED REJECTED CANCELLED INVALID FAILED REQUIRES_REVIEW ``` Browser refresh, wallet disconnect, navigation or session loss after submission does not erase durable operation state. ## `POST /api/v1/swap/:intentId/verify` Runs the trusted server-side verification/settlement/reconciliation boundary. Browser-supplied economic effects MUST NOT be accepted as authoritative verification data. The configured chain verifier observes the submitted transaction and normalizes at minimum: ``` network signature transaction success signer input mint output mint actual executable input actual SONIC service fee fee recipient actual output invoked programs observation time ``` ### Effect verification Before settlement, verify: * expected network; * expected signer; * transaction success; * trusted input/output mints; * expected executable input amount; * expected service fee; * verified fee recipient; * allowed programs; * minimum output; * transaction uniqueness; * intent compatibility. Canonical rule: ``` confirmation → effect verification → settlement ``` Never: ``` signature exists → settlement provider says success → settlement ``` ### Settlement invariant ``` one logical operation → at most one authoritative settlement ``` Repeated verify calls, callbacks, workers, retries or page refreshes MUST converge on the same settlement. ### Reconciliation After settlement: ``` SETTLED → RECONCILING → RECONCILED ``` Compare the quote, intent, settlement, Solana transaction, actual token movement and actual fee movement. Outcomes: ``` MATCH DRIFT_DETECTED REQUIRES_REVIEW FAILED ``` Unexplained mismatches MUST NOT be silently corrected. ## Normalized errors ``` UNAUTHENTICATED SESSION_EXPIRED ACCESS_DENIED ENTITLEMENT_REQUIRED WALLET_REQUIRED WALLET_MISMATCH NETWORK_MISMATCH TOKEN_NOT_TRUSTED BALANCE_UNAVAILABLE INSUFFICIENT_BALANCE INSUFFICIENT_SOL_RESERVE INVALID_AMOUNT QUOTE_UNAVAILABLE QUOTE_EXPIRED QUOTE_MISMATCH SLIPPAGE_OUT_OF_POLICY PRICE_IMPACT_EXCEEDED ROUTE_UNAVAILABLE SIMULATION_FAILED SIGNATURE_REJECTED SUBMISSION_UNCERTAIN TRANSACTION_FAILED VERIFICATION_FAILED SETTLEMENT_FAILED RECONCILIATION_DRIFT PROVIDER_UNAVAILABLE REQUIRES_REVIEW SWAP_PAUSED SWAP_NOT_CONFIGURED PERSISTENCE_NOT_CONFIGURED ``` Clients branch on `error.code`, not provider payloads or message parsing. ## Provider semantics Jupiter is an aggregated routing provider. Raydium, Meteora and Orca are direct venue integrations only when verified and enabled. Provider capability never owns SONIC financial truth: ``` provider response ≠ settlement authority ``` RPC disagreement or critical verification instability SHOULD pause sensitive writes. ## Observability A Swap SHOULD be traceable across: ``` operationId quoteId intentId transactionSignature settlementId reconciliationId ``` Money-path logs MUST NOT include private keys, seed phrases, wallet secrets, treasury secrets, provider secrets or unnecessary session credentials. ## Testing ownership This API page does not maintain its own acceptance-test matrix. Production verification is owned by **Swap Launch Readiness & Verification** in the Swap architecture documentation. ## Production activation rule ``` trusted configuration + verified token identity + validated wallet/session + sufficient balances + atomic accounting + transparent fees + valid slippage + acceptable price impact + verified route + immutable quote + TransactionIntent + explicit wallet authorization + confirmed Solana transaction + verified economic effects + single authoritative settlement + successful reconciliation = production-valid swap ``` --- # 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/sonic-swap-api.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.