> For the complete documentation index, see [llms.txt](https://docs.peach.ag/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.peach.ag/documentation/arc/aggregator/quickstart.md).

# Quickstart

Get a quote and transaction with one swap call, then confirm and submit it.

Call `arc.swap()` once to get the quote and validated Direct transaction. This example uses your application's existing viem `wallet` and `publicClient` on Arc Testnet (5042002). For Mainnet configuration, see [Client Configuration](https://docs.peach.ag/documentation/arc/aggregator/core-features/api-configuration-cancellation-and-errors).

### Install and initialize

```bash
npm install @masterpeach/arc-aggregator-sdk@1.0.0 viem@^2.33.3
```

```typescript
import { formatUnits } from "viem";
import { ArcClient, ARC_TESTNET_CONFIG, arcTestnet } from "@masterpeach/arc-aggregator-sdk";

const arc = new ArcClient(ARC_TESTNET_CONFIG, publicClient);
const account = wallet.account ?? (await wallet.getAddresses())[0];
if (!account) throw new Error("Connect a wallet account first");
if (await wallet.getChainId() !== ARC_TESTNET_CONFIG.chainId) throw new Error("Switch to Arc Testnet");
const executor = typeof account === "string" ? account : account.address;
```

### Get the quote and transaction

Use `tokenIn`, `tokenOut`, positive `amount` and `outputDecimals` from your order. Amounts are `bigint` values in input-token base units. Arc swaps use ERC-20 addresses; USDC's ERC-20 interface has 6 decimals.

```typescript
const prepared = await arc.swap({
  from: tokenIn, target: tokenOut, amount, executor,
  slippageBps: 50, // 0.5%; use the user's chosen tolerance
  deadlineSecs: 120,
});
if (prepared.amountIn !== amount) throw new Error("Prepared input differs from the order");
console.log("Expected output:", formatUnits(prepared.expectAmountOut, outputDecimals));
console.log("Minimum received:", formatUnits(prepared.tx.amountOutMin, outputDecimals));
```

`swap()` makes one Aggregator request and returns both quote amounts and transaction data. It does not approve tokens, request a wallet signature or broadcast the swap. Display the returned expected output, minimum received, recipient and fees, then **wait for the user to accept these terms**. Logging them alone is not confirmation.

### Confirm and submit

Submit the same accepted `prepared` result. Do not call `swap()` again in the confirmation handler. The Direct approval helper grants the exact input amount by default; it returns `undefined` when allowance is sufficient.

```typescript
const currentAccount = wallet.account ?? (await wallet.getAddresses())[0];
const currentAddress = typeof currentAccount === "string" ? currentAccount : currentAccount?.address;
if (currentAddress?.toLowerCase() !== prepared.executor.toLowerCase()) throw new Error("Wallet account changed");
if (await wallet.getChainId() !== ARC_TESTNET_CONFIG.chainId) throw new Error("Switch to Arc Testnet");
const approval = await arc.buildDirectApprovalRequest(prepared, executor);
if (approval) {
  const approvalHash = await wallet.sendTransaction({ ...approval.tx, account, chain: arcTestnet });
  const approvalReceipt = await publicClient.waitForTransactionReceipt({ hash: approvalHash });
  if (approvalReceipt.status !== "success") throw new Error(`Approval reverted: ${approvalHash}`);
}
if (prepared.execution.plan.deadline <= BigInt(Math.floor(Date.now() / 1000))) {
  throw new Error("Swap expired; get and confirm a new result");
}
await publicClient.call({ ...prepared.tx, account: executor });
const hash = await wallet.sendTransaction({ ...prepared.tx, account, chain: arcTestnet });
console.log("Transaction hash:", hash); // Save before waiting.
const receipt = await publicClient.waitForTransactionReceipt({ hash });
if (receipt.status !== "success") throw new Error(`Swap reverted: ${hash}`);
```

### Refresh and retry

Discard the result and its confirmation if the tokens, amount, accounts, recipient, network, routing, fees or slippage change. If it expires during approval, call `swap()` again, display its new terms and obtain new acceptance. Never modify signed fields or silently raise slippage.

Cancel or ignore stale requests and disable duplicate submission while a trade is active. If submission times out, resolve the saved hash or wallet nonce before retrying. A successful receipt completes the swap.

See [Direct Swaps](https://docs.peach.ag/documentation/arc/aggregator/core-features/direct-allowance) for complete helpers, [Delegated Swaps](https://docs.peach.ag/documentation/arc/aggregator/core-features/delegated-execution-with-permit2-witness) for prepare → signature → build, and [Transaction Safety](https://docs.peach.ag/documentation/arc/aggregator/core-features/validation-approvals-and-expiry).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.peach.ag/documentation/arc/aggregator/quickstart.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.