Sub-solver integration
This guide tells you how to go from zero to a settled proposal.
All normative facts (field names, amounts, signature formats, penalty amounts) are in the design document or the OpenAPI document. This guide links to them and does not repeat them. If this guide and one of those disagree, the source document is correct.
You do not need a CoW solver seat, an allowlist entry, or a relationship with CoW DAO. You need an address, collateral in the Escrow, and the ability to sign EIP-712 messages.
Your role as a sub-solver
You are responsible for:
- Collateral. Deposit funds into the Escrow. Your balance must be more than one worst-case Track A debit (
gas + c_l). - Order selection. Find orders in CoW's public orderbook. Compute any route that delivers buy tokens to the GPv2Settlement contract. Assume execution from Trampoline with sell tokens on it.
- Floor and ceiling. Set
minBuyAmountandquoteBuyAmountin your proposal. The safest and recommended option is enforcingminBuyAmount = quoteBuyAmount.quoteBuyAmountis the clearing-price commitment — it determines your score and how much the user receives.minBuyAmountis the on-chain revert threshold. If the route delivers less thanminBuyAmount, the settlement reverts (Track A debit). IfquoteBuyAmountis too low, you lose auctions. For sell orders, you can setminBuyAmount < quoteBuyAmountto opt into loose slippage — but the gap betweenquoteBuyAmountand what the route actually delivers is charged against your escrow. For buy orders,minBuyAmountmust equalquoteBuyAmount. - CoW solver rewards. BYOS does not forward CoW solver rewards to sub-solvers. To earn on a trade, embed a fee inside your route before the sweep — for example, by routing through a pool you operate or by setting your output amount below what the route actually delivers.
You are NOT responsible for:
- Transaction submission. BYOS builds and submits the settlement through the CoW driver. You never call
settle. - Scoring. BYOS scores proposals (
surplus - gas), selects the best one per order, and bids it into CoW's auction. - Gas estimation or fee calculation. BYOS sizes the gas cut. The driver applies protocol and partner fees. Your amounts are raw, pre-fee route amounts.
- Trampoline contract logic. The sweep, the floor check, and the sandbox isolation are in the contract code. You cannot change them.
- CoW protocol compliance. BYOS manages the relationship with CoW DAO, the bonding pool, and the reward accounting. But gatekeeping is non-exculpatory. Your signed route is your responsibility.
Byos Availability
Currently, BYOS is only available in staging competition of BNB chain.
See Active deployments for addresses, endpoints, and chain-specific parameters.
1. Understand the risks
You compute routes. BYOS bids them into CoW's auction under its own bonded solver seat. BYOS submits the settlement and takes the consequences from the protocol.
When a settlement that carries your route fails on-chain, BYOS debits the cost from your escrow balance. BYOS debits this amount without prior approval. Read the terms in #penalties.
minBuyAmount is the floor, quoteBuyAmount is the clearing-price commitment. The contract enforces minBuyAmount as a minimum. If the route delivers less, the settlement reverts. quoteBuyAmount is the amount BYOS bids into the auction — it determines the user's price and your score. A Track A debit is the penalty for a revert. A quoteBuyAmount that is too low loses auctions.
Loose slippage (sell orders only). When you set minBuyAmount < quoteBuyAmount, you accept a wider on-chain tolerance. The delta check uses minBuyAmount, but the clearing price uses quoteBuyAmount. If the route delivers between the two, the difference quoteBuyAmount − delivered is converted to native token and recorded as a buffer entry you owe. If the route over-delivers above quoteBuyAmount, the difference is recorded as a credit that offsets future shortfalls but is never paid out. Entries accumulate in a ledger — credits offset debits — and BYOS debits your escrow only when the outstanding balance exceeds c_l. Monitor your running balance with GET /buffer-balance (API endpoints). For buy orders, minBuyAmount must equal quoteBuyAmount.
Slippage limits. BYOS enforces two per-proposal caps on the gap between quoteBuyAmount and minBuyAmount: MAX_PROPOSAL_SLIPPAGE_BPS (maximum gap as a fraction of quoteBuyAmount, in basis points) and MAX_PROPOSAL_SLIPPAGE_NATIVE (maximum gap in native token value). Proposals that exceed either limit are rejected at ingestion. See Active deployments for the current values on each chain.
2. Deposit collateral
Deposit native token into the Escrow for your address. Any address can fund a sub-solver address. Only the sub-solver address can withdraw.
The deposit causes three effects:
- You can submit proposals. The deposit is the only requirement. The minimum balance must be enough for a single worst-case Track A debit (
#penalties). - BYOS deploys your Trampoline instance. The instance has a deterministic CREATE2 address that is based on your address. You pay this one-time gas cost. All your routes execute in this instance.
- BYOS sets your rate limit. The rate limit scales with your balance (
#proposal-api). A larger deposit gives more throughput.
Withdrawal
Withdrawal is not instant. It is all-or-nothing with a cooldown period. When you request a withdrawal, your effective balance drops to zero immediately. You cannot submit proposals during the cooldown. See #withdrawal-and-freeze.
Key rotation
To rotate keys, use the ERC20 transfer function to move your escrow balance to the new address. Do not withdraw and redeposit. A transfer prevents the gap where you have no collateral.
The new address gets its own Trampoline instance. Your old proposals do not follow you. Your address serves three roles: proposal signer, escrow key, and CREATE2 salt (#proposal-schema).
3. Find orders to route
BYOS does not operate an orderbook. Orders come from CoW's orderbook API. Access to the production orderbook may require permission from the CoW team.
One proposal covers one order (#single-order-solutions). There is no batch format. Both fill-or-kill and partially fillable orders are supported. For partially fillable orders, your proposal's sellAmount can be any amount up to the order's remaining fillable amount, and both minBuyAmount and quoteBuyAmount must independently satisfy the proportionally scaled limit price.
4. Auction timing
Orders appear in CoW's orderbook only after BYOS receives them from the driver in /solve. Do not poll the orderbook before a /solve call has arrived — the orders will not be there yet.
A proposal is valid for one auction window only. It does not carry over to the next auction. When BYOS sends its solution to the driver, the auction window closes. Proposals that were Submitted or Active at that point are cancelled with reason AuctionClosed. New POST /proposals requests after the window closes receive 202 until the next auction arrives.
If an order was not filled in the current auction, submit a new proposal when the next auction opens.
5. Build a route
A route is a list of raw calls. Each call has a target, a value, and calldata. You can use any DEX or protocol. BYOS does not maintain a venue registry. The calls execute as-is inside your Trampoline instance.
Sandbox constraints
Your Trampoline instance holds only the sell amount that BYOS pushes in for this settlement. The instance has no allowance over GPv2Settlement. It has no access to other sub-solver instances. The instance is empty between settlements (#topology).
A route that tries to access protocol buffers gets nothing. A route that plants an approval for future use against a funded contract gets nothing.
Headroom
Leave headroom above the user's limit price. BYOS takes a gas cut from the trade. The CoW driver applies protocol and partner fees on top. If a route quotes exactly at the limit, BYOS skips it because the solution is not feasible.
Sign raw, pre-fee route amounts. Do not pre-subtract fees. The driver creates the fee wedge after your amounts. The wedge stays in the settlement, not in your instance.
Private market makers
If you are a private market maker (MM) holding your own inventory, the Trampoline is your execution sandbox — not your funds contract. The standard routing pattern (compute a DEX route, let the Trampoline execute it) does not apply; instead, your route transfers buy tokens from your own contract into the settlement.
Why not hold inventory in the Trampoline? The Trampoline receives sell tokens only because BYOS encodes a sellToken.transfer(trampoline, sellAmount) interaction in the settlement. If that transfer is omitted — due to a bug or compromise — your route still executes and delivers buy tokens, but you never receive the sell tokens. Routing sub-solvers are not exposed to this: their routes consume sell tokens through DEX swaps, so a missing funding transfer simply reverts the route. An MM transferring from its own inventory has no such natural guard.
Recommended pattern:
- Deploy your own funds contract (or use an EOA) to hold buy-token inventory.
- Grant an ERC-20 approval from your funds contract to your Trampoline instance.
- Your signed route includes two interactions:
buyToken.transferFrom(yourContract, GPv2Settlement, buyAmount)— delivers output directly to the settlement through the Trampoline.sellToken.transfer(yourContract, sellAmount)— forwards the sell tokens the Trampoline received to your contract, before the sweep.
- The Trampoline's sweep sends any remaining balances back to the settlement. The delta check enforces
minBuyAmountas usual.
Your inventory is safe: the approval is to your Trampoline instance only (isolated per sub-solver), and the route is committed via interactionsHash in your EIP-712 signature — BYOS cannot substitute different interactions.
If your route does not explicitly forward sell tokens before the sweep, you can retrieve them post-settlement via claimToken.
Not recommended but not prevented: you may deposit tokens directly into your Trampoline instance and trust BYOS to always include the funding transfer. BYOS has no incentive to omit it, but the trust assumption is stronger than necessary.
6. Sign the proposal
Sign the EIP-712 typed data described in #proposal-schema. The ProposalData struct has nine fields: orderUidHash, sellToken, buyToken, sellAmount, minBuyAmount, quoteBuyAmount, interactionsHash, validUntil, nonce. Get the struct, domain, and typehash from bleu/byos-contracts. Test your signatures against the contract's own test vectors. Do not derive the typehash yourself.
The API verifies your signature at submission. The Trampoline verifies the same signature on-chain at settlement. If the two do not match, the settlement fails.
Domain binding
The EIP-712 domain binds to the TrampolineFactory address. The domain is specific to a chain and a deployment generation. A contracts v2 deployment invalidates all outstanding signatures. Update your domain configuration when contracts change.
Route commitment
The interactionsHash field in the signed struct commits to your route. BYOS cannot substitute different interactions. A third party can verify that the signed data matches the settlement calldata. This property makes Track A debits verifiable.
Expiry
Keep validUntil short. BYOS caps it at ingestion (#proposal-lifecycle). A route that is more than a few minutes old is stale.
Contract signers (EIP-1271)
If your sub-solver is a smart contract, set subSolverAddress in the POST body to your contract's address. The service tries ECDSA first; if that does not match, it calls isValidSignature on your contract. subSolverAddress is your identity: it is the escrow key and the Trampoline CREATE2 salt. It must match the address that holds collateral in the Escrow.
The signature is not limited to 65 bytes. The Trampoline uses SignatureChecker on-chain, so service and contract apply identical verification.
If your contract is upgradeable or has a mutable owner, dispute attribution may not hold after the fact. Use a non-upgradeable signer if dispute resolution matters.
7. Submit and poll
Send a POST request with the proposal. See the OpenAPI document for the payload format, status codes, and rejection reasons.
API endpoints
All endpoints are on the public listener (default port 9585):
| Method | Path | Auth | Purpose |
|---|---|---|---|
POST | /proposals | Proposal signature (in body) | Submit a signed proposal. Returns 200 {"id": n, "status": "active"} if validation passes; 400 ProposalRejected with a typed reason if validation fails; 400 noActiveAuction if no auction is running (proposal not stored); 400 unknownOrder if the order UID is not in the current auction; 202 in the rare case where the proposal was stored but the auction closed before validation ran. Replaying identical signed content returns the original id with 202; reusing a nonce with different content returns 409 NonceAlreadyUsed. |
GET | /proposal/{id} | X-Signature (EIP-712 ReadAuth) | Get your proposal status, rejection reason, and settlement/penalty tx hashes. Automatically falls back to the permanent log if the proposal has been swept from the active store — so this works regardless of how old the proposal is. |
GET | /proposals/{order_uid} | X-Signature | List your proposals on one order. Returns only in-flight proposals by default. Pass ?includeArchived=true to fetch from the permanent log instead, which includes all statuses and swept proposals. |
GET | /proposals/by-sub-solver | X-Signature | List all your proposals. Returns only in-flight proposals by default. Pass ?includeArchived=true to fetch from the permanent log instead. |
GET | /openapi.yaml | None | Machine-readable OpenAPI 3 spec for the full API. Use this to generate a client or validate your integration. |
GET | /buffer-balance | X-Signature (EIP-712 ReadAuth) | Your outstanding buffer balance, the clearing threshold, and individual per-proposal entries. |
DELETE | /proposal/{id} | X-Signature (EIP-712 CancelProposal) | Cancel a proposal. Works only on Submitted or Active proposals. |
Read authentication
Sign an EIP-712 ReadAuth { version: 1 } message once. Send it in the X-Signature header with every GET request. This signature has no timestamp or nonce. If it leaks, the risk is limited to read access to your own proposals. The signature does not grant write or cancellation access.
If you query a proposal that is not yours, you get 404 (not 403). You cannot check if a proposal id exists.
The POST response is the verdict
BYOS validates proposals synchronously on the request path. A 200 response with {"id": n, "status": "active"} means the proposal passed escrow and simulation checks and is live in the current auction. A 400 ProposalRejected response means validation failed — read the typed reason and fix the route or amounts. A 400 noActiveAuction response means no auction is running and the proposal was not stored. A 202 response is a rare race case: the proposal was stored but the auction closed before validation ran; resubmit when the next auction opens.
Poll for state changes
Use GET /proposal/{id} to track what happens after acceptance: when the proposal moves to Executing, Settled, or Cancelled (replaced by a newer proposal, or closed at auction end).
A proposal is valid for the current auction window only. When BYOS closes the auction, the proposal does not carry over. If the order was not filled, submit a new proposal in the next auction.
Once the proposal has been selected in an auction, the response includes four price snapshot fields: sellTokenRefPrice, surplusTokenRefPrice, auctionGasPrice, and clearingPrices. These are the auction-time prices used to score and settle the proposal. They are absent until the first auction selection and never change afterwards.
Run a loop: quote, sign, submit, poll, resubmit. This loop is the intended operating mode.
Cancel a proposal
To cancel a proposal before it settles, send a signed DELETE request. Proposals are immutable and there is no update operation. To replace one, submit a new proposal with a new nonce: when it validates, BYOS cancels your older submitted or active proposals for that order. Do not cancel first; the old proposal remains usable until the replacement becomes active.
8. Error handling
| What happened | Cost | Action |
|---|---|---|
| Rejected at gatekeeping | None | Read the typed rejection reason. Fix the route or the amounts. |
400 noActiveAuction | None | No /solve has arrived yet. BYOS just started or is between auctions. Wait for the next auction and resubmit. |
400 unknownOrder | None | The order UID is not in the current auction. The order may not have reached BYOS yet. Wait for the next auction. |
| Simulation reverted | None (one rate-limit slot used) | The proposal is dropped on the first revert. There are no retries. Resubmit if the route is still valid. |
429 rate limited | None | You are over your budget. Wait out Retry-After. Deposit more escrow for a larger budget. |
503 service unavailable | None | A BYOS dependency is down. Wait out Retry-After and retry; nothing was lost. |
409 NonceAlreadyUsed | None | The nonce was already used for different signed content. Generate a new nonce; retrying the exact same signed proposal is safe and returns its original id. |
403 insufficient escrow | None | Your cached balance is below the minimum collateral. Deposit more. Submission only — reads and cancellations keep working. |
| Expired | None | Your validUntil passed. Use a shorter interval. |
AuctionClosed | None | The auction closed while your proposal was active. Submit a new proposal in the next auction. |
SubsolverOutbid | None | BYOS selected a different sub-solver for this order. Resubmit with a better route for the next auction. |
SolverOutbid | None | BYOS won the internal competition but an external solver settled the order first. Resubmit or move to the next order. |
| Settlement reverted on-chain | Track A debit | BYOS debits your escrow immediately. You have a 72-hour dispute window. |
| BYOS won but did not settle | Smaller Track A debit | Same dispute window and grounds. |
Rate limits: 429 and 503
Your requests share one budget across POST, GET and DELETE, scaled by your escrow balance. A larger deposit buys more throughput. Size your polling against the budget: polling every live proposal on a short interval is what consumes it, and writes are cheap by comparison.
A 429 means you exceeded that budget, or the per-IP limit in front of it. A 503 means a store BYOS depends on is unreachable — infrastructure, not load. The two are deliberately separate so you can tell them apart in your own logs.
Both carry a Retry-After header, in seconds. Honour it. The reference clients do not, and that is a limitation of the examples rather than a pattern to copy: a client that retries at full rate through a 429 gets nothing back sooner and keeps its own counter pinned.
A 403 with InsufficientEscrow on submission means BYOS has a cached balance for your address that is below the minimum collateral. Deposit more; the gate clears within one refresh interval. An address BYOS has not seen before is not rejected — it is admitted at the lowest rate tier.
The gate is on submission alone. Reading and cancelling keep working at any balance, deliberately: requesting a withdrawal drops your effective balance to zero, and you still need to cancel and watch whatever you have live while it winds down.
Simulation failures
Simulation failures do not cost escrow. Only on-chain failures cause escrow debits. If a revert is caused by BYOS's own orchestration (not your route), BYOS pays.
9. Reference implementations
| Language | Location |
|---|---|
| Rust | crates/subsolver in byos-service |
| TypeScript | apps/subsolver in byos-service-ts |
| TypeScript | apps/fynd-subsolver in byos-service-ts |
| TypeScript | apps/private-mm-subsolver in byos-service-ts |
The protocol is language-neutral. Use either example for the sequence, the EIP-712 construction, and the polling behavior. The OpenAPI document specifies all wire-level details.
Pre-launch checklist
Before you go live, make sure that:
- [ ] You funded the Escrow above the minimum. A deposit also deploys your Trampoline.
- [ ] You verified your EIP-712 hashes against the contract's test vectors (not your own derivation). The struct has nine fields.
- [ ] Your domain configuration points to the correct chain and contracts generation.
- [ ] Your
validUntilvalue is within the ingestion cap. - [ ] Your route leaves headroom above the user's limit for the gas cut and the driver's fee shift.
- [ ] For buy orders,
minBuyAmount == quoteBuyAmount == order.buyAmount. - [ ] For sell orders using loose slippage, you understand the escrow charge for the gap between
quoteBuyAmountand the actual delivery. Monitor withGET /buffer-balance. - [ ] If you are a private MM, your inventory is held in your own contract with an approval to your Trampoline — not deposited directly in the Trampoline instance.
- [ ] For partially fillable orders, your
sellAmountdoes not exceed the remaining fillable amount, and both buy amounts satisfy the scaled limit price. - [ ] You have a polling loop that resubmits (not fire-and-forget).