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

# Aggregator Integration

> Integrate AKKA as a liquidity source in a router, wallet, or meta-aggregator

This guide is for server-side integrators such as wallets, cross-chain routers, and meta-aggregators. AKKA is an exact-input, same-chain EVM liquidity source. Use `GET /partner/v1/{chainId}/quote` as the integration contract: it combines exact pricing, executable calldata, payer checks, approval information, and lifecycle metadata in one response.

## Integration contract

| Item                  | Value                                               |
| --------------------- | --------------------------------------------------- |
| Base URL              | `https://api.akka.finance`                          |
| Authentication        | `apikey` request header                             |
| Native-token sentinel | `0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee`        |
| Amount format         | Base-10 integer string in the token's smallest unit |
| Quote type            | Exact input                                         |
| Chain scope           | Same-chain swaps                                    |
| Transaction format    | EVM `to`, `data`, `value`, `gasPrice`, and `gas`    |

## Partner discovery

Use these endpoints instead of hardcoding availability:

* `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

```bash theme={null}
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"
```

`payer` is the address that sends `tx` and supplies the input tokens. `recipient` receives the output and defaults to `payer`. This supports partner executor contracts without forcing output to remain in the executor.

The response includes `quoteId`, `quotedAtBlock`, `generatedAt`, `expiresAt`, `validForSeconds`, `validitySource`, `buyAmount`, `minAmountOut`, `allowanceTarget`, structured `simulation` and `validation`, `issues`, and the ready-to-broadcast `tx`. An HTTP `200` with non-empty `issues` is a valid quote that requires payer action before execution. A validation status of `UNKNOWN` means an RPC check failed and the partner must validate independently.

## Transaction fee model

Inspect `tx.type` before submitting:

```typescript theme={null}
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,
});
```

Do not submit both legacy `gasPrice` and EIP-1559 fields in one transaction.

## Contract executor integration

When a partner contract calls AKKA, that contract—not the end user—is the API `payer` and the router's `msg.sender`. It must hold the input tokens and approve the AKKA Router. The end user may remain the `recipient`.

See the public [Partner Executor Contract](/guides/partner-executor-contract) for a complete, copyable Solidity reference. It demonstrates exact per-call approval, ERC-20 input collection, native-value forwarding, reentrancy protection, router allowlisting, and delivery to the recipient already encoded in `tx.data`. Partners must audit, adapt, deploy, and operate their own version; AKKA does not deploy it for partners.

## RFQ calldata safety

Executable quotes may contain signed Bebop, Hashflow, Native, or other RFQ calldata. Treat every response as short-lived and single-use:

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

`validitySource=ADVISORY` means the API refresh window is conservative metadata rather than a universal on-chain deadline. Route-specific signatures may expire earlier; execute immediately or refresh.

Keep the API key on your backend. Contact the [AKKA team](https://t.me/akka_finance) for a partner key and production rate limit.

## Recommended request flow

<Steps>
  <Step title="Discover support">
    Read `GET /partner/v1/chains` and `GET /partner/v1/{chainId}/sources`. Fetch
    token metadata from `GET /{chainId}/tokens?verified=true`. Cache discovery
    data, never executable quotes.
  </Step>

  <Step title="Request the partner quote">
    Call `GET /partner/v1/{chainId}/quote` with `payer`, `recipient`, and
    exact-input `amount`. Use `buyAmount` for ranking and keep the complete
    response together as one executable unit.
  </Step>

  <Step title="Resolve payer issues">
    Block execution on non-empty `issues`. For `INSUFFICIENT_ALLOWANCE`, approve
    the response's `allowanceTarget`, wait for confirmation, then request a new
    quote. Independently verify validation checks marked `UNKNOWN`.
  </Step>

  <Step title="Validate and broadcast immediately">
    Verify the chain, payer, recipient, expiry, and router allowlist. Simulate
    where supported, then broadcast `tx` without changing `to`, `data`, or
    `value`. Never reuse or retry old calldata.
  </Step>

  <Step title="Report the receipt">
    Send `SUBMITTED`, followed by `CONFIRMED` or `REVERTED`, to `POST
            /partner/v1/executions`. On-chain receipts remain the source of truth.
  </Step>
</Steps>

## Minimal server-side adapter

```typescript akka-source.ts theme={null}
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

`/partner/v1` is additive-only. AKKA may add optional fields or enum values but will not remove fields, change units, or change existing field meaning within v1. Breaking changes require a new versioned path, a migration guide, and advance notice under the partner agreement. Integrators must ignore unknown response fields and enum values safely.

## Current limitations

AKKA currently exposes exact-input, same-chain swaps. There is no exact-output quote, cross-chain status lifecycle, Permit2 flow, gasless transaction, integrator-fee parameter, source allow/deny filter, webhook, or trade-history endpoint. If your integration requires one of these, coordinate the adapter behavior with the AKKA team before launch.

## 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](/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.