Get Supply Referrals

Query supply referral objects. Supply referrals track referral relationships for liquidity provision, enabling referral fee distribution from the protocol spread. This endpoint allows you to look up referrals by ID or list referrals with filters.

Endpoints

By ID

GET /deepbook-margin/supply-referrals/{supplyReferralId}

Returns a single supply referral by its ID.

List Referrals

GET /deepbook-margin/supply-referrals

Returns supply referrals with optional filters.

Use Cases

• Referral Tracking — Track referral relationships for fee distribution
• Referral Dashboard — Display referral activity and earnings
• Partner Analytics — Analyze referral program performance
• Fee Distribution — Verify referral eligibility for fee claims

Parameters

Path Parameters (By ID endpoint)

Parameter	Type	Required	Description
supplyReferralId	string	Yes	Supply referral ID

Query Parameters (List endpoint)

Parameter	Type	Required	Default	Description
owner	string	No	—	Filter by owner address
marginPoolId	string	No	—	Filter by margin pool ID
page	number	No	0	Page number (starts from 0)
perPage	number	No	10	Items per page (max 50)
api-key	string	Yes	—	Your Surflux API key

Response

Single Supply Referral (By ID)

Field	Type	Description
supply_referral_id	string	Unique supply referral ID
margin_pool_id	string	Associated margin pool
owner	string	Referral owner address
onchain_timestamp	number	On-chain timestamp in milliseconds
checkpoint_id	number	Checkpoint when created/updated
digest	string	Transaction digest
created_at	string	ISO timestamp of creation
updated_at	string	ISO timestamp of last update

Example Response (By ID)

{
  "supply_referral_id": "0x789abc123def456789abc123def456789abc123def456789abc123def456789a",
  "margin_pool_id": "0x4405b50d791fd3346754e8171aaab6bc2ed26c2c46efdd033c14b30ae507ac33",
  "owner": "0xb117b12facd947cabb3d17d68a67b3d8d6865280edb0644cb4d25a9d86646966",
  "onchain_timestamp": 1758629823805,
  "checkpoint_id": 192054000,
  "digest": "XyZaBcDeFgHiJkLmNoPqRsTuVwXyZaBcDeFgHiJkLmNo",
  "created_at": "2025-01-15T10:30:00.000Z",
  "updated_at": "2025-01-26T14:22:00.000Z"
}

Paginated Response (List)

{
  "items": [
    {
      "supply_referral_id": "0x789abc123def456789abc123def456789abc123def456789abc123def456789a",
      "margin_pool_id": "0x4405b50d791fd3346754e8171aaab6bc2ed26c2c46efdd033c14b30ae507ac33",
      "owner": "0xb117b12facd947cabb3d17d68a67b3d8d6865280edb0644cb4d25a9d86646966",
      "onchain_timestamp": 1758629823805,
      "checkpoint_id": 192054000,
      "digest": "XyZaBcDeFgHiJkLmNoPqRsTuVwXyZaBcDeFgHiJkLmNo",
      "created_at": "2025-01-15T10:30:00.000Z",
      "updated_at": "2025-01-26T14:22:00.000Z"
    }
  ],
  "isLastPage": true,
  "currentPage": 0,
  "perPage": 10
}