Junction Builders API

Read-only REST API that lets partner builders and AI agents track their Junction referrals across Hyperliquid perps, spot, and cross-chain swaps. Shape-compatible with based.one's builder-referrals API, with an OpenAPI 3.1 spec and an MCP server card for agent discovery.

Base URL

https://services.junction.exchange/builders

Authentication

All endpoints require an API key in the x-api-key header. The legacy X-Junction-Api-Key header is also accepted. Request a key by emailing[email protected] or via thecontact form.

curl https://services.junction.exchange/builders/referrals/ABC123 \
  -H "x-api-key: YOUR_API_KEY"

Endpoints

  • GET /builders/referrals/:code - all referrals (tiers 1/2/3), cumulative.
  • GET /builders/referrals/volume_30d/:code - referrals over a rolling 30-day window.
  • GET /builders/referrals/:code/user/:address - detailed view of a single referred user, including Hyperliquid asset-level breakdown and trades.
  • GET /builders/referrals/:code/summary - aggregated summary only.

Response envelope

Every success response uses the same envelope:

{
  "success": true,
  "data": {
    "referralCode": "ABC123",
    "referralOwner": { "address": "0x...", "code": "ABC123" },
    "window": "cumulative",
    "referrals": [
      {
        "address": "0x...",
        "registrationDate": "2026-01-15T10:30:00.000Z",
        "tier": 1,
        "totalTraded": 15750.25,
        "builderFees": 7.87,
        "commissionEarned": 4.72,
        "commissionRate": 60
      }
    ],
    "summary": { "tier1Count": 1, "totalCommission": 4.72, ... },
    "meta": { "source": "referral-service", "notes": [...] }
  }
}

Errors follow the opposite shape:

{
  "success": false,
  "error": "User is not a referral under this referral code",
  "code": "user_not_referral"
}

Commission rates

  • Tier 1 (direct referrals): 60% of builder fees.
  • Tier 2 (sub-referrals): 12%.
  • Tier 3 (sub-sub-referrals): 4%.

Rates are configurable per deployment. Builder fees themselves default to about 0.025% on Hyperliquid perps and spot (see the docs).

Compatibility with based.one

CapabilityJunctionbased.oneNotes
Path convention/builders/referrals/:code/api/builders/referrals/[code]Compatible shape and query params (sortBy, sortDirection, tier).
Authenticationx-api-key headerx-api-key headerIdentical.
Commission tiers60% / 12% / 4% (configurable)60% / 12% / 4%Tune per partner via env.
Rolling 30d window/builders/referrals/volume_30d/:code/api/builders/referrals/volume_30d/[code]Returns cumulative until period-scoped aggregation ships (documented in meta.notes).
Per-user detail/builders/referrals/:code/user/:address/api/builders/referrals/[code]/user/[address]Junction adds real-time Hyperliquid `userFillsByTime` breakdown.
Summary-only endpoint/builders/referrals/:code/summary-Junction-only, cheap for dashboards.
OpenAPI spec/openapi.json (tag: builders)-Junction-only.
MCP server toolsbuilders_list_referrals, builders_referral_user, ...-Junction-only.
Multi-product scopeHyperliquid perps + LiFi swapsHyperliquid onlyJunction tracks cross-chain swap volume too.

Integrate with AI agents

Rate limits

Same X-RateLimit-* and Retry-After headers as the rest of the Junction API. With a valid x-api-key, IP-based rate limits are bypassed; fair use is expected.

Contact