> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sodax.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> SODAX is mainnet-only (no testnet chains or RPC endpoints exist) with a hub-and-spoke architecture; Sonic is the hub. SODAX is non-custodial protocol/software: it routes and settles; independent solvers on the marketplace fill — never say 'our solver', 'the SODAX solver', that SODAX trades, takes custody, or fills orders. For frontend/React integrations, prefer @sodax/dapp-kit hooks over calling @sodax/sdk directly. SDK operations — the methods that build, submit or await a transaction, and the API/quote calls — return Result<T, E> ({ ok: true, value } or { ok: false, error }): check result.ok, never wrap them in try/catch or branch on error.message; discriminate on the narrow error.code union instead. Synchronous config getters (getPartnerFee, getSupportedSwapTokens, getVault, ...) return their value directly, not a Result.

# FAQ

#### 1. Which chains does SODAX support?

SODAX runs on a hub-and-spoke network of **mainnet** chains. Sonic is the hub; spokes span EVM chains (Arbitrum, Avalanche, Base, BNB Chain, Ethereum, Hedera, Hyper, Kaia, LightLink, Optimism, Polygon, Redbelly, Robinhood Chain) and non-EVM chains (Bitcoin, ICON, Injective, Near, Solana, Stacks, Stellar, SUI) — both lists read live from the backend config API. Reference any chain via `ChainKeys.*`, which — together with the backend config — is the source of truth. The legacy `*_CHAIN_ID` constants were **removed in v2**; see [Chain ID migration](https://github.com/gosodax/sodax-sdks/blob/main/packages/sdk/CHAIN_ID_MIGRATION.md) for the mapping.

Full list with relay IDs: [Relayer API endpoints](https://docs.sodax.com/developers/deployments/relayer-api-endpoints.md).

#### 2. Is SODAX available on a testnet?

No — SODAX is **mainnet-only**. Every chain in the canonical `@sodax/types` config is a `*_MAINNET` entry; there are no testnet chain configs, RPC endpoints, or a network toggle, because SODAX's cross-chain intents settle against real deployed contracts and live solver liquidity that only exist on mainnet. To build and test, use small amounts on mainnet and drive flows with the private-key wallet providers (see `apps/node`) rather than a testnet.

Full explanation and next steps: [Is SODAX on Testnet?](https://docs.sodax.com/developers/how-to/testnet.md).

#### 3. What is the difference between the hub and a spoke chain?

Sonic is the hub. All swap, lend, borrow, bridge and stake actions are coordinated by hub contracts (Intents, Asset Manager, Hub Wallet Factory). Spoke chains hold user funds and act as deposit and execution venues. The SODAX relayer carries cross-chain messages between them.

Deep dives: [Technical Overview](https://docs.sodax.com/developers/technical-overview.md), [Asset Manager](https://docs.sodax.com/developers/technical-overview/asset-manager.md), [Generalized Messaging Protocol](https://docs.sodax.com/developers/technical-overview/generalized-messaging-protocol.md).

### HTTP API

#### Can I integrate without the SDK?

Yes. The [HTTP API](https://docs.sodax.com/developers/http-api.md) covers swaps and leverage yield from any language, plus read endpoints for prices, stats and configuration. The money market's supply and borrow flows have no HTTP write endpoints, so those need [`@sodax/sdk`](https://docs.sodax.com/developers/packages/foundation/sdk/functional-modules/money_market).

#### Do I need an API key?

Create one in the [partner portal](https://portal.sodax.com) and send it from your server. [API keys](https://docs.sodax.com/developers/how-to/api-keys.md) covers what the key does, where it goes, and which routes check it.

#### How do I track a swap over HTTP?

After you broadcast the intent and call `submit-tx`, poll its status until it reaches a terminal state. [Poll status](https://docs.sodax.com/developers/http-api/swaps.md#4-poll-status) lists the states and what to do on failure.

### SDK setup

#### 4. Do I need to call `sodax.initialize()` before using the SDK?

No. The constructor uses the config packaged with the SDK version you installed, and `initialize()` currently returns success without fetching anything, so it does not add tokens or chains listed after your release. Calling it is harmless.

To use a token listed after your release, upgrade `@sodax/sdk`, or use the backend API clients (`sodax.api.swaps`, `sodax.api.bridge`, `sodax.api.leverageYield`), which leave token validation to the backend.

See [Where supported tokens come from](https://docs.sodax.com/developers/how-to/configure_sdk.md#where-supported-tokens-come-from).

#### 5. How do I override the hub RPC or contract addresses?

Pass a partial `hub` block to the constructor:

```tsx theme={null}
new Sodax({ hub: { rpcUrl: 'https://rpc.soniclabs.com' } })
```

Read the merged config from `sodax.instanceConfig.hub`. Note that `sodax.config.getHubChainConfig()` returns the packaged snapshot, not your overrides.

Full config reference: [Configure SDK](https://docs.sodax.com/developers/how-to/configure_sdk.md).

### SDK behaviour

#### 6. Why don't SDK methods throw?

Every public method returns `Result<T, E>` shaped as `{ ok: true, value }` or `{ ok: false, error }`. Do not wrap SDK calls in try/catch. Check `result.ok` first, then discriminate on `result.error.code`.

The pattern is canonical across modules: [Backend API](https://docs.sodax.com/developers/packages/foundation/sdk/tooling-modules/backend_api.md).

#### 7. How should I handle errors properly?

Switch on the narrow `error.code` union (for example `VALIDATION_FAILED`, `RELAY_TIMEOUT`, `TX_SUBMIT_FAILED`). Never branch on `error.message`, it is human-readable and may change. The original lower-level error is preserved on `error.cause`, structured metadata on `error.context`. Use the exported guards (`isSwapError`, `isStakeOrchestrationError`, `isMigrateOrchestrationError`, `isPartnerError`) in dapp code for cross-bundle type safety.

Per-module code tables: [Swaps](https://docs.sodax.com/developers/packages/foundation/sdk/functional-modules/swaps.md), [Money Market](https://docs.sodax.com/developers/packages/foundation/sdk/functional-modules/money_market.md), [Bridge](https://docs.sodax.com/developers/packages/foundation/sdk/functional-modules/bridge.md), [Staking](https://docs.sodax.com/developers/packages/foundation/sdk/functional-modules/staking.md), [Migration](https://docs.sodax.com/developers/packages/foundation/sdk/functional-modules/migration.md).

#### 8. What should I do when a swap returns `RELAY_TIMEOUT`?

The spoke transaction landed but the hub packet has not arrived within the timeout window. The relay may still complete. Persist the spoke tx hash and poll the relayer API. Do not re-submit from the user side.

Error semantics: [Make a swap (SDK)](https://docs.sodax.com/developers/how-to/how_to_make_a_swap.md), [Relayer API endpoints](https://docs.sodax.com/developers/deployments/relayer-api-endpoints.md).

#### 9. What does `TX_SUBMIT_FAILED` mean?

The critical case. The spoke tx landed but the relay submission itself failed. Funds may be in flight. Persist the user's input plus spoke tx hash and retry submission against the relay API. Do not retry the user-facing transaction.

Full code reference: [Make a swap (SDK)](https://docs.sodax.com/developers/how-to/how_to_make_a_swap.md).

### Swaps and intents

#### 10. What is the difference between `swap()`, `createIntent()` and `createLimitOrder()`?

`swap()` coordinates intent creation, relay submission and solver notification (signed execution only). It does **not** approve the input token for you. Before calling it, check `isAllowanceValid()` and call `approve()` when it returns `false`. On EVM chains this is an ERC-20 allowance and on Stellar it is a trustline; other chains return `true` and need no approval. See the [token approval flow](https://docs.sodax.com/developers/packages/foundation/sdk/functional-modules/swaps.md#token-approval-flow) for chain-specific requirements.

A successful submission is not settlement: [poll until settled](https://docs.sodax.com/quickstart.md#poll-until-settled).

`createIntent()` is the lower-level primitive and supports both signed and raw modes (`raw: true` for custom signing flows).

`createLimitOrder()` produces an intent with no deadline. The user must cancel it manually.

Full method list: [Swaps](https://docs.sodax.com/developers/packages/foundation/sdk/functional-modules/swaps.md).

#### 11. How do I get a swap quote and feed it into `minOutputAmount`?

Call `sodax.swaps.getQuote(payload)` with `token_src`, `token_dst`, source and destination `ChainKeys`, an amount in the token's smallest unit, and `quote_type: 'exact_input'`. Use `quoted_amount` from the response to set `minOutputAmount` on the intent.

Walkthrough with code: [Make a swap (SDK)](https://docs.sodax.com/developers/how-to/how_to_make_a_swap.md).

#### 12. Can I cancel an intent?

Yes. Call `cancelIntent(intent)` on the Intents contract. The caller must be the creator, or the deadline must have passed. Intents with pending fills cannot be cancelled. Limit orders (`deadline = 0`) always require manual cancellation.

Contract interface: [Intents](https://docs.sodax.com/developers/technical-overview/intents.md).

#### 13. Are intents trustless? Can a solver run off with funds?

No. Solvers cannot exit with user funds. They lock collateral in the `IntentFiller` contract on the destination spoke when filling. The hub is the source of truth for intent state and settlement, spokes act only as escrow and execution venues. Settlement reconciles cross-chain via the relay.

Detailed flow: [Intents](https://docs.sodax.com/developers/technical-overview/intents.md).

### Lend, borrow, bridge, stake

#### 14. Which actions actually need on-chain approval?

EVM spokes: `supply` and `repay` approve the Asset Manager contract.

Sonic hub: `supply` and `repay` approve the user's hub router.

Stellar: `supply`, `repay`, `withdraw`, `borrow` all check and establish trustlines.

Borrow and withdraw on EVM and hub do not require approval. Most non-EVM chains require no on-chain approval at all.

Full matrix: [Money Market](https://docs.sodax.com/developers/packages/foundation/sdk/functional-modules/money_market.md).

#### 15. How is the bridge different from a swap?

Bridge moves the same asset across chains using the hub vault, with no price discovery. Swap routes through the solver marketplace for cross-network price execution. The bridge supports three directions: spoke to hub, hub to spoke, and spoke to spoke.

See [Bridge](https://docs.sodax.com/developers/packages/foundation/sdk/functional-modules/bridge.md) and [Swaps](https://docs.sodax.com/developers/packages/foundation/sdk/functional-modules/swaps.md).

#### 16. How do I estimate gas across different chain families?

Build a raw tx with `raw: true` from any `createIntent`, `createSupplyIntent`, `approve`, etc. Then call the matching module's `estimateGas({ tx, chainKey })`. The return shape depends on the chain family.

EVM, ICON, Stellar, Bitcoin, NEAR return a `bigint`. Sui returns `{ computationCost, storageCost, storageRebate, nonRefundableStorageFee }`. Injective returns `{ gasWanted, gasUsed }`. Stacks returns `{ low, medium, high }` fee tiers. Solana returns `number | undefined` compute units.

Examples per chain: [Estimate Gas](https://docs.sodax.com/developers/how-to/estimate_gas.md).

#### 17. Can I stake SODA from a non-EVM chain like Sui or Stellar?

Yes. Every `StakingService` method accepts any `SpokeChainKey` as the source. If you pass `ChainKeys.SONIC_MAINNET`, the spoke and hub tx hashes are identical. Approval is required only on EVM spokes, the hub, and Stellar.

See [Staking](https://docs.sodax.com/developers/packages/foundation/sdk/functional-modules/staking.md).

### Monetization, integration, tooling

#### 18. How do partner fees work and how do I claim them?

Set a global default with the top-level `fee`, then override it per feature with `swaps.partnerFee`, `moneyMarket.partnerFee`, `bridge.partnerFee` and `leverageYield.partnerFee` on `SodaxConfig` — vault flows read the `leverageYield` slot, not `swaps`. `getQuote` deducts the swap partner fee from the input amount before forwarding to the solver, so no fee field appears in the request payload. Claim accrued fees via `sodax.partners.feeClaim*` methods, which return `Result<T, PartnerError>`.

Setup and claim flows: [Monetize SDK](https://docs.sodax.com/developers/how-to/monetize_sdk.md).

#### 19. When do I need the `IntentRelayChainId` versus `ChainKeys`?

The relay API identifies chains by a numeric `IntentRelayChainId` (for example `BASE_MAINNET = 30n`, `SOLANA_MAINNET = 1n`, `BITCOIN_MAINNET = 627463n`). The SDK converts internally. You only need `getIntentRelayChainId(chainKey)` when constructing raw relay requests directly, which is advanced usage.

Full mapping: [Relayer API endpoints](https://docs.sodax.com/developers/deployments/relayer-api-endpoints.md).

#### 20. How do I wire SODAX into my AI coding agent (Claude Code, Cursor, Codex)?

From your project root run `npx skills@latest add gosodax/sodax-sdks/packages/skills`. The CLI detects your tool (Claude Code, Cursor, Codex, Copilot) and installs five skill directories, each with its own `SKILL.md`, into the conventional discovery path (e.g. `.claude/skills/sodax-<pkg>/`). The CLI does **not** copy the package-level `AGENTS.md` — agents auto-discover the skills from `SKILL.md` frontmatter, so there is nothing to point your agent rules at. If you install via npm or a `file:` path instead, `node_modules/@sodax/skills/AGENTS.md` is the router.

See [AI Integration](https://docs.sodax.com/ai-integration-guide.md).

#### 21. What is hub wallet abstraction and when do I touch it directly?

The hub generates a deterministic user wallet on Sonic for every spoke address. For spoke chains with limited calldata, the SDK supports hashed calls: send a 32-byte `keccak256` payload to the hub, then execute the stored call later with the same data. The relayer handles this in normal flows. You only touch it directly when building custom orchestration or recovering stuck cross-chain executions.

See [Hub Wallet Abstraction](https://docs.sodax.com/developers/technical-overview/hub-wallet-abstraction.md).

#### 22. Can my AI agent query SODAX docs directly instead of web-searching?

Yes, two ways. This documentation site hosts an auto-generated MCP server at `docs.sodax.com/mcp` that exposes a search tool over these pages — add it to your agent's MCP config, or use the "Add to \[agent]" option in the contextual menu on any page. For more than doc search, add the [Builders MCP](https://docs.sodax.com/builders-mcp.md) (`https://builders.sodax.com/mcp`): 40 tools giving the agent live chains, tokens, quotes, money market rates, intent lookups **and** these docs, over one endpoint.

See [Builders MCP](https://docs.sodax.com/builders-mcp.md) and [AI Integration](https://docs.sodax.com/ai-integration-guide.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.