> 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/full-stack-finance-and-protocol-wiring.md).

# Full-stack finance & protocol wiring

End-to-end implementation map from product surfaces through finance services, Solana/provider adapters, settlement, reconciliation and operational controls.

This page defines what **fully wired** means across SONIC AI Works.

## Capability map

| Capability           | Product surface     | Core service                           | Provider/protocol                  | Final authority                               |
| -------------------- | ------------------- | -------------------------------------- | ---------------------------------- | --------------------------------------------- |
| Swap                 | `/swap`             | Swap Service + Market Router + Finance | Jupiter / Raydium / Meteora / Orca | verified Solana transaction + swap settlement |
| Checkout             | `/checkout`         | Checkout + Finance                     | Solana Pay / wallet                | settlement record + verified payment          |
| AI Credit purchase   | Checkout / Studio   | Checkout + Credits Ledger              | SOL / SONIC / USDC rails           | Credits ledger after settlement               |
| Marketplace purchase | Marketplace         | Marketplace + Commerce                 | configured payment rail            | order settlement + entitlement ledger         |
| Cross-chain USDC     | Checkout / App      | CCTP service + Finance                 | Circle CCTP                        | destination USDC verification                 |
| Agent payment        | API                 | x402 service + Finance                 | x402-compatible rail               | PaymentReceipt + entitlement                  |
| ZK eligibility       | Claims / Governance | Proof service                          | versioned verifier                 | verification policy decision                  |
| Vesting              | `/app/vesting`      | Vesting service                        | Streamflow                         | verified schedule + allocation reconciliation |
| Rewards              | `/app/rewards`      | Reward service                         | Solana where claimed               | Reward ledger + verified claim                |
| Treasury             | Admin               | Treasury + Finance                     | Solana                             | verified transfer + treasury journal          |

## Swap wiring

`/swap` is wired through `/api/v1/swap/*` to `SwapService`, `MarketRouter`, `finance-core`, `solana-core` and provider adapters. Jupiter integration remains behind `/packages/providers/jupiter`; `@jup-ag/api` is never called directly from product components.

Swap quotes persist trusted mint identities, authoritative token decimals, atomic amounts, user-selected `slippageBps`, minimum output, route, quote expiry, provider fees and the versioned SONIC service fee. The current SONIC swap-service policy is **200 bps (2%)**, disclosed independently from Solana network fees and venue/routing fees.

Swap execution requires an active authenticated session, connected verified wallet, non-zero and sufficient spendable balance, server-approved trusted tokens, an unexpired quote, persisted TransactionIntent, explicit wallet signature, independent confirmation/effect verification, idempotent settlement and reconciliation.

A missing balance is `unavailable`, not `0`. SOL swaps reserve enough SOL for expected network/account costs. Wallet connection proves session availability only; it does not authorize the transaction.

## Shared packages

```
/packages
  /finance-core
    operations
    quotes
    intents
    fees
    settlement
    idempotency
    reconciliation
    risk

  /solana-core
    rpc
    addresses
    amounts
    simulation
    signatures
    confirmation
    explorer

  /market-router
  /market-data
  /payments
  /checkout
  /credits-ledger
  /rewards
  /vesting
  /treasury
  /token-registry
  /reconciliation

  /providers
    /helius
    /jupiter
    /raydium
    /meteora
    /orca
    /streamflow
    /birdeye
    /solscan
    /solana-pay

  /protocols
    /cctp
    /x402
    /zk
```

Provider packages translate capabilities only. They do not own product economics.

## Canonical API surface

```
/api/v1/token
/api/v1/token/supply
/api/v1/token/markets
/api/v1/token/vesting

/api/v1/market/price
/api/v1/market/history

/api/v1/swap/tokens
/api/v1/swap/settings
/api/v1/swap/quotes
/api/v1/swap/intents
/api/v1/swap/:intentId/status
/api/v1/swap/:intentId/verify

/api/v1/checkout/quotes
/api/v1/checkout/intents
/api/v1/checkout/:id
/api/v1/checkout/:id/verify

/api/v1/payments/solana
/api/v1/payments/:id/verify

/api/v1/cctp/quotes
/api/v1/cctp/intents
/api/v1/cctp/:id

/api/v1/x402/discovery
/api/v1/x402/verify
/api/v1/x402/settle

/api/v1/proofs/verify

/api/v1/rewards
/api/v1/rewards/claims
/api/v1/vesting
/api/v1/webhooks/helius
```

All mutating financial APIs require authentication/authorization where applicable, validation, operation-scoped idempotency and explicit state-transition rules.

## Economic operation identifiers

```
operationId
├─ quoteId
├─ intentId
├─ paymentIntentId
├─ crossChainOperationId
├─ transactionSignature
├─ settlementId
└─ reconciliationId
```

## Settlement invariants

* one logical operation produces at most one authoritative settlement;
* no client-side success state can directly mutate a financial ledger;
* provider callbacks trigger verification rather than direct crediting;
* expired quotes cannot silently execute;
* wrong network, mint, recipient, amount or reference fails verification;
* swap service fees are versioned atomic calculations and stay distinct from provider/network fees;
* disconnected/session-mismatched wallets cannot create executable swap intents;
* zero/insufficient balances cannot proceed;
* cross-chain source completion is not destination settlement;
* proof verification grants only the explicitly configured entitlement;
* AI Credits are mutated only by the Credit ledger lifecycle;
* token allocation state must reconcile to the fixed token allocation model.

## Retry policy

**Safe:** reads, market-data fetches, quote creation, transaction lookup, verification and reconciliation.

**Inspect before retry:** transaction submission, CCTP destination mint, reward/vesting claims, treasury movements, burns and liquidity deployment.

## Provider degradation

| Dependency           | Degraded behavior                                                   |
| -------------------- | ------------------------------------------------------------------- |
| Birdeye              | charts and analytics become stale/unavailable                       |
| Helius webhook       | chain reconciliation continues                                      |
| Jupiter              | verified direct venue routes may remain                             |
| Raydium/Meteora/Orca | affected venue removed from routing                                 |
| Solscan              | explorer links unavailable only                                     |
| CCTP                 | cross-chain payments disabled; pending transfers remain recoverable |
| x402 facilitator     | affected machine-payment resources fail closed                      |
| ZK verifier          | proof-gated actions fail closed                                     |
| RPC disagreement     | sensitive writes pause until resolved                               |

## Admin surfaces

```
/admin/finance
/admin/settlement
/admin/reconciliation
/admin/treasury
/admin/liquidity
/admin/providers
/admin/contracts
/admin/token-supply
/admin/vesting
/admin/burns
/admin/cctp
/admin/x402
/admin/zk
```

Privileged flows distinguish `PREPARE → POLICY CHECK → APPROVE → SIGN → SUBMIT → VERIFY → RECONCILE`.

## Environment isolation

`LOCAL`, `DEVNET`, `STAGING` and `MAINNET` use separate deployment registries, mints, treasury accounts, pools, provider credentials, webhooks, Streamflow schedules, CCTP configuration, x402 configuration and ZK policies. Mainnet code must reject devnet identifiers.

## Definition of done

A capability is fully wired when its UI/API, authorization, persistent state, business policy, provider adapter, transaction/proof lifecycle, verification, settlement, reconciliation, observability, feature flag, runbook and acceptance tests all refer to the same versioned specification.


---

# 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/full-stack-finance-and-protocol-wiring.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.