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

# Your First Swap

> Build a working token swap in 5 minutes

## What You'll Accomplish

By the end of this guide, you'll have:

* ✅ Installed the avnu SDK
* ✅ Fetched the best swap quote
* ✅ Executed a token swap on Starknet

## Prerequisites

<AccordionGroup>
  <Accordion title="Node.js 22+ installed" icon="node-js">
    Download from [nodejs.org](https://nodejs.org/)
  </Accordion>
</AccordionGroup>

## Step 1: Install the SDK

<CodeGroup>
  ```bash npm theme={null}
  npm install @avnu/avnu-sdk
  ```

  ```bash yarn theme={null}
  yarn add @avnu/avnu-sdk
  ```

  ```bash pnpm theme={null}
  pnpm add @avnu/avnu-sdk
  ```
</CodeGroup>

## Step 2: Initialize Your Account

```typescript theme={null}
import { RpcProvider, Account } from 'starknet';

// Setup provider & account from starknet.js
const provider = new RpcProvider({
  nodeUrl: 'https://rpc.starknet.lava.build:443'
});

const account = new Account(
  provider,
  'YOUR_ACCOUNT_ADDRESS',
  'YOUR_PRIVATE_KEY'
);

// Or use hook from starknet-react
const { account } = useAccount();

```

<Warning>
  **Security Note:** Never hardcode private keys in production.
</Warning>

## Step 3: Fetch Swap Quotes

```typescript theme={null}
import { getQuotes } from '@avnu/avnu-sdk';
import { parseUnits } from 'ethers';

const ethAddress = "0x49d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7";
const strkAddress = "0x04718f5a0fc34cc1af16a1cdee98ffb20c31f5cd61d6ab07201858f4287c938d";

const quotes = await getQuotes({
  sellTokenAddress: ethAddress,
  buyTokenAddress: strkAddress,
  sellAmount: parseUnits('0.001', 18), // 0.001 ETH
  takerAddress: account.address,
  size: 3, // Get top 3 quotes (optional, default: 1)
  excludeSources: [], // Exclude specific DEXs (optional)
});

console.log('Best quote:', quotes[0]);
console.log('Estimated output:', quotes[0].buyAmount);
console.log('Gas fees:', quotes[0].gasFees);
console.log('Route:', quotes[0].routes);
```

<Note>
  **Optional Parameters:**

  * `size`: Number of quotes to return (default: 1)
  * `excludeSources`: Array of source names to exclude
  * `integratorFees`: Your integration fees in bps
  * `integratorFeeRecipient`: Address to receive fees
  * `integratorName`: Your platform name
  * `onlyDirect`: if you want only direct routes
</Note>

## Step 4: Execute the Swap

```typescript theme={null}
import { executeSwap } from '@avnu/avnu-sdk';

const result = await executeSwap({
  provider: account,
  quote: quotes[0],
  slippage: 0.001, // 0.1% slippage tolerance
});

console.log('Transaction hash:', result.transactionHash);
```

<Note>
  **Default Behavior:**

  * `executeApprove: true` - Automatically approves token spending if needed
  * `slippage` - Required parameter for price protection
  * Reverts if price moves beyond slippage tolerance
</Note>

## Complete Example

<CodeGroup>
  ```typescript Complete Code theme={null}
  import { RpcProvider, Account } from 'starknet';
  import { getQuotes, executeSwap } from '@avnu/avnu-sdk';
  import { parseUnits, formatUnits } from 'ethers';

  const ethAddress = "0x49d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7";
  const strkAddress = "0x04718f5a0fc34cc1af16a1cdee98ffb20c31f5cd61d6ab07201858f4287c938d";

  async function main() {
    // Setup provider & account from starknet.js
    const provider = new RpcProvider({
      nodeUrl: 'https://rpc.starknet.lava.build:443'
    });

    const account = new Account(
      provider,
      process.env.ACCOUNT_ADDRESS!,
      process.env.PRIVATE_KEY!
    );

    // Fetch quotes
    const quotes = await getQuotes({
      sellTokenAddress: ethAddress,
      buyTokenAddress: strkAddress,
      sellAmount: parseUnits('0.001', 18),
      takerAddress: account.address,
    });

    console.log(`Buying ${formatUnits(quotes[0].buyAmount, 18)} STRK`);

    // Execute swap
    const result = await executeSwap({
      provider: account,
      quote: quotes[0],
      slippage: 0.001, // 0.1%
    });

    // Wait for confirmation
    await provider.waitForTransaction(result.transactionHash);
    console.log('✅ Done:', result.transactionHash);
  }

  main().catch(console.error);
  ```

  ```typescript With Integration Fees theme={null}
  import { RpcProvider, Account } from 'starknet';
  import { getQuotes, executeSwap } from '@avnu/avnu-sdk';
  import { parseUnits } from 'ethers';

  const ethAddress = "0x49d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7";
  const strkAddress = "0x04718f5a0fc34cc1af16a1cdee98ffb20c31f5cd61d6ab07201858f4287c938d";

  async function main() {
    const provider = new RpcProvider({
      nodeUrl: 'https://rpc.starknet.lava.build:443'
    });

    const account = new Account(
      provider,
      process.env.ACCOUNT_ADDRESS!,
      process.env.PRIVATE_KEY!
    );

    // Fetch quotes with integration fees
    const quotes = await getQuotes({
      sellTokenAddress: ethAddress,
      buyTokenAddress: strkAddress,
      sellAmount: parseUnits('0.001', 18),
      takerAddress: account.address,
      integratorFees: 10n, // 0.1% fee (10 bps)
      integratorFeeRecipient: '0xYOUR_FEE_RECIPIENT',
      integratorName: 'MyDApp',
    });

    const result = await executeSwap({
      provider: account,
      quote: quotes[0],
      slippage: 0.01, // 1%
    });

    await provider.waitForTransaction(result.transactionHash);
    console.log('✅ Swap complete:', result.transactionHash);
  }

  main().catch(console.error);
  ```

  ```env Environment Variables theme={null}
  ACCOUNT_ADDRESS=0x...
  PRIVATE_KEY=0x...
  ```
</CodeGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Paymaster" icon="gift" href="/docs/paymaster/index">
    Sponsor gas or multi-token gas payments
  </Card>

  <Card title="API Reference" icon="book" href="/api/swap/get-quotes">
    Complete REST API docs
  </Card>

  <Card title="DCA Orders" icon="calendar-days" href="/docs/dca/index">
    Add automated recurring buys
  </Card>
</CardGroup>

## Resources

<CardGroup cols={3}>
  <Card title="API Reference" icon="code" href="/api/overview">
    REST API documentation
  </Card>

  <Card title="SDK" icon="cube" href="https://github.com/avnu-labs/avnu-sdk">
    TypeScript/JavaScript SDK
  </Card>

  <Card title="Support" icon="life-ring" href="https://t.me/avnu_developers">
    Telegram community
  </Card>
</CardGroup>