Aggregator Integration

​

Integration contract

​

Partner discovery

• GET /partner/v1/chains returns active chains that have a deployed AKKA Router.
• GET /partner/v1/{chainId}/sources returns protocol and pool-type coverage derived from active pools.
• GET /{chainId}/tokens?verified=true returns current verified token metadata.

​

One-call executable quote

curl -G "https://api.akka.finance/partner/v1/1/quote" \
  -H "apikey: YOUR_PARTNER_API_KEY" \
  --data-urlencode "src=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2" \
  --data-urlencode "dst=0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48" \
  --data-urlencode "amount=10000000000000000" \
  --data-urlencode "payer=0xPARTNER_EXECUTOR_OR_USER" \
  --data-urlencode "recipient=0xOUTPUT_RECIPIENT" \
  --data-urlencode "slippage=0.5"

​

Transaction fee model

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

await walletClient.sendTransaction({
  to: quote.tx.to,
  data: quote.tx.data,
  value: BigInt(quote.tx.value),
  gas: BigInt(quote.tx.gas),
  ...feeFields,
});

​

Contract executor integration

​

RFQ calldata safety

• Never cache or persist executable calldata for later execution.
• Never broadcast the same response concurrently from multiple workers.
• Never automatically retry a reverted transaction with the old calldata.
• Refresh after user delay, expiresAt, failed simulation, or nonce replacement.
• Do not edit RFQ targets, offsets, amounts, signatures, or nested route data.
• Use quoteId for logs and support correlation, not as an idempotency key.

​

Recommended request flow

​

Minimal server-side adapter

const AKKA_API = 'https://api.akka.finance';

export class AkkaPartnerSource {
  constructor(private readonly apiKey: string) {}

  private async get<T>(
    path: string,
    params: Record<string, string>,
  ): Promise<T> {
    const url = new URL(path, AKKA_API);
    for (const [key, value] of Object.entries(params))
      url.searchParams.set(key, value);

    const response = await fetch(url, {
      headers: { apikey: this.apiKey },
      signal: AbortSignal.timeout(10_000),
    });
    const body = await response.json();
    if (!response.ok) {
      throw new Error(
        `AKKA ${response.status}: ${body.message ?? JSON.stringify(body)}`,
      );
    }
    return body as T;
  }

  quote(
    chainId: number,
    src: string,
    dst: string,
    amount: bigint,
    payer: string,
    recipient: string,
    slippagePercent: number,
  ) {
    return this.get<{
      quoteId: string;
      buyAmount: string;
      minAmountOut: string;
      expiresAt: string;
      issues: Array<{ code: string; message: string }>;
      allowanceTarget: string | null;
      tx: {
        from?: string;
        to: string;
        data: string;
        value: string;
        gasPrice: string;
        gas: string;
        type?: 'legacy' | 'eip1559';
        maxFeePerGas?: string;
        maxPriorityFeePerGas?: string;
      };
    }>(`/partner/v1/${chainId}/quote`, {
      src,
      dst,
      amount: amount.toString(),
      payer,
      recipient,
      slippage: slippagePercent.toString(),
    });
  }
}

​

Production behavior

• Set a client timeout and treat timeouts, 429, and 5xx as retryable for quote discovery. Use exponential backoff with jitter and do not retry a signed or broadcast transaction automatically.
• Refresh the executable swap response after a user delay. Do not cache executable calldata.
• Compare integer amounts with bigint; never use floating-point values for token quantities.
• A successful HTTP response may include payer problems in issues or UNKNOWN validation states. Resolve or independently verify them before broadcast.
• Simulate the returned transaction when your execution stack supports it. A simulation can still become stale as pool state changes.
• Log partner ID, quote ID, chain ID, token addresses, input amount, returned output, latency, simulation status, issue codes, and transaction hash. Never log API keys, private keys, or full signed RFQ calldata.
• After broadcasting, send POST /partner/v1/executions with the quote ID, chain ID, transaction hash, and SUBMITTED; follow with CONFIRMED or REVERTED. Reporting is best-effort telemetry and never replaces checking the chain receipt.

​

Versioning contract

​

Current limitations

​

Launch checklist

• Obtain a dedicated partner API key and agreed production limits.
• Test native-to-ERC-20, ERC-20-to-native, and ERC-20-to-ERC-20 swaps on each enabled chain.
• Confirm approval, insufficient-balance, no-route, timeout, rate-limit, stale-price, and on-chain-revert behavior.
• Allowlist the active router contracts from Smart Contracts, while still executing against tx.to returned by the API.
• Agree on monitoring, incident escalation, and how AKKA should be named and displayed as a liquidity source.