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

# Integration guide

> Wire the MultiversX Aggregator into a wallet flow from pair validation to signed transaction broadcast.

Integrate the MultiversX Aggregator by validating the pair, quoting near user confirmation, signing the returned transaction data, and broadcasting the signed transaction.

## Prerequisites

| Requirement               | Why                                                                   |
| ------------------------- | --------------------------------------------------------------------- |
| Wallet or signing service | The Aggregator does not sign transactions.                            |
| Amount conversion         | Quote amounts are smallest unit strings.                              |
| Broadcast path            | Wallet, Gateway, or Relayer broadcast after signing.                  |
| Error handling            | Pair, quote, rate limit, and simulation failures are expected states. |

## Flow

<Steps>
  <Step title="Validate token support">
    Call [`/api/v1/pair-config`](/aggregator/pair-config) with `from` and `to`. Stop if `supported=false`.
  </Step>

  <Step title="Convert the amount">
    Convert the user-entered human-readable amount with `decimalsIn`. See [Token amounts](/resources/token-amounts).
  </Step>

  <Step title="Quote without sender for preview">
    Call [`/api/v1/quote`](/aggregator/quote) with `amountIn` or `amountOut`. Use the response for display only.
  </Step>

  <Step title="Requote with sender at confirmation">
    Pass `sender` when the user confirms. This lets the service build a transaction object when nonce and gas simulation succeed.
  </Step>

  <Step title="Sign and broadcast">
    Sign the returned `transaction`, or build a transaction from `txData` using the correct token transfer shape, then broadcast.
  </Step>
</Steps>

## Implementation Checklist

| Check                         | Required handling                                            |
| ----------------------------- | ------------------------------------------------------------ |
| Pair unsupported              | Show `error` from pair config and stop.                      |
| Amount below minimum          | Compare smallest-unit input with `minAmountIn`.              |
| Slippage changed              | Requote; `txData` encodes slippage-derived minimum output.   |
| Sender changed                | Requote; nonce and transaction fields are sender-specific.   |
| ESDT input with only `txData` | Wrap `txData` with `ESDTTransfer` or `MultiESDTNFTTransfer`. |
| HTTP `429`                    | Back off and queue requests.                                 |
| HTTP `503`                    | Retry after service warmup or snapshot recovery.             |

<Warning>
  Do not reuse `txData` across quote requests. It belongs to the quote, amount, slippage, route, and sender context that produced it.
</Warning>

## Minimal TypeScript Shape

```ts theme={"system"}
async function getSwapTransaction(sender: string) {
  const pair = await fetch(
    "https://swap.xoxno.com/api/v1/pair-config?from=WEGLD-bd4d79&to=USDC-c76f1f"
  ).then((res) => res.json());

  if (!pair.supported) throw new Error(pair.error);

  const params = new URLSearchParams({
    from: "WEGLD-bd4d79",
    to: "USDC-c76f1f",
    amountIn: "1000000000000000000",
    slippage: "0.005",
    sender,
  });

  const quote = await fetch(`https://swap.xoxno.com/api/v1/quote?${params}`)
    .then((res) => {
      if (!res.ok) throw new Error(`quote failed: ${res.status}`);
      return res.json();
    });

  if (!quote.transaction && !quote.txData) {
    throw new Error("quote did not include transaction data");
  }

  return quote;
}
```

## Verify Before Signing

* `pair.supported` is `true`.
* `amountIn` is an integer string in the input token's smallest unit.
* `amountOutMin` matches the slippage shown in the UI.
* `transaction.sender` equals the connected wallet when `transaction` is present.
* The quote was requested after the latest user change to token, amount, slippage, or sender.

## Related Pages

* [Quickstart](/aggregator/quickstart)
* [Quote endpoint](/aggregator/quote)
* [Pair config](/aggregator/pair-config)
* [Routing algorithms](/resources/routing-algorithms)
* [Quote freshness](/resources/quote-freshness)
* [Token amounts](/resources/token-amounts)