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.
Addresses for every chain come from GET /v1/venues; never hardcode them. See deployed instances for the current fleet.
1. Sections
| Section | Contents |
|---|---|
| 5.1. On-chain Integration | Solidity: swap, deposit, withdraw, liability swap · pool deployment · hooks · flash · consuming price feeds |
| 5.2. API & SDK | Gateway HTTP reference · @btr-protocol/sdk · quotes & routing · recipes |
| 5.3. Operations | White-label fronts · protocol fee collection · liquidity incentivization |
New to the protocol? Start with Basic Operations §10: 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 |
| Multi-hop in one transaction | build Part[] + Floor[] off chain | Router.swap | One signature, all or nothing, end-to-end floors. Composability §2 |
| 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 |
| 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) |
| Flash loan | Flash.flashLoan | ERC-3156-style, postFlashLoan | Composability §1 |
| Collect protocol fees | Admin.collectProtocolFees | caller must be pool.treasury() | Protocol Fee Collection |
| Deploy a pool | PoolFactory.createPool | beacon proxy | Permissionless; tokens must be non-empty. Listing needs the AC owner. 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 |
| Custom mark adapter | implement IOracle | ADD_ASSET with EXTERNAL mode | Oracle configuration |
| Yield / dual ledger | hook + Admin | UPDATE_HOOK | Hooks |
| Depth ladder | POST /v1/depth | - | Off-chain only. Quotes & Routing §5 |
Limit and stop orders are front-end constructs, not on-chain order types.
3. Non-negotiables
- 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.swapcalls batched with EIP-5792wallet_sendCalls, or hand the whole path toRouter.swapin one transaction. TheRouterexecutes a path; it never searches for one. Plans and legs are per chain. - Multicall3 cannot swap.
Pool.swappullstokenInfrommsg.sender, which under Multicall3 is the multicall contract. Calls must originate from the user. IPool.soldoes not declare the trading functions. They live onPool.sol. Use the interface block in Basic Operations §1 or a live ABI from/v1/abis/Pool.createPoolis permissionless; administration is not. Listing assets, oracles, curves and hooks all resolve to the chain’s singleAccessControlowner (Ownership model).- Prefer EXTERNAL marks. EXTERNAL reads
IOracle.getFeed; INTERNAL is a 1.0 peg helper for cash-collateralized 1:1 tokens only (Oracles). - Always pass a real
minAmountOut. Nothing bounds the quoted spread from above (Basic Operations §7).
4. Call graph
| 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 · Glossary
- Security: §3 Overview · Addresses: Contract Addresses
- User-facing: User Guide
- Runnable: Integration examples