> ## 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.

# HyperEVM Wallets

> EVM wallets on HyperEVM, and every other network's wallets through one interface, with @sodax/wallet-sdk-react or a direct provider.

Welcoming cross-network users means supporting the wallets they already use. On HyperEVM, SODAX works with any wallet that can sign EVM transactions on HyperEVM mainnet (chain ID 999), such as MetaMask. On the networks your users arrive from, it is Phantom, Suiet, Lobstr, and more. SODAX gives you both through one interface, so wallet plumbing never becomes the integration.

## Account requirements

* **The network may need adding.** If a user's wallet does not list HyperEVM yet, they add it as a custom network: chain ID 999, RPC URL `https://rpc.hyperliquid.xyz/evm`, currency symbol HYPE. Hyperliquid's [onboarding guide](https://hyperliquid.gitbook.io/hyperliquid-docs/onboarding/how-to-use-the-hyperevm) walks through it.
* **HYPE for gas, held on HyperEVM.** HYPE is HyperEVM's native gas token. HYPE in the user's HyperCore spot balance does not pay HyperEVM gas until it is transferred to HyperEVM.

## React apps: `@sodax/wallet-sdk-react`

The React package wraps each chain family's native wallet SDK (wagmi for EVM networks, including HyperEVM) behind a uniform connector interface with a single persisted store.

```bash theme={null}
pnpm add @sodax/wallet-sdk-react
```

Mount the provider with the chains you serve. HyperEVM is an entry under `EVM`, alongside any other EVM network you support:

```tsx theme={null}
import { SodaxWalletProvider, type SodaxWalletConfig } from '@sodax/wallet-sdk-react';
import { ChainKeys } from '@sodax/types';

const config: SodaxWalletConfig = {
  EVM: {
    chains: {
      [ChainKeys.HYPEREVM_MAINNET]: { rpcUrl: 'https://rpc.hyperliquid.xyz/evm' },
      [ChainKeys.SONIC_MAINNET]: { rpcUrl: 'https://rpc.soniclabs.com' },
    },
  },
};
```

Then connect and read accounts with the same three hooks for every chain family:

```tsx theme={null}
import { useXConnectors, useXConnect, useXAccount } from '@sodax/wallet-sdk-react';

function EvmConnect() {
  const connectors = useXConnectors({ xChainType: 'EVM' }); // MetaMask, Rabby, ...
  const { mutateAsync: connect } = useXConnect();
  const account = useXAccount({ xChainType: 'EVM' });

  if (account.address) return <p>Connected: {account.address}</p>;

  return connectors.map(c => (
    <button key={c.id} onClick={() => connect(c)}>{c.name}</button>
  ));
}
```

One EVM connection covers every EVM network, so the wallet may be on a different network than HyperEVM when your user acts. `useEvmSwitchChain({ xChainId: ChainKeys.HYPEREVM_MAINNET })` returns `isWrongChain` and a `handleSwitchChain` callback to prompt the switch.

### Bridging to SDK calls

`useWalletProvider({ xChainId: ChainKeys.HYPEREVM_MAINNET })` returns a typed `IEvmWalletProvider` ready to pass into any `@sodax/sdk` method. The [swap](/hyperevm/swaps) and [money market](/hyperevm/money-market) calls take it directly.

### Showing balances

Balances read through SODAX (for example `useXBalances` from [`@sodax/dapp-kit`](/developers/packages/experience/dapp-kit)) are HyperEVM balances. They do not include what the user holds in HyperCore spot or perps, so label the figure as the HyperEVM balance.

## Scripts and backends: `EvmWalletProvider`

Outside React, construct the provider from `@sodax/wallet-sdk-core` directly:

```typescript theme={null}
import { EvmWalletProvider } from '@sodax/wallet-sdk-core';
import { ChainKeys } from '@sodax/sdk';

const walletProvider = new EvmWalletProvider({
  privateKey: '0x…', // private key of the HyperEVM account
  chainId: ChainKeys.HYPEREVM_MAINNET,
  rpcUrl: 'https://rpc.hyperliquid.xyz/evm',
});
```

`EvmWalletDefaults` lets you tune behavior per provider: `sendTransaction`, `waitForTransactionReceipt`, `publicClient`, `walletClient`, and `transport`.

***

* Full React reference: [@sodax/wallet-sdk-react](/developers/packages/connection/wallet-sdk-react)
* Every chain family's providers: [Setup Wallet Providers](/developers/how-to/wallet_providers)


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