Swaps on Hedera - SODAX Docs

SODAX swaps are intents, not bridges. Your user signs one transaction on Hedera that locks the input and declares what they want on the destination network. Solvers fill it; the SODAX relayer carries proof between Hedera, the hub (Sonic), and the destination. If nothing fills, the intent can be cancelled and funds recovered. From your side it is one SDK call. From your user’s side it is one wallet prompt, plus an approval the first time they swap an HTS token.

What this looks like on Hedera

Source: the intent transaction is an EVM transaction sent through Hedera’s JSON-RPC relay and signed by the user’s ECDSA key. ChainKeys.HEDERA_MAINNET ('hedera') identifies the network everywhere in the SDK.
Reach: any solver-compatible asset on any SODAX network is a valid destination, 166 assets today. The on-Hedera asset list only bounds what users hold on Hedera itself, not what they can swap into.
Tokens: Hedera assets are native HTS tokens, addressed by the EVM form of their token ID. USDC is token 0.0.456858, which the SDK lists as 0x000000000000000000000000000000000006f89a. Read addresses from the SDK config; never convert them by hand.
Settlement: output lands on the destination network at dstAddress. Swaps into Hedera settle as HTS balances on the recipient’s EVM address, which must be able to receive the token: see Receiving tokens on Hedera.

Approvals

swap() does not approve the input token for you. HBAR is the native token and needs no approval. Every HTS token does: SODAX’s asset manager pulls it through the token’s ERC-20 interface, so check the allowance first and approve when it falls short.

const allowance = await sodax.swaps.isAllowanceValid({ params, walletProvider });
if (!allowance.ok) throw allowance.error;

if (!allowance.value) {
  const approval = await sodax.swaps.approve({ params, walletProvider });
  if (!approval.ok) throw approval.error;
  // wait for the approval to be mined before calling swap()
}

params is the same intent params object you pass to swap().

Quoting

The solver API quotes both directions:

const quoteResult = await sodax.swaps.getQuote({
  token_src: hbar.address,            // token on Hedera
  token_dst: usdc.address,            // token on the destination network
  token_src_blockchain_id: ChainKeys.HEDERA_MAINNET,
  token_dst_blockchain_id: ChainKeys.ARBITRUM_MAINNET,
  amount: 10n * 10n ** BigInt(hbar.decimals), // 10 HBAR
  quote_type: 'exact_input',          // the only supported quote type
});

getQuote deducts any configured partner fee before quoting, so quoted_amount is the net output the user actually receives.

Fees

Using SODAX is free to integrate. Two fees can apply to a trade:

Base fee: a fixed 0.1% of the input, taken by the protocol. Not configurable; compute it ahead of time with getSolverFee(inputAmount).
Your fee: optional platform fee on top, set by you and paid to you. It is the only fee you control. Configure it at SDK setup and check it with getPartnerFee(inputAmount). See Monetize SDK.

The user also pays Hedera’s network fee for the intent transaction, in HBAR, like any other Hedera EVM transaction.

Executing

Prefer swap(). It creates the intent on Hedera, verifies it landed, submits it to the relay, waits for the packet on the hub, and notifies the solver. The Quickstart has the complete call. Track progress with getStatus(request), and cancel unfilled intents with cancelIntent. Limit orders (intents without deadlines) work from Hedera too, via createLimitOrder. Orchestrating manually with createIntent and submitIntent works the same as on any EVM network: Hedera intents need no relay extra data.

Receiving tokens on Hedera

On most EVM networks any address can receive any token. On Hedera an account receives an HTS token only if it is associated with that token, or still has a free automatic association slot. A delivery to an account that is neither fails. This applies whenever Hedera is the destination: a swap into Hedera, or a money market borrow or withdraw delivered to Hedera. HBAR itself needs no association. Whether an account qualifies depends on how it was created:

`max_automatic_token_associations`	What the account can receive
`-1`	Any token. The default for accounts auto-created by sending to an EVM address, and for hollow accounts once completed. Most accounts made by EVM wallets are in this group.
`> 0`	New tokens until that many slots are used, then only tokens it is already associated with.
`0`	Only tokens it is already associated with.

Check before you submit, using Hedera’s public mirror node. It accepts an EVM address directly:

const MIRROR = 'https://mainnet-public.mirrornode.hedera.com/api/v1';

// tokenAddress is the SDK's EVM address for the HTS token, e.g. usdc.address
async function canReceiveOnHedera(evmAddress: string, tokenAddress: string): Promise<boolean> {
  const tokenId = `0.0.${BigInt(tokenAddress)}`;

  const res = await fetch(`${MIRROR}/accounts/${evmAddress}`);
  if (!res.ok) return false; // no Hedera account at this address yet
  const account: { max_automatic_token_associations: number } = await res.json();
  if (account.max_automatic_token_associations === -1) return true;

  const rel = await fetch(`${MIRROR}/accounts/${evmAddress}/tokens?token.id=${tokenId}`);
  const { tokens }: { tokens: { automatic_association: boolean }[] } = await rel.json();
  if (tokens.length > 0) return true; // already associated

  // Count used automatic slots; this reads the first page, which covers most accounts
  const all = await fetch(`${MIRROR}/accounts/${evmAddress}/tokens?limit=100`);
  const { tokens: held }: { tokens: { automatic_association: boolean }[] } = await all.json();
  const usedSlots = held.filter(t => t.automatic_association).length;
  return usedSlots < account.max_automatic_token_associations;
}

When it returns false, ask the user to associate the token before you submit. From an EVM wallet that is one transaction: every HTS token exposes associate() at its own address (HIP-719), signed by the account that will receive it.

import { parseAbi } from 'viem';

// walletClient: a viem wallet client for the receiving account on Hedera mainnet
const hash = await walletClient.writeContract({
  address: usdc.address as `0x${string}`,
  abi: parseAbi(['function associate() returns (uint256)']),
  functionName: 'associate',
});

Error handling

Operations return Result<T> instead of throwing. The core methods (swap, createIntent, postExecution) return a typed SodaxError union you can switch on by error.code.

Full reference, including raw mode, limit orders, cancellation, and the complete error-code table: Swaps.

​What this looks like on Hedera

​Approvals

​Quoting

​Fees

​Executing

​Receiving tokens on Hedera

​Error handling