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

# Intent

> /instructions/intent

This instruction type enables advanced portfolio operations with multiple input and output positions. Define what you want (target tokens with weights), and the system automatically handles routing, bridging, and conversions.

## How It Works

The intent flow:

1. **Accepts input positions** - Multiple source tokens with amounts
2. **Defines target positions** - Desired output tokens with weights (must sum to 1.0)
3. **Automatic routing** - Finds optimal paths for rebalancing
4. **Handles everything** - Swaps, bridges, and multi-step conversions

## Parameters

When using `/instructions/intent` in your `composeFlows` array:

| Parameter         | Type   | Required | Description                                         |
| ----------------- | ------ | -------- | --------------------------------------------------- |
| `slippage`        | number | Yes      | Slippage tolerance (0-1, e.g., 0.01 = 1%)           |
| `inputPositions`  | array  | Yes      | Source tokens with amounts (≥1)                     |
| `targetPositions` | array  | Yes      | Target tokens with weights (≥1, weights sum to 1.0) |

### Input Position Structure

```typescript theme={null}
{
  chainToken: {
    chainId: number,
    tokenAddress: string
  },
  amount: string // in wei
}
```

### Target Position Structure

```typescript theme={null}
{
  chainToken: {
    chainId: number,
    tokenAddress: string
  },
  weight: number // 0-1, all weights must sum to 1.0
}
```

## Complete Workflow Examples

<Tabs>
  <Tab title="Portfolio Rebalancing">
    **Split USDC into multiple tokens**

    ```typescript theme={null}
    import { createWalletClient, http, parseUnits } from 'viem';
    import { privateKeyToAccount } from 'viem/accounts';
    import { base } from 'viem/chains';

    const account = privateKeyToAccount('0x...');
    const walletClient = createWalletClient({
      account,
      chain: base,
      transport: http()
    });

    // Step 1: Build quote request
    const quoteRequest = {
      mode: 'smart-account',
      ownerAddress: account.address,
      composeFlows: [
        {
          type: '/instructions/intent',
          data: {
            slippage: 0.01,
            inputPositions: [{
              chainToken: {
                chainId: 8453, // Base
                tokenAddress: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913' // USDC
              },
              amount: parseUnits('1000', 6).toString() // 1000 USDC
            }],
            targetPositions: [
              {
                chainToken: {
                  chainId: 8453, // Base
                  tokenAddress: '0x4200000000000000000000000000000000000006' // WETH
                },
                weight: 0.6 // 60% to WETH
              },
              {
                chainToken: {
                  chainId: 10, // Optimism
                  tokenAddress: '0x94b008aa00579c1307b0ef2c499ad98a8ce58e58' // USDT
                },
                weight: 0.4 // 40% to USDT
              }
            ]
          }
        }
      ]
    };

    // Step 2: Get quote
    const quote = await fetch('https://api.biconomy.io/v1/quote', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(quoteRequest)
    }).then(r => r.json());

    console.log('Quote type:', quote.quoteType); // 'simple' for smart-account
    console.log('Returned data:', quote.returnedData); // Details for each position

    // Then sign and POST to /v1/execute
    ```
  </Tab>

  <Tab title="Multi-Input Rebalancing">
    **Combine multiple tokens into one**

    ```typescript theme={null}
    const quoteRequest = {
      mode: 'smart-account',
      ownerAddress: account.address,
      composeFlows: [
        {
          type: '/instructions/intent',
          data: {
            slippage: 0.01,
            inputPositions: [
              {
                chainToken: {
                  chainId: 8453,
                  tokenAddress: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913' // USDC
                },
                amount: parseUnits('500', 6).toString()
              },
              {
                chainToken: {
                  chainId: 10,
                  tokenAddress: '0x94b008aa00579c1307b0ef2c499ad98a8ce58e58' // USDT
                },
                amount: parseUnits('500', 6).toString()
              }
            ],
            targetPositions: [{
              chainToken: {
                chainId: 8453,
                tokenAddress: '0x4200000000000000000000000000000000000006' // WETH
              },
              weight: 1.0 // 100% to WETH
            }]
          }
        }
      ]
    };

    // Then quote → sign → execute
    ```
  </Tab>

  <Tab title="Complex Multi-Chain">
    **Rebalance across multiple chains**

    ```typescript theme={null}
    const quoteRequest = {
      mode: 'smart-account',
      ownerAddress: account.address,
      composeFlows: [
        {
          type: '/instructions/intent',
          data: {
            slippage: 0.01,
            inputPositions: [{
              chainToken: {
                chainId: 8453,
                tokenAddress: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913'
              },
              amount: parseUnits('2000', 6).toString()
            }],
            targetPositions: [
              {
                chainToken: {
                  chainId: 8453,
                  tokenAddress: '0x4200000000000000000000000000000000000006'
                },
                weight: 0.4 // 40% WETH on Base
              },
              {
                chainToken: {
                  chainId: 10,
                  tokenAddress: '0x94b008aa00579c1307b0ef2c499ad98a8ce58e58'
                },
                weight: 0.3 // 30% USDT on Optimism
              },
              {
                chainToken: {
                  chainId: 42161,
                  tokenAddress: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831'
                },
                weight: 0.3 // 30% USDC on Arbitrum
              }
            ]
          }
        }
      ]
    };

    // Then quote → sign → execute
    ```
  </Tab>
</Tabs>

## Returned Data Structure

The quote response includes details for each target position:

```json theme={null}
{
  "ownerAddress": "0x...",
  "mode": "smart-account",
  "fee": {...},
  "quoteType": "simple",
  "quote": {...},
  "payloadToSign": [...],
  "returnedData": [
    {
      "outputAmount": "599850000",
      "minOutputAmount": "593850000",
      "targetPosition": {
        "chainToken": {
          "chainId": 8453,
          "tokenAddress": "0x4200000000000000000000000000000000000006"
        },
        "weight": 0.6
      },
      "route": {
        "summary": "lifi[uniswapv3]",
        "steps": [...]
      }
    },
    {
      "outputAmount": "399900000",
      "minOutputAmount": "395900000",
      "targetPosition": {
        "chainToken": {
          "chainId": 10,
          "tokenAddress": "0x94b008aa00579c1307b0ef2c499ad98a8ce58e58"
        },
        "weight": 0.4
      },
      "route": {
        "summary": "lifi[uniswapv3] => across[SpokePoolV3]",
        "steps": [...]
      }
    }
  ]
}
```

## Intent vs Direct Instructions

The Supertransaction API offers two approaches:

| Approach                                    | Use Case                                             | Control Level               |
| ------------------------------------------- | ---------------------------------------------------- | --------------------------- |
| Intent-based (this endpoint)                | Express desired outcome, system determines execution | High-level abstraction      |
| Direct instructions (`/instructions/build`) | Explicitly specify each step                         | Full control over execution |

The intent approach simplifies complex multi-chain operations by automatically:

* Finding optimal routes
* Handling protocol interactions
* Managing cross-chain complexity
* Optimizing for gas efficiency

## Best Practices

<AccordionGroup>
  <Accordion title="Ensure Weights Sum to 1.0">
    All target position weights must sum to exactly 1.0:

    ```typescript theme={null}
    // ✅ Valid
    targetPositions: [
      { chainToken: {...}, weight: 0.6 },
      { chainToken: {...}, weight: 0.4 }
    ] // Sum = 1.0

    // ❌ Invalid
    targetPositions: [
      { chainToken: {...}, weight: 0.5 },
      { chainToken: {...}, weight: 0.6 }
    ] // Sum = 1.1
    ```
  </Accordion>

  <Accordion title="Consider Slippage for Multi-Position Operations">
    Use higher slippage for complex rebalancing:

    ```typescript theme={null}
    // Simple rebalancing: 1%
    slippage: 0.01

    // Complex multi-chain rebalancing: 2%
    slippage: 0.02

    // Many positions with cross-chain: 3%
    slippage: 0.03
    ```
  </Accordion>

  <Accordion title="Validate Output Amounts">
    Check each position's output in returnedData:

    ```typescript theme={null}
    quote.returnedData.forEach((positionResult, index) => {
      const outputUi = formatUnits(BigInt(positionResult.outputAmount), 6);
      const minOutputUi = formatUnits(BigInt(positionResult.minOutputAmount), 6);

      console.log(`Position ${index + 1}:`);
      console.log(`  Expected: ${outputUi}`);
      console.log(`  Minimum: ${minOutputUi}`);
      console.log(`  Route: ${positionResult.route.summary}`);
    });
    ```
  </Accordion>

  <Accordion title="Use for Portfolio Management">
    Intent is perfect for:

    * Rebalancing portfolios to target allocations
    * Converting multiple small positions into fewer tokens
    * Distributing one token across multiple chains
    * DCA (dollar-cost averaging) strategies
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Weights don't sum to 1.0">
    Ensure all weights add up to exactly 1.0:

    ```typescript theme={null}
    const weights = targetPositions.map(p => p.weight);
    const sum = weights.reduce((a, b) => a + b, 0);

    if (Math.abs(sum - 1.0) > 0.0001) {
      throw new Error(`Weights sum to ${sum}, must be 1.0`);
    }
    ```
  </Accordion>

  <Accordion title="No route found for some positions">
    If routing fails:

    * Check token liquidity on source and target chains
    * Verify token addresses are correct
    * Try adjusting weights to reduce complexity
    * Increase slippage tolerance
  </Accordion>

  <Accordion title="Output amounts lower than expected">
    If outputs are too low:

    * Review each position's route in `returnedData`
    * Check if bridge fees are higher than expected
    * Consider splitting into separate operations
    * Verify market prices are as expected
  </Accordion>
</AccordionGroup>