Claim Referral

Claim accrued referral commissions for the authenticated wallet. The referrer wallet is derived from the EIP-712 signature — no explicit address field is required or accepted.

Unlike most trade endpoints, claimReferral does not use a top-level { v, r, s } signature or nonce. The EIP-712 signature is passed as a 0x-prefixed hex string inside params.

Endpoint

POST https://papi.synthetix.io/v1/trade

Request

Request Format

{
  "params": {
    "action": "claimReferral",
    "expiresAfter": 1704067500,
    "signature": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef12"
  }
}

Request Parameters

Parameter	Type	Required	Description
`params`	object	Yes	Request parameters wrapper
`params.action`	string	Yes	Must be `"claimReferral"`
`params.expiresAfter`	integer	Yes	Signature expiry as a Unix timestamp in seconds; must be in the future and within 5 minutes of the current server time
`params.signature`	string	Yes	`0x`-prefixed hex encoding of the EIP-712 signature over the `ClaimReferralPayout` typed data

:::info Owner key required claimReferral must be signed with the wallet owner key. The recovered signer is used as the canonical referrer identity — signing with a delegate key would attempt to claim on behalf of the delegate address, not the account owner. :::

Response

Success Response

{
  "status": "ok",
  "response": {
    "payoutId": "4892034750123456789",
    "amountUsdt": "125.50",
    "status": "confirmed"
  },
  "request_id": "5ccf215d37e3ae6d"
}

Response Fields

Field	Type	Description
`payoutId`	string	Unique payout identifier, serialized as a decimal string to preserve precision for JavaScript clients
`amountUsdt`	string	Amount credited in USDT, as a decimal string (for example `"125.50"`)
`status`	string	Payout status — `"confirmed"` on a successful claim

Authentication

EIP-712 Signature

claimReferral uses a dedicated EIP-712 primary type ClaimReferralPayout. The signed payload contains only expiresAfter. The signer of the signature is the wallet whose commissions are being claimed.

ClaimReferralPayout Type Definition

const ClaimReferralPayoutTypes = {
  ClaimReferralPayout: [
    { name: "expiresAfter", type: "uint256" }
  ]
}

Example Typed Data for ClaimReferralPayout

{
  "types": {
    "EIP712Domain": [
      { "name": "name", "type": "string" },
      { "name": "version", "type": "string" },
      { "name": "chainId", "type": "uint256" },
      { "name": "verifyingContract", "type": "address" }
    ],
    "ClaimReferralPayout": [
      { "name": "expiresAfter", "type": "uint256" }
    ]
  },
  "primaryType": "ClaimReferralPayout",
  "domain": {
    "name": "Synthetix",
    "version": "1",
    "chainId": 1,
    "verifyingContract": "0x0000000000000000000000000000000000000000"
  },
  "message": {
    "expiresAfter": "1704067500"
  }
}

Important notes:

Serialize the signed payload to params.signature as a single 0x-prefixed hex string (standard Ethereum signature bytes), not as a top-level { v, r, s } object
expiresAfter is encoded as a decimal string in the EIP-712 message (matching the uint256 type encoding)
expiresAfter must be a future Unix second timestamp and no more than 5 minutes ahead of current server time
There is no nonce field — replay protection relies on the 5-minute validity window and a per-referrer 24-hour claim cooldown enforced server-side
A leaked signature can be replayed at most once before the 24-hour cooldown blocks further claims
Use the chainId for your target environment. See Environments for the domain configuration used on mainnet and testnet

For general EIP-712 background, see EIP-712 Signing.

Validation Rules

expiresAfter must be a positive integer representing a future Unix timestamp in seconds
expiresAfter must be within 5 minutes of the current server time
params.signature must be a valid EIP-712 signature over the ClaimReferralPayout typed data, passed as a 0x-prefixed hex string inside params
Wallet must have a claimable balance above the minimum payout threshold
A 24-hour cooldown applies between successful claims per referrer wallet

Error Handling

Error Code	Description	Retryable
`UNAUTHORIZED`	EIP-712 signature validation failed	No
`VALIDATION_ERROR`	Request validation failed	No
`MISSING_REQUIRED_FIELD`	Required field is missing	No
`INVALID_FORMAT`	Field format is invalid	No
`INVALID_VALUE`	Invalid parameter value	No
`RATE_LIMIT_EXCEEDED`	Too many requests in time window	Yes
`INSUFFICIENT_MARGIN`	Not enough margin for trade	No
`ORDER_NOT_FOUND`	Order does not exist	No
`OPERATION_TIMEOUT`	Operation timed out	Yes

Error	HTTP Status	Description
`expiresAfter is required and must be a future unix-second timestamp`	400	`expiresAfter` is missing, zero, or in the past
`signature is required`	400	`params.signature` is missing or blank
`signature verification failed`	401	Signature is invalid or `expiresAfter` exceeds the 5-minute validity window
No claimable balance / below minimum	400	Wallet has no accrued commissions or the balance is below the minimum payout threshold
Claim cooldown active	429	A claim was already made within the last 24 hours; see `nextEligibleAt` in the error response for the next eligible claim time

Cooldown Response

When a claim is rejected due to the cooldown period, the response includes a nextEligibleAt field in the error details:

{
  "status": "error",
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "claim cooldown active",
    "details": {
      "nextEligibleAt": "2026-06-05T12:00:00Z"
    }
  },
  "request_id": "5ccf215d37e3ae6d"
}

Apply Referral — Attribute a referral code to a wallet
Get Referral — View referral dashboard, claimable balance, and referee list