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=<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).

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 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.