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

# Supertransaction API

> Build and execute multi-chain workflows with simple REST API calls

The Supertransaction API lets you build complex blockchain operations—swaps, bridges, DeFi deposits—without writing smart contracts. Users sign once, and Biconomy handles everything.

## The Pattern

Every Supertransaction follows the same four steps:

<Steps>
  <Step title="Build Your Flow">
    Define what you want to do using `composeFlows`—swap tokens, bridge chains, call contracts
  </Step>

  <Step title="Get a Quote">
    POST to `/v1/quote` → receive execution costs, routing info, and a payload to sign
  </Step>

  <Step title="Sign the Payload">
    User signs once (the format depends on wallet type)
  </Step>

  <Step title="Execute">
    POST to `/v1/execute` → Biconomy handles all the blockchain complexity
  </Step>
</Steps>

```typescript theme={null}
// The complete flow in 20 lines
const quote = await fetch('https://api.biconomy.io/v1/quote', {
  method: 'POST',
  body: JSON.stringify({
    mode: 'smart-account',
    ownerAddress: userAddress,
    composeFlows: [{
      type: '/instructions/intent-simple',
      data: { srcChainId: 8453, dstChainId: 10, srcToken: USDC, dstToken: USDT, amount: '100000000', slippage: 0.01 }
    }]
  })
}).then(r => r.json());

const signature = await wallet.signMessage(quote.payloadToSign[0]);

const result = await fetch('https://api.biconomy.io/v1/execute', {
  method: 'POST',
  body: JSON.stringify({ ...quote, payloadToSign: [{ ...quote.payloadToSign[0], signature }] })
}).then(r => r.json());
```

## What You Can Build

<CardGroup cols={2}>
  <Card title="Token Swaps" icon="arrow-right-arrow-left">
    Same-chain or cross-chain swaps with automatic routing
  </Card>

  <Card title="DeFi Actions" icon="vault">
    Deposit, withdraw, stake across any protocol
  </Card>

  <Card title="Multi-Step Flows" icon="layer-group">
    Chain operations: swap → bridge → deposit in one tx
  </Card>

  <Card title="Custom Contracts" icon="code">
    Call any smart contract function
  </Card>
</CardGroup>

## Instruction Types

The `composeFlows` array supports four instruction types:

| Type                          | Use Case                          | Example               |
| ----------------------------- | --------------------------------- | --------------------- |
| `/instructions/intent-simple` | Token swaps (same or cross-chain) | Swap USDC → ETH       |
| `/instructions/intent`        | Complex multi-token operations    | Rebalance portfolio   |
| `/instructions/build`         | Custom contract calls             | Deposit into Aave     |
| `/instructions/build-raw`     | Pre-encoded calldata              | Advanced integrations |

<Tip>
  Start with `intent-simple` for swaps—it handles routing, bridging, and DEX selection automatically.
</Tip>

## Account Modes

Choose the mode that matches your users' wallets:

<Tabs>
  <Tab title="smart-account">
    **For:** Biconomy Nexus accounts, ERC-4337 smart accounts

    ```typescript theme={null}
    { mode: 'smart-account', ownerAddress: '0x...' }
    ```

    * Native gas abstraction
    * Single signature always
    * Funds stay in smart account
  </Tab>

  <Tab title="eoa">
    **For:** MetaMask, Rabby, Trust Wallet, any EOA

    ```typescript theme={null}
    { 
      mode: 'eoa', 
      ownerAddress: '0x...',
      fundingTokens: [{ tokenAddress: '0x...', chainId: 8453, amount: '1000000' }]
    }
    ```

    * Works with any wallet
    * Requires `fundingTokens` parameter
    * Uses Fusion execution under the hood
  </Tab>

  <Tab title="eoa-7702">
    **For:** Embedded wallets (Privy, Dynamic, Turnkey) with EIP-7702

    ```typescript theme={null}
    { mode: 'eoa-7702', ownerAddress: '0x...' }
    ```

    * Best of both worlds
    * Single signature like smart accounts
    * No fundingTokens needed
  </Tab>
</Tabs>

## Gas Options

<CardGroup cols={2}>
  <Card title="Sponsored (Gasless)" icon="gift">
    Omit `feeToken`—gas is paid from your sponsorship account

    ```typescript theme={null}
    { mode: 'smart-account', ownerAddress: '0x...' }
    // No feeToken = sponsored
    ```
  </Card>

  <Card title="User Pays in Token" icon="coins">
    Set `feeToken` to deduct from user's balance

    ```typescript theme={null}
    { 
      feeToken: { address: USDC, chainId: 8453 }
    }
    ```
  </Card>
</CardGroup>

## API Reference

| Endpoint                  | Purpose                                  |
| ------------------------- | ---------------------------------------- |
| `POST /v1/quote`          | Get execution quote and signable payload |
| `POST /v1/execute`        | Submit signed quote for execution        |
| `GET /v1/explorer/{hash}` | Track execution status                   |

Base URL: `https://api.biconomy.io`

## Tutorials

<CardGroup cols={3}>
  <Card title="1. Get Quote" icon="file-lines" href="/overview/supertransaction-api/get-quote">
    Build your first quote request
  </Card>

  <Card title="2. Sign Payload" icon="signature" href="/overview/supertransaction-api/sign-payload">
    Handle different signature types
  </Card>

  <Card title="3. Execute" icon="play" href="/overview/supertransaction-api/execute">
    Submit and track your transaction
  </Card>
</CardGroup>