API Reference

Base URL

https://alpha.baibai.cx/api/v1

Use this REST API for BaiBai integrations.

Rules

Base only for now: chainId: 8453.
Gasless EIP-712 orders only.
Traditional/non-gasless orders are coming soon.
Amounts are token base units as decimal strings.
Use ERC-20 tokens with Permit2.
Native ETH is not a gasless order token. Use WETH in quote and order requests; callers handle wrap/unwrap transactions.

Base WETH: 0x4200000000000000000000000000000000000006

Endpoints

Method	Path	Purpose
`GET`	`/tokens?chainId=8453`	List supported tokens.
`POST`	`/quote`	Get a quote and EIP-712 typed data.
`POST`	`/orders`	Submit a signed gasless order.
`GET`	`/orders/{orderId}`	Get order status.

List Tokens

GET /tokens?chainId=8453

[
  {
    "chainId": 8453,
    "address": "0x833589fCD6EDb6E08f4c7C32D4f71b54bdA02913",
    "symbol": "USDC",
    "name": "USD Coin",
    "decimals": 6,
    "logoURI": "https://..."
  }
]

Use token decimals to convert user-facing amounts into base units before calling /quote.

Quote

POST /quote

Request

{
  "chainId": 8453,
  "from": "0x1111111111111111111111111111111111111111",
  "receiver": "0x1111111111111111111111111111111111111111",
  "sellToken": "0x833589fCD6EDb6E08f4c7C32D4f71b54bdA02913",
  "buyToken": "0x4200000000000000000000000000000000000006",
  "kind": "sell",
  "sellAmountBeforeFee": "1000000",
  "slippageBps": 50,
  "routingPreference": "auto",
  "signingScheme": "eip712"
}

Field	Required	Description
`chainId`	Yes	Base mainnet: `8453`.
`from`	Yes	Owner address that will sign the order.
`receiver`	No	Recipient of the buy token. Defaults to `from`.
`sellToken`	Yes	ERC-20 sell token. Use WETH instead of native ETH.
`buyToken`	Yes	ERC-20 buy token. Use WETH instead of native ETH.
`kind`	Yes	`sell` for exact-input or `buy` for exact-output.
`sellAmountBeforeFee`	For `sell`	Exact sell amount in base units.
`buyAmountAfterFee`	For `buy`	Exact buy amount in base units.
`slippageBps`	No	Slippage in basis points. Defaults to `50`; max `2000`.
`routingPreference`	No	`auto`, `preferBaiBai`, or `onlyBaiBai`. Defaults to `auto`.
`signingScheme`	Yes	Must be `eip712`.

For exact-output quotes, use kind: "buy" and buyAmountAfterFee.

Response

{
  "id": "baibai_quote_123",
  "from": "0x1111111111111111111111111111111111111111",
  "expiration": "2026-06-13T18:35:18.814Z",
  "quote": {
    "sellToken": "0x833589fCD6EDb6E08f4c7C32D4f71b54bdA02913",
    "buyToken": "0x4200000000000000000000000000000000000006",
    "receiver": "0x1111111111111111111111111111111111111111",
    "sellAmount": "1000000",
    "buyAmount": "250000000000000",
    "minBuyAmount": "248750000000000",
    "validTo": 1781375718,
    "feeAmount": "0",
    "kind": "sell",
    "partiallyFillable": false,
    "signingScheme": "eip712"
  },
  "permit2": {
    "allowanceTarget": "0x000000000022D473030F116dDEE9F6B43aC78BA3",
    "spender": "0xbf8E65Fe0711F6B2424372A65070b7A4F2B26567",
    "typedData": {
      "domain": {
        "name": "Permit2",
        "chainId": 8453,
        "verifyingContract": "0x000000000022D473030F116dDEE9F6B43aC78BA3"
      },
      "primaryType": "PermitWitnessTransferFrom",
      "types": { "...": "EIP-712 types" },
      "message": { "...": "Permit2 witness message" }
    },
    "witnessTypeString": "OrderWitness witness)"
  }
}

Field	Description
`id`	Quote ID to submit after signing.
`expiration`	ISO timestamp when the quote expires.
`quote.sellAmount`	Max sell amount in base units.
`quote.buyAmount`	Expected buy amount in base units.
`quote.minBuyAmount`	Minimum buy amount after slippage.
`quote.validTo`	Permit deadline in Unix seconds.
`permit2.allowanceTarget`	Permit2 contract to approve with the sell token.
`permit2.spender`	BaiBai settlement spender in the Permit2 typed data.
`permit2.typedData`	EIP-712 payload to sign exactly as returned.

Approve permit2.allowanceTarget, not permit2.spender. spender is included in the EIP-712 signature.

Quote Expiry

Before signing, verify the quote is still fresh:

const nowSeconds = Math.floor(Date.now() / 1000);
const isFresh =
  Date.parse(quote.expiration) > Date.now() + 10_000 &&
  quote.quote.validTo > nowSeconds + 10;

If the quote is expired or close to expiry, request a fresh quote. This matters when the user must wrap ETH, send an approval transaction, or takes time to confirm a signature.

Quote Controls

routingPreference is optional:

Value	Meaning
`auto`	Default. Choose the best available route. May use BaiBai Prop AMM liquidity, external liquidity, or a split route.
`preferBaiBai`	Prefer BaiBai Prop AMM liquidity when it is competitive with the best available route.
`onlyBaiBai`	Only quote BaiBai Prop AMM liquidity. If BaiBai has no route or enough liquidity, the quote fails.

Examples:

{ "routingPreference": "auto" }

{ "routingPreference": "preferBaiBai" }

{ "routingPreference": "onlyBaiBai" }

Use auto for best execution unless your integration intentionally wants to bias routing.

Submit Order

POST /orders

Request

{
  "quoteId": "baibai_quote_123",
  "signature": "0xabcdef...",
  "clientOrderId": "wallet-session-123"
}

Field	Required	Description
`quoteId`	Yes	Quote ID from `/quote`.
`signature`	Yes	EIP-712 signature over `permit2.typedData`.
`clientOrderId`	No	Integrator-provided idempotency key. Max 128 chars; letters, numbers, `:`, `_`, `-`.

If a request with the same clientOrderId was already accepted for the same owner, BaiBai returns the existing order instead of creating a duplicate. Use the same clientOrderId when retrying after network failures.

Response

{
  "orderId": "baibai_order_123",
  "quoteId": "baibai_quote_123",
  "status": "pending"
}

Get Order

GET /orders/{orderId}

{
  "orderId": "baibai_order_123",
  "quoteId": "baibai_quote_123",
  "status": "filled",
  "sellToken": "0x833589fCD6EDb6E08f4c7C32D4f71b54bdA02913",
  "buyToken": "0x4200000000000000000000000000000000000006",
  "sellAmount": "1000000",
  "buyAmount": "250000000000000",
  "executedSellAmount": "1000000",
  "executedBuyAmount": "250000000000000",
  "txHash": "0x1234..."
}

Status	Meaning	Terminal
`pending`	Order accepted and executing.	No
`filled`	Order completed.	Yes
`failed`	Order failed.	Yes
`expired`	Quote/signature expired before fill.	Yes

Poll every 1-2 seconds, then back off to every 5 seconds for longer-running orders.

Native ETH

Use WETH in quote and order requests.

Swapping from ETH

Request an indicative WETH quote before the user wraps:

{
  "chainId": 8453,
  "from": "0x1111111111111111111111111111111111111111",
  "sellToken": "0x4200000000000000000000000000000000000006",
  "buyToken": "0x833589fCD6EDb6E08f4c7C32D4f71b54bdA02913",
  "kind": "sell",
  "sellAmountBeforeFee": "1000000000000000000",
  "signingScheme": "eip712"
}

Then wrap ETH to WETH, approve Permit2, check quote expiry, sign, and submit. If wrapping or approval takes too long, request a fresh WETH quote.

Swapping to ETH

Quote WETH as the buy token, submit the order, then unwrap WETH after the order fills.

Rate Limits

Rate-limited responses use HTTP 429 and include these headers:

Header	Description
`x-ratelimit-limit`	Request limit for the route/window.
`x-ratelimit-remaining`	Remaining requests in the current window.
`x-ratelimit-reset`	Reset timestamp in milliseconds.
`retry-after`	Seconds to wait before retrying. Present on `429`.

Errors

Errors use this envelope:

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Native ETH is not supported for gasless orders. Use WETH (0x4200000000000000000000000000000000000006) and wrap or unwrap in the caller."
  }
}

Common HTTP statuses:

Status	Code	Retry?	Notes
`400`	`BAD_REQUEST`	No, unless quote/signature is stale.	Invalid input, unsupported token, native ETH, expired quote, invalid signature.
`404`	`NOT_FOUND`	No.	Unknown order ID.
`429`	`RATE_LIMITED`	Yes.	Wait for `retry-after`.
`500`	`INTERNAL_ERROR`	Yes, with backoff.	If submit status is unknown, retry with the same `clientOrderId`.

Examples:

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Unsupported token."
  }
}

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Quote expired. Request a fresh quote."
  }
}

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Invalid signature."
  }
}

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded for quote.once."
  }
}

cURL Happy Path

API=https://alpha.baibai.cx/api/v1
OWNER=0x1111111111111111111111111111111111111111
USDC=0x833589fCD6EDb6E08f4c7C32D4f71b54bdA02913
WETH=0x4200000000000000000000000000000000000006

curl -sS "$API/tokens?chainId=8453" | jq

curl -sS -X POST "$API/quote" \
  -H 'content-type: application/json' \
  --data "{\
    \"chainId\":8453,\
    \"from\":\"$OWNER\",\
    \"receiver\":\"$OWNER\",\
    \"sellToken\":\"$USDC\",\
    \"buyToken\":\"$WETH\",\
    \"kind\":\"sell\",\
    \"sellAmountBeforeFee\":\"1000000\",\
    \"slippageBps\":50,\
    \"routingPreference\":\"auto\",\
    \"signingScheme\":\"eip712\"\
  }" | tee /tmp/baibai-quote.json | jq

# Sign .permit2.typedData with the owner's wallet, then submit:
QUOTE_ID=$(jq -r .id /tmp/baibai-quote.json)
SIGNATURE=0x...
CLIENT_ORDER_ID=$(uuidgen)

curl -sS -X POST "$API/orders" \
  -H 'content-type: application/json' \
  --data "{\
    \"quoteId\":\"$QUOTE_ID\",\
    \"signature\":\"$SIGNATURE\",\
    \"clientOrderId\":\"$CLIENT_ORDER_ID\"\
  }" | tee /tmp/baibai-order.json | jq

ORDER_ID=$(jq -r .orderId /tmp/baibai-order.json)
curl -sS "$API/orders/$ORDER_ID" | jq

Docs

API Reference

Base URL

Rules

Endpoints

List Tokens

Quote

Request

Response

Quote Expiry

Quote Controls

Submit Order

Request

Response

Get Order

Native ETH

Swapping from ETH

Swapping to ETH

Rate Limits

Errors

cURL Happy Path

OpenAPI

Download OpenAPI

Aggregator Flow

Wallet Integration

BaiBai Overview

​Base URL

​Rules

​Endpoints

​List Tokens

​Quote

​Request

​Response

​Quote Expiry

​Quote Controls

​Submit Order

​Request

​Response

​Get Order

​Native ETH

​Swapping from ETH

​Swapping to ETH

​Rate Limits

​Errors

​cURL Happy Path

​OpenAPI

Download OpenAPI

​Related Docs

Aggregator Flow

Wallet Integration

BaiBai Overview

Base URL

Rules

Endpoints

List Tokens

Quote

Request

Response

Quote Expiry

Quote Controls

Submit Order

Request

Response

Get Order

Native ETH

Swapping from ETH

Swapping to ETH

Rate Limits

Errors

cURL Happy Path

OpenAPI

Related Docs