# 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);
    }
  }
);
```