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

# Quickstart

> Get started with 1tx in under 5 minutes

## Setup your development environment

Follow these steps to integrate 1tx into your application.

### Option 1: Direct Smart Contract Integration

Perfect for DeFi protocols and wallets that want to interact directly with our contracts.

<Steps>
  <Step title="Install Dependencies">
    Install the necessary packages:

    ```bash theme={null}
    npm install viem wagmi
    # or
    yarn add viem wagmi
    ```
  </Step>

  <Step title="Configure Contract Addresses">
    Import the deployed contract addresses (Base Mainnet):

    ```typescript theme={null}
    const ONETX_ROUTER = "0xbFdd5bEdC0cB9B8795A93C2a1fB634012C8F99bC";
    const USDC = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
    ```
  </Step>

  <Step title="Make Your First Buy">
    Execute a buy into Aave USDC using the 1tx router:

    ```typescript theme={null}
    import { parseUnits } from 'viem';

    // Instrument ID for Aave USDC on Base
    const AAVE_USDC_ID = "0x00002105c053a3e1290845e12a3eea14926472ce7f15da324cdf0700056fc04b";
    const amount = parseUnits("1000", 6); // 1000 USDC

    // 1. Approve 1tx Router to spend your USDC
    await usdc.write.approve([ONETX_ROUTER, amount]);

    // 2. Execute buy via 1tx Router
    // buy(instrumentId, amount, minDepositedAmount, fastTransfer, maxFee, referralFeeBps, referralWallet)
    await d1txRouter.write.buy([
      AAVE_USDC_ID,
      amount,
      0n,
      false,
      0n,
      0,                                              // referralFeeBps (0-500, e.g. 25 = 0.25%)
      '0x0000000000000000000000000000000000000000',   // referralWallet (zero address = no referral)
    ]);
    ```

    Use `minDepositedAmount` to enforce your minimum acceptable output. For same-asset deposits such as Aave USDC, `0n` is fine because no internal swap is needed.

    To earn a referral fee, pass `referralFeeBps` (up to `500` = 5%) and a non-zero `referralWallet`. The fee is taken from the input USDC before swap/deposit.
  </Step>
</Steps>

<Note>
  The deployment set in `1tx-contracts/docs/deployments.md` uses `SwapDepositRouter.buy()` and `sell()` on Base, Arbitrum, and Unichain.
</Note>

## Contract Addresses

Need the full multi-chain deployment set? See <a href="/contracts/addresses">Contract Addresses</a> for Base, Arbitrum, and Unichain router, registry, adapter, and bridge addresses.

### Option 2: REST API Integration

Perfect for applications that need instrument discovery, calldata generation, and cross-chain execution tracking.

<Steps>
  <Step title="Get Your API Key">
    Sign up at [https://app.1tx.fi/api-keys](https://app.1tx.fi/api-keys) to get your API key.
  </Step>

  <Step title="Make Your First Request">
    Fetch all available instruments:

    ```bash theme={null}
    curl -H "x-api-key: your-api-key" \
      https://api.1tx.fi/api/v1/instruments
    ```
  </Step>

  <Step title="Query Specific Instrument">
    Get details for a specific instrument:

    ```bash theme={null}
    curl -H "x-api-key: your-api-key" \
      https://api.1tx.fi/api/v1/instruments/0x00002105c053a3e1290845e12a3eea14926472ce7f15da324cdf0700056fc04b
    ```
  </Step>

  <Step title="Build Buy Calldata">
    ```bash theme={null}
    curl -X POST "https://api.1tx.fi/api/v1/transactions/buy" \
      -H "Authorization: Bearer <your_jwt>" \
      -H "x-api-key: your-api-key" \
      -H "Content-Type: application/json" \
      -d '{
        "userAddress": "0x59F84Af036712AFe2fD0Ec77f4D9a6F0a612f1fE",
        "instrumentId": "0x0000a4b194d4938ed6aab5bdbac7ca4b622f3639b1bca1b8b9c3271403d3b1b5",
        "amountUsdc": "2.20"
      }'
    ```

    Send the returned transactions in order with the user's wallet.
  </Step>

  <Step title="Monitor Cross-Chain Completion">
    After the source transaction confirms, poll relay status by source tx hash:

    ```bash theme={null}
    curl "https://api.1tx.fi/api/v1/cctp/relay/tx/0xSourceTxHash"
    ```

    A brief `404 Job not found` immediately after source-chain confirmation is expected while the bridge webhook is being ingested.
  </Step>
</Steps>

### Option 3: Embedded Wallet Integration

Perfect for AI agents and robo-advisors that need automated trading.

<Steps>
  <Step title="Install Privy SDK">
    ```bash theme={null}
    npm install @privy-io/react-auth wagmi viem
    ```
  </Step>

  <Step title="Configure Privy Provider">
    ```typescript theme={null}
    import { PrivyProvider } from '@privy-io/react-auth';

    <PrivyProvider
      appId="your-privy-app-id"
      config={{
        embeddedWallets: {
          createOnLogin: 'all-users',
        },
      }}
    >
      <YourApp />
    </PrivyProvider>
    ```
  </Step>

  <Step title="Create Session Keys">
    Enable automated trading within limits:

    ```typescript theme={null}
    import { usePrivy } from '@privy-io/react-auth';

    const { createSessionKey } = usePrivy();

    // Create session key with limits
    await createSessionKey({
      maxAmount: parseEther("10000"), // Max 10k USDC
      expiry: Date.now() + 86400000, // 24 hours
    });
    ```
  </Step>
</Steps>

## Example Use Cases

<CardGroup cols={2}>
  <Card title="Wallet Integration" icon="wallet" href="/use-cases/wallets">
    Let users deposit to any protocol from any token
  </Card>

  <Card title="AI Agent" icon="robot" href="/use-cases/ai-agents">
    Build autonomous yield optimization strategies
  </Card>

  <Card title="Exchange" icon="building-columns" href="/use-cases/exchanges">
    Offer institutional DeFi access to your users
  </Card>

  <Card title="DeFi Protocol" icon="chart-line" href="/use-cases/defi-protocols">
    Accept deposits in any token, not just your native token
  </Card>
</CardGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Read How It Works" icon="book-open" href="/how-it-works">
    Understand the architecture in detail
  </Card>

  <Card title="Core Concepts" icon="lightbulb" href="/concepts/instrument-registry">
    Learn about universal instrument IDs
  </Card>

  <Card title="View API Docs" icon="terminal" href="/api-reference/introduction">
    Explore all available endpoints
  </Card>

  <Card title="Integration Patterns" icon="diagram-project" href="/integration/overview">
    Choose the best integration for your use case
  </Card>
</CardGroup>