> For the complete documentation index, see [llms.txt](https://www.aevo.xyz/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://www.aevo.xyz/docs/api-reference/builder-codes/testnet-and-reconciliation.md). # Testnet guide and reconciliation ## End-to-end on testnet 1. **Fee account.** Create an account on `https://testnet.aevo.xyz`, deposit at least 100 testnet USDC, and create an API key. 2. **Register.** Call `POST /builder/register` with that key, or use **Settings → Builders → Builder Dashboard**. Note your `builder_id`. 3. **Check limits.** Call `GET /builder-config` and pick a rate at or below the caps, for example `0.0003`. 4. **User approval.** From a second (user) account, open `https://testnet.aevo.xyz/builder/approve?builder_id=&max_fee_rate=0.0005` and approve with the wallet. 5. **Order.** From the user account, place a signed order with `builder_id` and `builder_fee_rate: "0.0003"` (see [Placing orders](/docs/api-reference/builder-codes/placing-orders.md)). 6. **Verify.** * The user's trade history shows `builder_fee` on the fill. * `GET /builder/fills` on the fee account shows the same fill. * The fee account's USDC balance has gone up by `builder_fee`. The Python SDK's `builder_example.py` runs this flow. It is a dry run unless `SEND=1` is set. ## Reconciliation For any period: * The sum of `builder_fee` in the CSV export (or `/builder/fills`) equals `fees` from `/builder/stats` for the same window. * Each row's `builder_fee` is: * perpetuals: `builder_fee_rate × price × quantity`; * options: `min(builder_fee_rate × index price × quantity, option_premium_cap × price × quantity)`. * A fill with `builder_fee` = `0` and your `builder_id` executed while a limit was no longer met (for example the user had revoked). It is attributed to you but not charged. * Fees are credited to the fee account in USDC as each fill settles. There is no separate payout. ## Common integration mistakes | Mistake | Symptom | Fix | | -------------------------------------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | Signing `builderFeeRate` / `maxFeeRate` as a decimal | `BUILDER_INVALID_SIGNATURE` or an invalid order signature | Sign the raw 6-decimal integer: `0.0003` → `300`. Send the decimal string in the JSON body. | | Signing a builder order with the normal `Order` type | Invalid order signature | When `builder_id` is set, sign the `Order` type with `builderId` and `builderFeeRate` appended. | | Approval `nonce` in seconds | `BUILDER_INVALID_NONCE` | Use current Unix **milliseconds**. | | Reusing an approval nonce | `BUILDER_INVALID_NONCE` | Each approval needs a new, larger nonce. | | Signing the approval with the API signing key | `BUILDER_INVALID_SIGNATURE` | Approvals must be signed by the user's **wallet**. | | Wrong EIP-712 domain | Invalid signature | `Aevo Testnet` / chain `11155111` on testnet, `Aevo Mainnet` / chain `1` on mainnet, version `1`. | | Rate above the user's approval | `BUILDER_FEE_EXCEEDS_USER_LIMIT` | Check `GET /builder/approval?account=…` and stay at or below `max_fee_rate`. | | Hardcoding the protocol cap | `BUILDER_FEE_EXCEEDS_AEVO_LIMIT` after a cap change | Read `GET /builder-config` at startup and periodically. | | Editing an order without builder fields | Edited order has no `builder_id`; its fills pay no builder fee | Re-send `builder_id` and `builder_fee_rate` on every edit and sign them into the new order. | | Using `DELETE /orders-all` to clean up your app's orders | Cancels the user's other orders too | Cancel your own orders by `order_id` ([`DELETE /orders`](/docs/api-reference/urls/private-api/deleteorders.md) for up to 10 at once). | | Passing `builder_id` to reporting endpoints | `BUILDER_INVALID_ID` | Reporting derives the builder from the fee account's API key. | | Timestamps in ms for reporting | Empty results | `start_time` / `end_time` are Unix **nanoseconds**. | | Non-checksum address in `/builder/approval` | Error | Pass `account` in EIP-55 checksum form. | --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://www.aevo.xyz/docs/api-reference/builder-codes/testnet-and-reconciliation.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.