> 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/attribution-and-referrals.md).

# Attribution & Referrals

Nectar Liquid features a robust, non-overwritable **First-Touch Permanent Attribution Model**. This guarantees that once an end-user connects through your builder link or integration, all future trading activity by that user is attributed to your builder account.

***

### First-Touch Permanent Attribution

Many referral programs allow user attribution to be hijacked by subsequent cookie drops or promotional links. Nectar Liquid enforces a first-touch lock:

1. **First-Touch Attribution**: The first builder that introduces a trader receives permanent attribution for that wallet address in protocol accounting.
2. **Re-attribution Protection**: If a user later visits Nectar Liquid through another builder's link or interface, their original builder attribution remains intact.
3. **Multi-Channel Consistency**: Attribution applies whether the user trades through the official web app, an embedded iframe, a third-party mobile wallet, or a Telegram bot.

***

### Web Referral Links

When routing users to the Nectar Liquid web terminal, append your builder UUID using the `builderId` query parameter:

#### Link Formats

* **Asset Chain Mainnet**:

  ```
  https://app.nectarliquid.com/#/trade?builderId=c1f7b028-4ef3-4819-bb20-21db3342ce14
  ```
* **Asset Chain Testnet**:

  ```
  https://testnet.nectarliquid.com/#/trade?builderId=c1f7b028-4ef3-4819-bb20-21db3342ce14
  ```

You can find your unique `builderId` inside the builder portal or via `GET /v1/builders/me`.

***

### Attribution Lifecycle

```
[ User clicks builder link ]
            |
            v
[ Frontend caches builderId in localStorage ]
            |
            v
[ User connects wallet & signs SIWE challenge ]
            |
            v
[ Client sends POST /auth/verify with builderId ]
            |
            v
+---------------------------------------+
|  Backend ensureTrader(address, id)    |
|  - Check if user already attributed   |
|  - If null -> Permanently associate   |
|  - If set  -> Retain original builder |
+---------------------------------------+
            |
            v
[ All trades contribute to your volume & monthly rewards ]
```

#### Step 1: Client Ingestion

When a trader lands on the terminal with `?builderId=<uuid>`, the frontend parses the parameter and persists it in the browser's `localStorage`.

#### Step 2: SIWE Authentication Pass-Through

When the user connects their wallet and authenticates via Sign-In with Ethereum, the client passes `builderId` in the verification payload:

```http
POST /auth/verify
Host: api.nectarliquid.com
Content-Type: application/json

{
  "message": "app.nectarliquid.com wants you to sign in with your Ethereum account:\n0x123...",
  "signature": "0x456...",
  "builderId": "c1f7b028-4ef3-4819-bb20-21db3342ce14"
}
```

#### Step 3: Database Verification & Locking

The backend validates that the `builderId` exists and is active. The internal user service (`ensureTrader`) attributes the trader's account to your builder ID. If the trader was previously attributed to another builder, the existing attribution is preserved.

***

### Monitoring Attributed Traders

Builders can inspect their attributed traders and activity in real time through the builder REST API:

#### List Attributed Users

```http
GET /v1/builders/me/users?page=1&pageSize=20&sortBy=volumeUsd&order=desc
Host: api.nectarliquid.com
X-API-Key: nct_live_...
```

#### Response

```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
}
```


---

# 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/attribution-and-referrals.md?ask=<question>&goal=<user_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.