> 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/api-reference.md). # Builder API Reference The Nectar Liquid Builder REST API provides programmatic access to manage builder profiles, generate API keys, submit fee requests, and inspect real-time user volume and trade history. *** ### Environments & Base URLs | Environment | Base URL | | ----------------------- | -------------------------------------- | | **Asset Chain Mainnet** | `https://api.nectarliquid.com` | | **Asset Chain Testnet** | `https://api-testnet.nectarliquid.com` | *** ### Authentication All endpoints require one of the following authentication headers: ```http # Using Bearer JWT (from SIWE authentication) Authorization: Bearer # Using Secret API Key X-API-Key: nct_live_72ea004491c13bc498e8fba10034a781 ``` *** ### Endpoints #### 1. Get Builder Profile Retrieve profile details, current fee rate, protocol cap, and primary payout wallet. * **Method**: `GET` * **Path**: `/v1/builders/me` **Example Request** ```bash curl -X GET https://api.nectarliquid.com/v1/builders/me \ -H "X-API-Key: nct_live_..." ``` **Response `200 OK`** ```json { "builder": { "id": "c1f7b028-4ef3-4819-bb20-21db3342ce14", "name": "Apex Trading Terminal", "slug": "apex-terminal", "contactEmail": "dev@apexterminal.io", "status": "active", "registeredAt": "2026-10-15T12:00:00.000Z", "primaryWallet": "0x284d323a81d12E01ac195D940Eb7Cb08a139B7dF", "feeRateBps": 3, "feeCapBps": 5 } } ``` *** #### 2. Update Builder Profile Update mutable builder metadata such as display name or contact email. * **Method**: `PUT` * **Path**: `/v1/builders/me` **Request Body** ```json { "name": "Apex Pro Terminal", "contactEmail": "support@apexterminal.io" } ``` **Response `200 OK`** ```json { "success": true, "builder": { "id": "c1f7b028-4ef3-4819-bb20-21db3342ce14", "name": "Apex Pro Terminal", "contactEmail": "support@apexterminal.io" } } ``` > \[!NOTE] Payout wallet address and fee rate cannot be modified through this endpoint. Payout wallet changes require security multi-factor validation, and fee changes require fee rate requests. *** #### 3. Register as a Builder Create a new builder account, primary wallet, and initial fee policy. * **Method**: `POST` * **Path**: `/v1/builders/register` * **Auth**: Requires SIWE Bearer Token (`Authorization: Bearer `) **Request Body** ```json { "name": "Apex Trading Terminal", "slug": "apex-terminal", "contactEmail": "dev@apexterminal.io", "walletAddress": "0x284d323a81d12E01ac195D940Eb7Cb08a139B7dF" } ``` **Response `201 Created`** ```json { "builder": { "id": "c1f7b028-4ef3-4819-bb20-21db3342ce14", "name": "Apex Trading Terminal", "slug": "apex-terminal", "status": "active", "registeredAt": "2026-10-15T12:00:00.000Z", "primaryWallet": "0x284d323a81d12E01ac195D940Eb7Cb08a139B7dF", "feeRateBps": 0, "feeCapBps": 5 } } ``` *** #### 4. List API Keys Retrieve all API keys associated with your builder account. * **Method**: `GET` * **Path**: `/v1/builders/me/api-keys` **Response `200 OK`** ```json { "keys": [ { "id": "e83f2a1b-94c0-4382-b7ef-6346bc781da2", "label": "Production Server", "publicKey": "pk_live_8f3a1290bb244e8992ca3b776a0129bc", "status": "active", "createdAt": "2026-10-15T12:05:00.000Z" } ] } ``` *** #### 5. Create API Key Pair Generate a new secret and public API key pair. * **Method**: `POST` * **Path**: `/v1/builders/me/api-keys` **Request Body** ```json { "label": "Mobile App Client" } ``` **Response `201 Created`** ```json { "id": "f94c3b2a-15d1-4993-c8fa-7457cd892eb3", "label": "Mobile App Client", "publicKey": "pk_live_5c4b1180aa133d7881ba2a66590118ab", "secretKey": "nct_live_91fb005582d24cd509f9fca21145b892", "status": "active", "createdAt": "2026-10-16T09:30:00.000Z" } ``` *** #### 6. Revoke API Key Permanently revoke an active key pair. * **Method**: `DELETE` * **Path**: `/v1/builders/me/api-keys/:id` **Response `200 OK`** ```json { "success": true, "message": "API key successfully revoked." } ``` *** #### 7. Submit Fee Rate Request Request an increase in your builder fee rate (up to 5 bps). * **Method**: `POST` * **Path**: `/v1/builders/me/fee-rate-requests` **Request Body** ```json { "feeRateBps": 3, "reason": "Integration live in mobile wallet with 10k monthly active traders" } ``` **Response `200 OK`** ```json { "success": true, "request": { "id": "a71b2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d", "feeRateBps": 3, "status": "pending_approval", "createdAt": "2026-10-17T11:00:00.000Z" } } ``` *** #### 8. List Attributed Users Retrieve a paginated report of all traders attributed to your builder ID. * **Method**: `GET` * **Path**: `/v1/builders/me/users` * **Query Parameters**: * `page` (number, default: 1) * `pageSize` (number, default: 20, max: 100) * `sortBy` (`volumeUsd` | `tradeCount` | `firstSeen`, default: `volumeUsd`) * `order` (`asc` | `desc`, default: `desc`) **Response `200 OK`** ```json { "items": [ { "account": "0x51c24...3a9", "firstSeen": "2026-10-16T08:14:22.000Z", "lastSeen": "2026-10-22T14:30:10.000Z", "tradeCount": 42, "volumeUsd": 284500.00, "builderFeeGeneratedUsd": 85.35 } ], "totalItems": 156, "page": 1, "pageSize": 20, "lastPage": 8 } ``` *** #### 9. List Builder Trades Audit trail of individual trade executions routed through your integration. * **Method**: `GET` * **Path**: `/v1/builders/me/trades` * **Query Parameters**: * `page` (number, default: 1) * `pageSize` (number, default: 20, max: 100) * `chainId` (number, optional) * `account` (string, optional trader address filter) * `fromTimestamp` (unix timestamp in seconds) * `toTimestamp` (unix timestamp in seconds) **Response `200 OK`** ```json { "items": [ { "orderId": "0x98f...1a2", "txHash": "0x98f...1a2", "account": "0x51c24...3a9", "marketKey": "0x97D83eE4829D0ca1371144cBdCf3EB44c446460D", "marketSymbol": "WETH/USD", "isLong": true, "sizeDeltaUsd": 10000.00, "builderFeeUsd": 3.00, "status": "executed", "settledAt": "2026-10-22T14:30:10.000Z", "chainId": 42420 } ], "totalItems": 1240, "page": 1, "pageSize": 20, "lastPage": 62 } ``` *** #### 10. Public Protocol Builder Config Public endpoint returning network fee receiver configurations without authentication. * **Method**: `GET` * **Path**: `/v1/builders/config` * **Query Parameters**: `chainId` (e.g. 42420 or 42421) **Response `200 OK`** ```json { "chainId": 42420, "uiFeeReceiver": "0x284d323a81d12E01ac195D940Eb7Cb08a139B7dF", "defaultFeeRateBps": 0, "maxFeeRateBps": 5 } ``` --- # 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/api-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.