docs(builders): Mintlify MDX pack for the Builders API

builders/authentication.mdx

@@ -0,0 +1,69 @@
+---
+title: "Authentication"
+description: "How Builders API keys work."
+---
+
+## Header
+
+Send your key on every request:
+
+```http
+x-api-key: jxn_live_…
+```
+
+The legacy `X-Junction-Api-Key` header is also accepted and carries the
+same key. New integrations should prefer `x-api-key`.
+
+<Warning>
+Never embed the API key in a front-end bundle or in a public repository.
+The key is server-side only. If you need a web UI that talks to the
+Builders API, proxy through your own backend.
+</Warning>
+
+## Request a key
+
+Builder API keys are issued to partners who integrate Junction via a
+builder code or a referral code. Two options:
+
+1. [Contact form](https://junction.exchange/contact?reason=builders) —
+   pick the "Builders" reason.
+2. Email [team@junction.exchange](mailto:team@junction.exchange) with your
+   referral code, product name, and expected traffic.
+
+Keys are opaque strings; rotate them by requesting a new one — old keys
+are revoked on rotation.
+
+## Rate limits
+
+All responses expose:
+
+| Header | Meaning |
+| --- | --- |
+| `X-RateLimit-Limit` | Requests allowed in the current window. |
+| `X-RateLimit-Remaining` | Requests left in the current window. |
+| `Retry-After` | Seconds to wait when the server returns `429`. |
+
+Authenticated requests bypass per-IP rate limits. Fair use is expected;
+for bursty dashboards prefer caching client-side for 30 – 120 seconds.
+
+## Which endpoints need the key?
+
+All of them:
+
+- `GET /referrals/{code}`
+- `GET /referrals/volume_30d/{code}`
+- `GET /referrals/{code}/user/{address}`
+- `GET /referrals/{code}/summary`
+
+Without a valid `x-api-key` you get a `401` with
+`{ "success": false, "error": "Invalid or missing API key", "code": "invalid_api_key" }`.
+
+## Test your key
+
+```bash
+curl -i https://services.junction.exchange/builders/referrals/ABC123 \
+  -H "x-api-key: $JXN_API_KEY"
+```
+
+A successful response is `HTTP/2 200` with `content-type: application/json`
+and a `{ "success": true, ... }` body.

builders/commissions.mdx

@@ -0,0 +1,62 @@
+---
+title: "Commissions"
+description: "How tier 1 / 2 / 3 commissions are computed."
+---
+
+## Tier model
+
+When a user signs up with your referral code, they become a **tier 1**
+referral. When one of *their* referrals joins, that person is a **tier 2**
+referral of yours, and so on down to **tier 3**.
+
+| Tier | Who they are | Default commission |
+| --- | --- | --- |
+| 1 | Users who signed up with **your** referral code. | **60%** of their builder fees |
+| 2 | Users who signed up with a tier-1 user's code. | **12%** |
+| 3 | Users who signed up with a tier-2 user's code. | **4%** |
+
+Rates are exposed in every response under `summary.commissionRates` so
+clients do not hard-code them. Junction operates individual partners with
+custom rates — the response always reflects the rates applied to your
+account.
+
+## Computation
+
+```
+commissionEarned = builderFees * (commissionRate / 100)
+```
+
+Where `builderFees` is the cumulative USD value of Hyperliquid builder fees
+paid by the referred user. Builder fees themselves default to:
+
+- **0.05%** of notional on Hyperliquid perps
+- **0.10%** of notional on Hyperliquid spot
+
+These are the Junction defaults; your contract may specify different
+rates.
+
+## Windows
+
+- `GET /referrals/{code}` returns **cumulative** (all-time) volume and
+  commission totals.
+- `GET /referrals/volume_30d/{code}` is shape-compatible with based.one's
+  30-day endpoint. Today it returns the cumulative snapshot with a
+  `period.days = 30` stamp; this is disclosed in `meta.notes`. The
+  **per-user** endpoint (`/user/{address}`) uses the Hyperliquid fills API
+  so its `days` window is always exact.
+
+## Data sources and freshness
+
+- Referral tree walk and cumulative totals come from Junction's referral
+  service.
+- Per-user asset breakdown and trade list come from Hyperliquid's
+  `userFillsByTime` info endpoint.
+- Tree snapshots are cached for 120 seconds on the Builders API Worker to
+  keep latency stable under burst.
+
+## Configurable rates
+
+Rates are exposed as environment variables on the Builders API Worker
+(`BUILDERS_TIER1_BPS`, `BUILDERS_TIER2_BPS`, `BUILDERS_TIER3_BPS`). Values
+are in basis points of builder fees (6000 = 60%). Contact the Junction
+team if you need a custom grid.

builders/endpoints/list-referrals.mdx

@@ -0,0 +1,109 @@
+---
+title: "List referrals"
+description: "All referrals (tier 1 / 2 / 3) under a code, cumulative."
+openapi: "GET /builders/referrals/{code}"
+---
+
+Returns every user who is a direct or indirect referral of `code`, with
+their cumulative trading volume, builder fees paid, and the commission you
+have earned. Sortable and filterable by tier.
+
+## Example request
+
+<CodeGroup>
+```bash curl
+curl "https://services.junction.exchange/builders/referrals/ABC123?sortBy=totalTraded&sortDirection=desc&tier=tier1" \
+  -H "x-api-key: $JXN_API_KEY"
+```
+
+```typescript TypeScript
+const qs = new URLSearchParams({
+  sortBy: 'totalTraded',
+  sortDirection: 'desc',
+  tier: 'tier1',
+})
+const res = await fetch(
+  `https://services.junction.exchange/builders/referrals/ABC123?${qs}`,
+  { headers: { 'x-api-key': process.env.JXN_API_KEY! } },
+)
+const body = await res.json()
+```
+
+```python Python
+import os, requests
+
+r = requests.get(
+    "https://services.junction.exchange/builders/referrals/ABC123",
+    params={"sortBy": "totalTraded", "sortDirection": "desc", "tier": "tier1"},
+    headers={"x-api-key": os.environ["JXN_API_KEY"]},
+    timeout=10,
+)
+r.raise_for_status()
+body = r.json()
+```
+</CodeGroup>
+
+## Example response
+
+```json
+{
+  "success": true,
+  "data": {
+    "referralCode": "ABC123",
+    "referralOwner": {
+      "address": "0x1234567890abcdef1234567890abcdef12345678",
+      "code": "ABC123"
+    },
+    "window": "cumulative",
+    "referrals": [
+      {
+        "address": "0xabcdef1234567890abcdef1234567890abcdef12",
+        "registrationDate": "2026-01-15T10:30:00.000Z",
+        "tier": 1,
+        "totalTraded": 15750.25,
+        "builderFees": 7.87,
+        "commissionEarned": 4.72,
+        "commissionRate": 60,
+        "referreeCode": "ABC123",
+        "swapXp": 120,
+        "referralXp": 35,
+        "totalXp": 155
+      }
+    ],
+    "summary": {
+      "tier1Count": 15,
+      "tier2Count": 8,
+      "tier3Count": 3,
+      "totalTier1Commission": 2450.75,
+      "totalTier2Commission": 245.30,
+      "totalTier3Commission": 48.15,
+      "totalVolume": 41200.12,
+      "totalCommission": 2744.20,
+      "commissionRates": { "tier1": 60, "tier2": 12, "tier3": 4 }
+    },
+    "meta": {
+      "source": "referral-service",
+      "notes": [
+        "Volume and commission figures are cumulative (all-time).",
+        "Commission rates are configurable and default to 60%/12%/4% of builder fees for tier 1/2/3."
+      ],
+      "generatedAt": "2026-04-18T12:34:56.000Z"
+    }
+  }
+}
+```
+
+## Query parameters
+
+| Name | Type | Default | Values |
+| --- | --- | --- | --- |
+| `sortBy` | string | `registrationDate` | `registrationDate`, `totalTraded`, `commissionEarned` |
+| `sortDirection` | string | `desc` | `asc`, `desc` |
+| `tier` | string | `all` | `all`, `tier1`, `tier2`, `tier3` |
+
+## See also
+
+- [30-day window](/builders/endpoints/volume-30d)
+- [User detail](/builders/endpoints/user-detail)
+- [Summary](/builders/endpoints/summary)
+- [Errors](/builders/errors)

builders/endpoints/summary.mdx

@@ -0,0 +1,52 @@
+---
+title: "Summary"
+description: "Lightweight aggregate-only view of a referral code, ideal for dashboard widgets."
+openapi: "GET /builders/referrals/{code}/summary"
+---
+
+Returns the `summary` block of
+[`GET /referrals/{code}`](/builders/endpoints/list-referrals) without the
+full referral list. Use it when you only need tier counts and totals —
+payload is orders of magnitude smaller, making it safe to poll every few
+seconds.
+
+## Example request
+
+```bash
+curl https://services.junction.exchange/builders/referrals/ABC123/summary \
+  -H "x-api-key: $JXN_API_KEY"
+```
+
+## Example response
+
+```json
+{
+  "success": true,
+  "data": {
+    "referralCode": "ABC123",
+    "referralOwner": { "address": "0x…", "code": "ABC123" },
+    "summary": {
+      "tier1Count": 15,
+      "tier2Count": 8,
+      "tier3Count": 3,
+      "totalTier1Commission": 2450.75,
+      "totalTier2Commission": 245.30,
+      "totalTier3Commission": 48.15,
+      "totalVolume": 41200.12,
+      "totalCommission": 2744.20,
+      "commissionRates": { "tier1": 60, "tier2": 12, "tier3": 4 }
+    },
+    "generatedAt": "2026-04-18T12:34:56.000Z"
+  }
+}
+```
+
+<Note>
+This endpoint is Junction-specific — based.one does not expose an
+equivalent shortcut.
+</Note>
+
+## See also
+
+- [List referrals](/builders/endpoints/list-referrals)
+- [Commissions](/builders/commissions)