--- title: "Developer Guides" description: "Integrate BTR: swap, LP, liability transfer, flash, deploy pools, hooks, HTTP API, SDK" audience: tech type: reference status: live lang: en updated: "2026-09-02" publish: true --- # Developer Guides Wire BTR into a contract, a bot, or a front end, from Solidity, TypeScript, Python or Rust. Quotes and routes are computed off chain; a chosen path is then settled either by calling each pool from the caller's own wallet, or in one transaction through the `Router`. Find your intent in the action matrix, then follow the link. Every call below is runnable and tested in the [integration examples](https://github.com/btr-protocol/examples). Addresses for every chain come from `GET /v1/venues`; never hardcode them. See [deployed instances](/docs/2-1-contract-addresses) for the current fleet. --- ## 1. Sections | Section | Contents | |---------|----------| | [5.1. On-chain Integration](/docs/5-1-1-basic-operations) | Solidity: swap, deposit, withdraw, liability swap · pool deployment · hooks · flash · consuming price feeds | | [5.2. API & SDK](/docs/5-2-1-api-sdk-reference) | Gateway HTTP reference · `@btr-protocol/sdk` · quotes & routing · recipes | | [5.3. Operations](/docs/5-3-1-white-labeling) | White-label fronts · protocol fee collection · liquidity incentivization | New to the protocol? Start with [Basic Operations §10](/docs/5-1-1-basic-operations#10-arc-testnet-quickstart): addresses, faucet, first swap. --- ## 2. Action matrix On-chain names are authoritative. | Intent | Prefer | On-chain call | Notes | |----------------------|--------|----------|-------| | Market swap | `POST /v1/route` → `planToLegs` → `buildSwapCalls` | `Pool.swap` × N, or `Router.swap` | Multi-pool and split fills. [Quotes & Routing](/docs/5-2-2-quotes-routing) | | Multi-hop in one transaction | build `Part[]` + `Floor[]` off chain | `Router.swap` | One signature, all or nothing, end-to-end floors. [Composability §2](/docs/5-1-4-composability#2-routing-through-the-router) | | Single-pool swap | `getSwapQuote` + `swap` | `Pool.swap` | Fixed venue, aggregator hop | | Deposit (same asset) | `deposit` / `buildDepositCalls` | `Pool.deposit` | Opening a leg sinks `deadLp` | | Dual-route mint | `rankDeposit` → `buildDepositCalls` | `swap` then `deposit`, or the reverse | Market-first vs deposit-first | | Withdraw (same asset) | `withdraw` | `Pool.withdraw` | Haircut below 100% coverage | | Cross-asset exit | `rankRedeem` → `buildRedeemCalls` | `withdrawTo`, or `swapLiability` + `withdraw` | [Cookbook §3](/docs/5-2-3-cookbook#3-liquidity) | | Transfer liability | encode via `POOL_ABI` | `Pool.swapLiability` | Moves an LP claim across legs; no reserve move | | Donate | encode via `POOL_ABI` | `Pool.donate` | Raises the LP index. Seed the leg first ([Incentivization §3](/docs/5-3-3-incentivization#3-donations)) | | Flash loan | `Flash.flashLoan` | ERC-3156-style, `postFlashLoan` | [Composability §1](/docs/5-1-4-composability#1-flash-loans) | | Collect protocol fees | `Admin.collectProtocolFees` | caller must be `pool.treasury()` | [Protocol Fee Collection](/docs/5-3-2-protocol-fee-collection) | | Deploy a pool | `PoolFactory.createPool` | beacon proxy | Permissionless; `tokens` must be non-empty. Listing needs the AC owner. [Deployment & Curation](/docs/5-1-2-pool-deployment-curation) | | Read a BTR price feed | `IOracle.getFeed` + `isFeedFresh` | `ExternalOracleV4.getFeed` | Third-party consumers. Gate on freshness and the pause bit. [Consuming Price Feeds](/docs/5-1-5-consuming-price-feeds) | | Custom mark adapter | implement `IOracle` | `ADD_ASSET` with EXTERNAL mode | [Oracle configuration](/docs/5-1-2-pool-deployment-curation#32-oracle-configuration) | | Yield / dual ledger | hook + Admin | `UPDATE_HOOK` | [Hooks](/docs/5-1-3-hooks) | | Depth ladder | `POST /v1/depth` | - | Off-chain only. [Quotes & Routing §5](/docs/5-2-2-quotes-routing#5-depth-and-slippage) | Limit and stop orders are front-end constructs, not on-chain order types. --- ## 3. Non-negotiables 1. **Route selection is off chain.** Best execution is a search over every pool's curve, coverage and marks, so it is computed off chain and the result is brought to the contracts. Settle it as `approve` + `Pool.swap` calls batched with EIP-5792 `wallet_sendCalls`, or hand the whole path to `Router.swap` in one transaction. The `Router` executes a path; it never searches for one. Plans and legs are per chain. 2. **Multicall3 cannot swap.** `Pool.swap` pulls `tokenIn` from `msg.sender`, which under Multicall3 is the multicall contract. Calls must originate from the user. 3. **`IPool.sol` does not declare the trading functions.** They live on `Pool.sol`. Use the interface block in [Basic Operations §1](/docs/5-1-1-basic-operations#1-interfaces) or a live ABI from `/v1/abis/Pool`. 4. **`createPool` is permissionless; administration is not.** Listing assets, oracles, curves and hooks all resolve to the chain's single `AccessControl` owner ([Ownership model](/docs/5-1-2-pool-deployment-curation#22-ownership-model)). 5. **Prefer EXTERNAL marks.** EXTERNAL reads `IOracle.getFeed`; INTERNAL is a 1.0 peg helper for cash-collateralized 1:1 tokens only ([Oracles](/docs/3-4-oracles)). 6. **Always pass a real `minAmountOut`.** Nothing bounds the quoted spread from above ([Basic Operations §7](/docs/5-1-1-basic-operations#7-slippage-protection)). --- ## 4. Call graph ```mermaid flowchart TB user[User wallet] --> batch["EIP-5792 wallet_sendCalls or sequential txs"] batch --> approve[ERC-20 approve] batch --> wrap[WETH deposit / withdraw] batch --> swap[Pool.swap] batch --> router["Router.swap (multi-hop, one tx)"] router --> swap batch --> dep[Pool.deposit] batch --> wd[Pool.withdraw / withdrawTo] batch --> liab[Pool.swapLiability] user --> flash[Flash.flashLoan] flash --> poolFlash[Pool.flashPrepare / flashSend] curator[AC owner] --> admin[Admin.addAsset / requestOp] anyone[Anyone] --> factory[PoolFactory.createPool] ``` | Layer | Role | |-------|------| | `POST /v1/quote`, `/v1/route`, `/v1/depth` | Stateless pricing kernels. Same integer arithmetic as the contracts, run on state **you** supply | | `GET /v1/venues`, `/v1/abis/{name}` | Addresses and ABIs, live per chain | | `@btr-protocol/sdk` | Calldata builders, on-chain reads, off-chain AIMM replica | | `Pool` / `Router` / `Admin` / `Flash` / `PoolFactory` | On-chain entry points, one set per chain | --- ## 5. Related - Concepts: [AIMM Overview](/docs/1-overview) · [Glossary](/docs/glossary) - Security: [§3 Overview](/docs/3-overview) · Addresses: [Contract Addresses](/docs/2-1-contract-addresses) - User-facing: [User Guide](/docs/user-guide) - Runnable: [Integration examples](https://github.com/btr-protocol/examples)