> For the complete documentation index, see [llms.txt](https://docs.nectarliquid.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nectarliquid.com/builders/admin-console-reference.md). # Admin Console Reference This document preserves the complete technical specification, API reference, data models, and component architectures for the **Builder Admin Console**. Use this reference to implement the Builder Administration section in the **main admin frontend**. *** ## 1. Overview & Architecture The Builder Admin Console provides protocol administrators with tools to: 1. **Oversee Builders**: Search, inspect, edit, freeze, or blacklist registered builders. 2. **Fee Policy Governance**: Review, approve, or reject requested fee rate changes (up to 5 bps). 3. **Monthly Volume Rewards**: Audit monthly rewards epochs, inspect algorithmic wash trading flags, approve payouts, and record on-chain payment transaction hashes. 4. **Protocol Revenue & Analytics**: Track total volume, organic protocol fees, builder fee distributions, and top-performing builders. 5. **Reconciliation & Auditing**: Compare off-chain indexed fee ledgers against on-chain event blocks and audit individual user fee histories. ### Authentication & Authorization All Admin endpoints require: * **EIP-4361 SIWE Session**: `Authorization: Bearer ` * **Admin Allowlist**: The authenticated wallet address must be present in the backend admin allowlist configuration (`ADMIN_WALLET_ADDRESSES` / `walletAllowlist` middleware). Non-admin wallets receive `403 Forbidden` (`ADMIN_ACCESS_DENIED`). *** ## 2. Admin REST API Reference Base URLs: * **Mainnet**: `https://api.nectarliquid.com` * **Testnet**: `https://api-testnet.nectarliquid.com` *** ### 2.1 Builders Management #### `GET /v1/admin/builders` List registered builders with search, filtering, sorting, and pagination. * **Query Parameters**: * `search` (string, optional): Search by builder name, slug, or wallet address. * `status` (`active` | `frozen` | `blacklisted`, optional) * `sortBy` (`volumeUsd` | `tradeCount` | `feeGenerated` | `registeredAt`, default: `volumeUsd`) * `order` (`asc` | `desc`, default: `desc`) * `page` (number, default: 1) * `pageSize` (number, default: 20, max: 100) * **Response `200 OK`**: ```json { "items": [ { "builderId": "c1f7b028-4ef3-4819-bb20-21db3342ce14", "name": "Apex Trading Terminal", "slug": "apex-terminal", "status": "active", "registeredAt": "2026-10-15T12:00:00.000Z", "primaryWallet": "0x284d323a81d12E01ac195D940Eb7Cb08a139B7dF", "feeRateBps": 3, "feeCapBps": 5, "stats": { "uniqueUsers": 45, "tradeCount": 312, "volumeUsd": 1250000.00, "baseFeeGeneratedUsd": 750.00, "builderFeeGeneratedUsd": 375.00 } } ], "totalItems": 18, "page": 1, "pageSize": 20, "lastPage": 1 } ``` *** #### `GET /v1/admin/builders/:builderId` Get full details of a specific builder, including fee policies, wallets, and performance stats. *** #### `PUT /v1/admin/builders/:builderId` Update builder metadata, fee rate, or wallet from the admin panel. * **Request Body**: ```json { "name": "Apex Trading Terminal", "contactEmail": "admin@apexterminal.io", "walletAddress": "0x284d323a81d12E01ac195D940Eb7Cb08a139B7dF", "feeRateBps": 4, "feeCapBps": 5, "description": "Updated description" } ``` *** #### `PATCH /v1/admin/builders/:builderId/status` Change builder status (`active`, `frozen`, `blacklisted`). * **Request Body**: ```json { "status": "frozen", "reason": "Investigating unusual order clustering reported by indexer" } ``` *** #### `POST /v1/admin/builders/:builderId/fee-policies/:policyId/approve` Approve a pending fee rate request submitted by a builder. *** #### `POST /v1/admin/builders/:builderId/fee-policies/:policyId/reject` Reject a pending fee policy request. *** ### 2.2 Monthly Rewards & Wash Trading Governance #### `GET /v1/admin/rewards` List monthly rewards by epoch, including wash trading verification signals. * **Query Parameters**: * `epoch` (string, format: `YYYY-MM`, e.g. `2026-10`) * `status` (`pending` | `review_required` | `approved` | `paid`, optional) * `page` (number, default: 1) * `pageSize` (number, default: 20) *** #### `POST /v1/admin/rewards/:id/approve` Approve a monthly reward record for payout. *** #### `POST /v1/admin/rewards/:id/pay` Record the on-chain payout transaction hash after funds are disbursed. * **Request Body**: ```json { "txHash": "0x98f12a34b56c78d90e12f34a56b78c90d12e34f5a67b89c01d23e45f67a89b01" } ``` *** ### 2.3 Protocol Revenue, Reconciliation & User Audits #### `GET /v1/admin/protocol-revenue` Global protocol revenue analytics (`period`: `24h` | `7d` | `30d` | `all`). #### `GET /v1/admin/reconciliation` Scan on-chain fee events versus backend fee ledger (`chainId`, `fromBlock`, `toBlock`). #### `GET /v1/admin/users/:account` Audit history of fees generated by a specific trader address. *** ## 3. UI Component Architecture for Main Admin Dashboard When integrating into the main admin frontend: 1. **Admin Builders List (`/builders`)**: * Search input + Status filter tabs (`all`, `active`, `frozen`, `blacklisted`). * Table displaying: Builder Name, Primary Wallet, Current Fee Rate (bps), Attributed Users, Volume, Generated Protocol Fees, Status Badge. * Actions: "Edit", "Change Status" (with modal requiring audit reason), "View Details". 2. **Builder Detail Page (`/builders/:id`)**: * Header profile card: Name, Slug, Contact Email, Registered Date, Primary Wallet. * Fee Policy Card: Current active fee rate, pending requests with 1-click "Approve" / "Reject" actions. * Tabbed Panels: * **Users**: Attributed traders with volume and trades. * **Trades**: Chronological audit trail of orders executed with this builder's `uiFeeReceiver`. * **Audit Log**: Chronological log of admin actions (status changes, policy updates, wallet edits). 3. **Monthly Rewards Panel (`/rewards` or tab inside `/builders`)**: * Epoch selector (`YYYY-MM`). * Summary metric cards: Total Qualifying Volume, Total Rewards Pool, Approved Payouts, Pending Review Count. * Table: Builder Name, Qualifying Volume, Reward USD, Unique Traders Count, Top Trader Volume Share %, Status (`review_required`, `approved`, `paid`), Wash Trade Warning Chips. * Actions: "Approve Payout", "Record Payment TxHash". 4. **Reconciliation Tool**: * Chain selector (`42420` Mainnet, `42421` Testnet). * Block range inputs (`From Block`, `To Block`). * Comparison table showing on-chain event counts vs off-chain database counts and variance. --- # 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://docs.nectarliquid.com/builders/admin-console-reference.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.