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

# Atomic Router

> Single-transaction execution of multi-step DeFi flows

## What is Atomic Routing?

Atomic Routing enables complex multi-step DeFi operations (swap → deposit) to execute in a single transaction with all-or-nothing guarantees.

Think of it as **Amazon's 1-Click Checkout for DeFi**: What used to require multiple transactions, approvals, and manual coordination now happens automatically in one click.

## The Problem

Traditional DeFi workflows are complex and error-prone:

**Traditional Approach (5+ transactions):**

1. Approve USDC to DEX
2. Swap USDC → EURC on DEX
3. Wait for swap confirmation
4. Approve EURC to Aave
5. Deposit EURC to Aave

**Risks:**

* Transaction failures at any step
* Price changes between steps
* High gas costs (5 separate transactions)
* Poor user experience
* Funds stuck if interrupted

## The Solution

1tx enables single-transaction deposits:

**1tx Approach (1 transaction):**

1. User sends USDC with instrument ID
   * 1tx automatically swaps USDC → EURC
   * 1tx automatically deposits to Aave
   * User receives aEURC tokens

**Benefits:**

* ✅ All steps succeed or fail together (atomic)
* ✅ No price slippage between steps
* ✅ 40% lower gas costs
* ✅ One-click user experience
* ✅ No partial state or stuck funds

## Atomicity Guarantees

1tx ensures **all-or-nothing execution**:

<CardGroup cols={2}>
  <Card title="Success Case" icon="check">
    All steps complete successfully:

    * User sends USDC ✅
    * Router swaps to EURC ✅
    * Router deposits to Aave ✅
    * User receives aEURC ✅
  </Card>

  <Card title="Failure Case" icon="xmark">
    If ANY step fails, entire transaction reverts:

    * Insufficient liquidity ❌
    * Slippage exceeded ❌
    * Adapter error ❌
    * **No partial state changes**
  </Card>
</CardGroup>

### What Atomicity Means

<AccordionGroup>
  <Accordion title="No Partial State">
    Either everything happens or nothing happens. You'll never be stuck with:

    * EURC when you wanted aEURC
    * Lost tokens in transit
    * Incomplete swaps
    * Failed deposits with successful swaps
  </Accordion>

  <Accordion title="Price Certainty">
    No price changes between swap and deposit steps. The rate you see is the rate you get for the entire operation.
  </Accordion>

  <Accordion title="Automatic Rollback">
    If any step fails, the entire transaction reverts automatically. Your original tokens are returned safely to your wallet.
  </Accordion>

  <Accordion title="Gas Efficiency">
    Pay gas only once for the entire operation instead of 5 separate transactions. Average savings: **40%**
  </Accordion>
</AccordionGroup>

## Transaction Flow Example

Let's walk through a deposit from USDC to Aave EURC vault:

At the contract level, the router path is:

```solidity theme={null}
buy(instrumentId, amount, minDepositedAmount, fastTransfer, maxFee, referralFeeBps, referralWallet)
sell(instrumentId, yieldTokenAmount, minOutputAmount, referralFeeBps, referralWallet)
```

`referralFeeBps` / `referralWallet` are optional — set `referralFeeBps = 0` and `referralWallet = address(0)` to skip the referral fee (fee is capped at 500 bps / 5%).

<Steps>
  <Step title="User Initiates">
    User wants to deposit 1000 USDC into Aave EURC vault (which requires EURC, not USDC)
  </Step>

  <Step title="1tx Detects Need">
    The router resolves the instrument and detects that USDC != EURC, so a swap is needed
  </Step>

  <Step title="Atomic Execution">
    In a single transaction:

    * Swap USDC → EURC internally
    * Deposit EURC to Aave
    * Mint aEURC to user
  </Step>

  <Step title="User Receives">
    User receives aEURC tokens and starts earning yield immediately
  </Step>
</Steps>

## Benefits

<CardGroup cols={2}>
  <Card title="Atomicity" icon="atom">
    All steps succeed or fail together - no partial state
  </Card>

  <Card title="Gas Efficiency" icon="gas-pump">
    40% gas savings vs manual multi-step approach
  </Card>

  <Card title="User Experience" icon="face-smile">
    One-click deposits - no manual coordination
  </Card>

  <Card title="Price Certainty" icon="lock">
    No price changes between swap and deposit steps
  </Card>

  <Card title="Security" icon="shield">
    Reentrancy protected, slippage controlled
  </Card>

  <Card title="Composability" icon="puzzle-piece">
    Works with any ERC20 token and lending protocol
  </Card>
</CardGroup>

## Comparison with Alternatives

| Feature             | Manual Multi-Tx | 1inch Fusion | 1tx Atomic Router |
| ------------------- | --------------- | ------------ | ----------------- |
| Single Transaction  | ❌               | ✅            | ✅                 |
| Protocol Agnostic   | ✅               | ✅            | ✅                 |
| Gas Optimized       | ❌               | ⚠️           | ✅                 |
| Automatic Deposits  | ❌               | ❌            | ✅                 |
| Slippage Protection | Manual          | ✅            | ✅                 |
| No Partial State    | ❌               | ✅            | ✅                 |

## Withdrawal Flow

Withdrawals work in reverse with the same atomic guarantees:

<Steps>
  <Step title="User Initiates Withdrawal">
    User wants to withdraw from Aave EURC, receive USDC
  </Step>

  <Step title="1tx Withdraws">
    1tx withdraws EURC from Aave using your aEURC tokens
  </Step>

  <Step title="1tx Swaps">
    1tx automatically swaps EURC back to USDC
  </Step>

  <Step title="User Receives">
    User receives original token (USDC) - all in one transaction
  </Step>
</Steps>

<Info>
  Withdrawals have the same atomicity guarantees - if any step fails, the entire transaction reverts and your aEURC tokens remain safe.
</Info>

<Info>
  The current router implementation supports cross-chain `buy()` flows through CCTP, but `sell()` is local-chain only.
</Info>

## Next Steps

<CardGroup cols={2}>
  <Card title="Instrument Registry" icon="fingerprint" href="/concepts/instrument-registry">
    Learn about universal instrument IDs
  </Card>

  <Card title="How It Works" icon="gears" href="/how-it-works">
    See the complete transaction flow
  </Card>

  <Card title="Integration Guide" icon="book" href="/integration/overview">
    Start integrating atomic routing
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/introduction">
    Query instruments via API
  </Card>
</CardGroup>