# Integration

### 1. Search for best swap router

```
GET https://2bird.xyz/api/dex/router/search
```

#### Request parameters

<table><thead><tr><th width="148.0703125">Name</th><th width="125.27734375">Type</th><th width="110.296875">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>coinInType</code></td><td>string</td><td>Yes</td><td>Full Sui coin type of the token you are swapping <strong>from</strong></td></tr><tr><td><code>coinOutType</code></td><td>string</td><td>Yes</td><td>Full Sui coin type of the token you are swapping <strong>to</strong></td></tr><tr><td><code>coinInAmount</code></td><td>string</td><td>Yes</td><td>Amount of input token in <strong>base units</strong> (no decimals applied)</td></tr><tr><td><code>feeRate</code></td><td>string</td><td>No</td><td>Fee rate in <strong>basis points</strong> (default: <code>"0"</code>). Max: <code>100</code>(1% ), protocol will charge 20% base on the fee if available.</td></tr></tbody></table>

#### Response

```json
{
  "paths": [
    [
      {
        "coinIn": "0x...::usdc::USDC",
        "coinOut": "0x...::sui::SUI",
        "amountIn": "1000000",
        "amountOut": "5000000",
        "poolId": "0x..."
      }
    ]
  ],
  "amountIn": "1000000",
  "amountOut": "5000000"
}
```

#### Example Request

```bash
curl -X GET \
  "https://2bird.xyz/api/dex/router/search?coinInType=0x0000000000000000000000000000000000000000000000000000000000000002::sui::SUI&coinOutType=0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC&coinInAmount=1000000000"
```

***

### 2. Build Swap Transaction

```
POST https://2bird.xyz/api/dex/router/txb
```

#### Description

Given paths from `/search`, builds a **serialized transaction block** you can sign and execute.

#### Request Body

```json
{
  "feeConfig": {
    "rate": "100", // 1%, Same as previous parameter to /search API
    "recipient": "0xFeeRecipientAddress"
  },
  "partnerCap": "0x64f5a6e78a0568677fc80d49a8eef5818d9750ce074a62958eab567dc961f47a",
  "paths": [ // paths from the /search API
    [
      {
        "coinIn": "0x...::usdc::USDC",
        "coinOut": "0x...::sui::SUI",
        "amountIn": "1000000",
        "amountOut": "5000000",
        "poolId": "0x...",
        "adapter": "..."
      }
    ]
  ],
  "slippage": "50",
  "sender": "0xUserAddress"
}
```

#### Response

```json
{
  "buildTxb": { "0": 143, "1": 255, "2": 128, "...": "..." },
  "error": null
}
```

* `buildTxb` – Transaction bytes (as an object with numeric keys).
* `error` – Error message if building failed.

***

### Frontend Integration

```javascript
// Step 1: Get swap path & quote
const feeRate = '100'; // 0 - 100, 100 = 1%
const searchResponse = await fetch(
  `https://2bird.xyz/api/dex/router/search?coinInType=${coinInType}&coinOutType=${coinOutType}&coinInAmount=${coinInAmount}&feeRate=${feeRate}`
);
const { paths, amountOut } = await searchResponse.json();

// Step 2: Build transaction
const txbResponse = await fetch(`https://2bird.xyz/api/dex/router/txb`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    feeConfig: { rate: feeRate, recipient: feeRecipient },
    partnerCap: '0x64f5a6e78a0568677fc80d49a8eef5818d9750ce074a62958eab567dc961f47a',
    paths: paths,
    slippage: '50', // 0.5%
    sender: userAddress
  })
});

const { buildTxb, error } = await txbResponse.json();
if (error) throw new Error(error);

// Step 3: Sign & Execute
const txBytes = new Uint8Array(Object.values(buildTxb));
const transaction = Transaction.from(txBytes);

signAndExecuteTransaction(
  {
    transaction,
    chain: 'sui:mainnet',
  },
  {
    onSuccess: (result) => {
      console.log('Swap success:', result.digest);
    },
    onError: (err) => {
      console.error('Swap failed:', err);
    }
  }
);
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.2bird.xyz/integration.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.