Slippage & Best Practices

Slippage

Slippage is the maximum price difference you’re willing to accept between the quoted rate and the executed rate. It protects against price movement during the time between quoting and on-chain execution.

Choosing a slippage value

Slippage	When to use
0.1–0.5%	Stablecoins or high-liquidity pairs (e.g., USDC → USDT)
0.5–1%	Standard pairs with good liquidity (e.g., HYPE → USDC)
1–3%	Lower-liquidity tokens or volatile markets
3–5%	Very low liquidity or fast-moving prices
> 5%	Generally not recommended — consider splitting into smaller trades

Pass slippage as a percentage (not a fraction) to the partner quote endpoint:

# 1% slippage
curl -H "apikey: YOUR_API_KEY" \
  "https://api.akka.finance/partner/v1/999/quote?src=0x...&dst=0x...&amount=1000000000000000000&payer=0x...&recipient=0x...&slippage=1"

The partner API allows 0 to 5. Up to 4 decimal places are supported (for example 0.5 or 1.25).

What happens when slippage is exceeded

The on-chain transaction reverts. You pay gas but no tokens are swapped and no tokens are lost. The user keeps their full balance.

Quote and execution timing

The partner quote returns both the output and transaction. Pool and RFQ state can still change before confirmation. Best practice: A display quote may be shown while the user reviews, but request a fresh partner quote when they click “Swap” and execute it immediately.

// Display response is informational and will not be reused.
const displayQuote = await getPartnerQuote(input);
// ... user reviews and clicks "Swap" ...
const executableQuote = await getPartnerQuote(input);
await sendQuote(executableQuote);

sendQuote sends to, data and value unchanged, with simulation.gasLimit as the gas limit. By default that is also tx.gas; with expected-gas reporting (a per-key option agreed with AKKA) tx.gas is the expected receipt gas (after the refund), and a transaction with that limit runs out of gas. Sending simulation.gasLimit is correct in both modes; tx.gas stands in only on a response without it.

function sendQuote(quote: PartnerQuote) {
  const { tx, simulation } = quote;
  return walletClient.sendTransaction({
    to: tx.to as `0x${string}`,
    data: tx.data as `0x${string}`,
    value: BigInt(tx.value),
    gas: BigInt(simulation.gasLimit ?? tx.gas),
    ...(tx.type === 'eip1559'
      ? {
          maxFeePerGas: BigInt(tx.maxFeePerGas),
          maxPriorityFeePerGas: BigInt(tx.maxPriorityFeePerGas),
        }
      : { gasPrice: BigInt(tx.gasPrice) }),
  });
}

Handling reverts

If a swap transaction reverts on-chain, it’s usually one of these:

Cause	Solution
Price moved beyond slippage tolerance	Ask the user whether to change slippage, then request a fresh quote
Stale quote or RFQ signature	Request a completely new partner quote
Insufficient gas	Send `simulation.gasLimit` as the gas limit, never lower
Insufficient balance	Check the user’s balance before initiating the swap
Insufficient allowance	The token wasn’t approved, or the approval transaction hasn’t confirmed yet

Safe retry pattern

async function requestAndSend(input: QuoteInput) {
  const quote = await getPartnerQuote(input);
  if (quote.issues.length) throw new Error(quote.issues[0].message);
  if (Date.now() >= Date.parse(quote.expiresAt)) {
    throw new Error('Refresh required');
  }
  return sendQuote(quote);
}

Retry network failures while requesting a quote with bounded backoff. After a transaction is signed, broadcast, or reverted, never reuse its calldata and never silently raise the user’s slippage; obtain fresh user intent and a fresh quote.

Gas on HyperEVM

The partner response returns simulation.gasLimit, the gas limit to send (by default also tx.gas), plus either legacy or EIP-1559 fee fields. Inspect tx.type and never submit both fee models.

const { tx, simulation } = await getPartnerQuote({
  src,
  dst,
  amount,
  payer,
  slippage,
});

const feeFields =
  tx.type === 'eip1559'
    ? {
        maxFeePerGas: BigInt(tx.maxFeePerGas),
        maxPriorityFeePerGas: BigInt(tx.maxPriorityFeePerGas),
      }
    : { gasPrice: BigInt(tx.gasPrice) };

await walletClient.sendTransaction({
  to: tx.to as `0x${string}`,
  data: tx.data as `0x${string}`,
  value: BigInt(tx.value),
  gas: BigInt(simulation.gasLimit ?? tx.gas),
  ...feeFields,
});

If you need to override gas, set a higher limit than simulation.gasLimit — never lower:

const gasWithBuffer = (BigInt(simulation.gasLimit ?? tx.gas) * 130n) / 100n; // 30% buffer

Rate limiting

Partner limits are assigned with the API key. Confirm the production quota during onboarding. To stay within it:

Debounce quote requests — Don’t re-fetch on every keystroke. Do not cache executable responses in a CDN, service worker, or persistent store.
Poll at reasonable intervals — For price feeds, 15–30 seconds is sufficient. Prices refresh every ~5 seconds on the backend.
Batch token lookups — Use GET /{chainId}/tokens to fetch all tokens in one call instead of fetching individually.

If you hit the rate limit, the API returns HTTP 429. Back off and retry:

async function fetchWithBackoff<T>(
  url: string,
  headers: Record<string, string>,
): Promise<T> {
  const res = await fetch(url, { headers });
  if (res.status === 429) {
    await new Promise((r) => setTimeout(r, 5000)); // wait 5 seconds
    return fetchWithBackoff(url, headers);
  }
  if (!res.ok) throw new Error(`HTTP ${res.status}`);
  return res.json();
}

Approval best practices

Use the returned target — Approve only the allowanceTarget returned by the partner quote; never assume one router address applies forever.
Prefer exact approval — Approving sellAmount limits exposure. Partners may choose a larger allowance only after their own security review.
Wait and refresh — After approval confirmation, request a new partner quote before swapping.
Native tokens skip approval — HYPE (0xeeee...eeee) doesn’t need approval. Skip the allowance check for native tokens.

const NATIVE = '0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee';

if (src.toLowerCase() !== NATIVE) {
  const quote = await getPartnerQuote(input);
  if (quote.issues.some((issue) => issue.code === 'INSUFFICIENT_ALLOWANCE')) {
    const hash = await approve(
      src,
      quote.allowanceTarget,
      BigInt(quote.sellAmount),
    );
    await waitForReceipt(hash); // wait before swapping
    // Request a new quote; do not use the pre-approval calldata.
  }
}

Amounts and decimals

All amounts in the API are in wei (the token’s smallest unit). Each token has its own decimals value.

Token	Decimals	1.0 in wei
HYPE	18	`1000000000000000000`
USDC	6	`1000000`
UBTC	18	`1000000000000000000`

Use viem’s parseUnits and formatUnits to convert:

import { parseUnits, formatUnits } from 'viem';

// Human → wei
const amountWei = parseUnits('1.5', 18).toString(); // "1500000000000000000"

// Wei → human
const amountHuman = formatUnits(BigInt('1500000000000000000'), 18); // "1.5"

Always use the token’s actual decimals value from the API — don’t hardcode 18. Some tokens use 6, 8, or other values.

Getting Started

Guides

Resources

Slippage

Choosing a slippage value

What happens when slippage is exceeded

Quote and execution timing

Handling reverts

Safe retry pattern

Gas on HyperEVM

Rate limiting

Approval best practices

Amounts and decimals

​Slippage

​Choosing a slippage value

​What happens when slippage is exceeded

​Quote and execution timing

​Handling reverts

​Safe retry pattern

​Gas on HyperEVM

​Rate limiting

​Approval best practices

​Amounts and decimals

Slippage

Choosing a slippage value

What happens when slippage is exceeded

Quote and execution timing

Handling reverts

Safe retry pattern

Gas on HyperEVM

Rate limiting

Approval best practices

Amounts and decimals