Integration

1. Search for best swap router

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

Request parameters

Name	Type	Required	Description
coinInType	string	Yes	Full Sui coin type of the token you are swapping from
coinOutType	string	Yes	Full Sui coin type of the token you are swapping to
coinInAmount	string	Yes	Amount of input token in base units (no decimals applied)
feeRate	string	No	Fee rate in basis points (default: "0"). Max: 100(1% ), protocol will charge 20% base on the fee if available.

Response

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

Example Request

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

{
  "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

{
  "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

// 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);
    }
  }
);