Referrals

The referral API lets you create referral codes, attach a trader to a referrer, read earnings, and claim rewards. Nothing here requires an API key, and nothing requires your users to send a transaction except the claim itself. Creating a code and applying a code are EIP-712 signatures. The signature is the only authority. Per-endpoint schemas live under API Reference → Referrals. This page covers what the schemas cannot tell you: how to sign, what breaks, and what to ask us for.

This is the self-serve referral API served by backend-global.It is not the on-chain program documented in GNSReferrals and ReferralsUtils, and it is not the older KOL-slug system behind /api/referrals/links/…. Three different things share the word “referral”. Do not mix them.

Check availability first

The API is enabled per deployment. Probe it at startup:

curl https://backend-global.gains.trade/api/referrals/config

{
  "result": {
    "chainId": 42161,
    "distributor": "0x…",
    "l1RateBps": 1000,
    "l2RateBps": 500
  }
}

Anything other than 200 means referrals are unavailable on that host. Disable the feature in your UI rather than falling back to stored values.

GET /api/referrals/config is the only valid readiness check. The read endpoints return 200 with zeroes whether or not the system is running, so they tell you nothing.

chainId and distributor come from this endpoint at runtime by design. A distributor redeploy is meant to be a configuration change on our side, not a client rebuild on yours. Any address you pin elsewhere will eventually be wrong.

Three rules that break integrations

A code must be applied before the trader's first trade

Once a wallet has traded on any chain covered by the program, POST /api/referrals/bind returns 409 AlreadyTraded and no referrer can ever be attached. This is permanent.Bind at onboarding, before the wallet reaches the exchange. Binding shortly after the first trade earns nothing.There is no endpoint that answers “is this wallet still bindable”. Derive it from trading history, and ask us for the exact list of chain ids in the attribution window so your check covers the same set as ours. Cover fewer chains than we do and you will show an eligible state that the API then refuses.Treat any chain you cannot resolve as not eligible and disable the bind UI. Failing open here produces a link that is accepted and then earns nothing.

Never hardcode the distributor address or the chain id

Read both from /config on every session.A stale chainId or distributor silently changes the EIP-712 domain. The recovered signer becomes a different address, so the failure surfaces as 401 unauthorized-signer rather than as anything that mentions the domain. If you see that error and your subject really is the signer, re-fetch /config before looking anywhere else.

Neither `claimableMicroUsdc` nor `unpaidMicroUsdc` is claimable

Despite the names:

claimableMicroUsdc is lifetime gross earnings. It ignores everything already paid out.
unpaidMicroUsdc is lifetime minus already claimed. It still includes earnings that no published batch carries yet, which the contract will refuse to pay.

Gate the claim on a 200 from /proof/{address} and a positive delta. See Claiming.

Signing

Both write operations share one EIP-712 domain.

const domain = {
  name: "GainsReferral",
  version: "1",
  chainId: config.chainId,           // from /api/referrals/config
  verifyingContract: config.distributor,
};

There is no salt, and you must not add EIP712Domain to the types object.

Types

Field order is part of the hash. Do not reorder.

const RegisterCode = {
  RegisterCode: [
    { name: "owner", type: "address" },
    { name: "code", type: "string" },
    { name: "nonce", type: "uint256" },
    { name: "validUntil", type: "uint64" },
  ],
};

const BindCode = {
  BindCode: [
    { name: "referee", type: "address" },
    { name: "code", type: "string" },
    { name: "nonce", type: "uint256" },
    { name: "validUntil", type: "uint64" },
  ],
};

The structs differ only in the first field name and are not interchangeable.

Message fields

Field	Type	How to build it
`owner` / `referee`	`address`	The signing wallet. Anything else returns `401`.
`code`	`string`	Must match `/^[a-z0-9_]{1,31}$/`. Normalize with `trim().toLowerCase()` before signing — we reject, we do not normalize.
`nonce`	`uint256`	`Date.now()`, in milliseconds. Must be strictly greater than your last accepted nonce.
`validUntil`	`uint64`	Unix seconds. Use `now + 600`.

nonce is milliseconds and validUntil is seconds. Swapping them gives 400 expiry-too-far or 409 BadNonce.

The nonce high-water mark is per signer and shared across both message kinds. A bind sent after a register must carry a strictly larger nonce, and you must never have two writes in flight for the same wallet. validUntil is checked against our clock: it must be in the future and at most 900 seconds ahead. Sign immediately before submitting rather than pre-signing and queueing.

Smart-contract wallets are not supported. Signatures are verified by ECDSA recovery only, with no EIP-1271 path, so the recovered address must be an EOA.

Sending it

Both transports are equivalent; the signature is the only thing that matters.

const res = await fetch(`${base}/api/referrals/code`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ message: { kind: "register_code", ...message }, signature }),
});

// base64url, unpadded
const encoded = btoa(JSON.stringify({ kind: "register_code", ...message }))
  .replace(/\+/g, "-")
  .replace(/\//g, "_")
  .replace(/=+$/, "");

const res = await fetch(
  `${base}/api/referrals/code?message=${encodeURIComponent(encoded)}&signature=${encodeURIComponent(signature)}`,
  { method: "GET" }
);

Use bind_code and /api/referrals/bind to bind. kind must be present and must match the path, but it is transport metadata only and is not part of the signed struct.

The GET transport exists so the request stays a CORS simple request and survives edge rules that block POST. If you use it, send no custom headers, or you reintroduce the preflight you were avoiding.

Only 201 is success.

Worked example

import { createWalletClient, custom } from "viem";

const cfg = await fetch(`${base}/api/referrals/config`)
  .then((r) => r.json())
  .then((j) => j.result);

const code = raw.trim().toLowerCase();
if (!/^[a-z0-9_]{1,31}$/.test(code)) throw new Error("invalid code");

const message = {
  referee: account,
  code,
  nonce: Date.now(),
  validUntil: Math.floor(Date.now() / 1000) + 600,
};

const signature = await wallet.signTypedData({
  account,
  domain: {
    name: "GainsReferral",
    version: "1",
    chainId: cfg.chainId,
    verifyingContract: cfg.distributor,
  },
  types: {
    BindCode: [
      { name: "referee", type: "address" },
      { name: "code", type: "string" },
      { name: "nonce", type: "uint256" },
      { name: "validUntil", type: "uint64" },
    ],
  },
  primaryType: "BindCode",
  message,
});

const res = await fetch(`${base}/api/referrals/bind`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ message: { kind: "bind_code", ...message }, signature }),
});

Write errors

Status	Error	Meaning	What to do
`400`	prose	Malformed field. These strings are not stable — do not switch on them.	Fix the client.
`400`	`expired`	`validUntil` is in the past.	Re-sign. Check your clock.
`400`	`expiry-too-far`	More than 900 seconds ahead.	Use `now + 600`.
`400`	`malformed`	Signature could not be recovered.	Check encoding, domain and types.
`401`	`unauthorized-signer`	Signer is not the subject. Usually a stale `chainId` or `distributor`.	Re-fetch `/config`.
`403`	`origin not allowed`	Your `Origin` is not allowlisted.	Not retryable. Ask us to add it.
`409`	`AlreadyTraded`	The wallet has traded. Bind only.	Terminal.
`409`	`AlreadyBound`	Already has a referrer.	Terminal.
`409`	`CodeUnknown`	Code is not registered.	Register first, or check spelling.
`409`	`CodeTaken`, `OwnerHasCode`, `CodeReserved`	Register conflicts.	Choose another code.
`409`	`SelfReferral`, `Cycle`	Not permitted.	Terminal.
`409`	`BadNonce`	Nonce not strictly greater.	See below.
`429`	`too many requests…`	30 writes per minute.	Back off; read the `RateLimit-*` headers.
`503`	`signed referral writes are disabled`	Not enabled on this host.	Disable the feature.
`503`	`TradeHistoryUnavailable`	We could not check trade history, so we refused.	Retryable.
`500`	`failed to apply signed write`	State is indeterminate.	Re-read before retrying.

A 409 does not mean the write failed.If a request times out and you retry, BadNonce means the original write already landed. So do AlreadyBound and OwnerHasCode when you retry with a fresh nonce.After any non-201, re-read /binding/{address} or /address/{address}/code before deciding what happened.

Reading

Every response is wrapped in {"result": …}; errors are {"error": "…"}. Reads are not rate limited and CORS is open, but there is no server-side cache, so poll conservatively. Accruals move at most every 30 seconds, and the claimable amount changes roughly once a day.

Units

lifetimeUsd and claimableMicroUsdc are the same quantity in different units. Do not add them, and do not divide lifetimeUsd by 1e6.

Micro-USDC integers as strings — divide by 1e6, parse with BigInt: claimableMicroUsdc, settledMicroUsdc, unpaidMicroUsdc, cumulativeMicroUsdc, amountMicroUsdc.
Decimal USD strings, already human-scaled: lifetimeUsd, l1Usd, l2Usd, cashbackUsd, accruedUsd, earnedUsd, volume30dUsd.
Basis points as integers, 10000 = 100%: l1RateBps, l2RateBps, cashbackBps.
Unix seconds: boundAt, nullable. YYYY-MM-DD UTC: day.

What to display

Label	Value
Ready to claim	`proof.cumulativeMicroUsdc − rewards.settledMicroUsdc`, floored at 0
Lifetime earned	`rewards.claimableMicroUsdc` ÷ 1e6
Claimed	`rewards.settledMicroUsdc` ÷ 1e6
Pending	`rewards.unpaidMicroUsdc` − ready to claim
Rate	`effectiveRate.l1RateBps / 100` %

effectiveRate reports the standard programme rate. A negotiated partner rate is applied to actual earnings but is not reflected in that field today, so do not present it as a contractual rate.

Claiming

Fetch the proof

GET /api/referrals/proof/{address} returns day, cumulativeMicroUsdc and proof.A 404 nothing claimable is a normal state, not an error.

Compute the payout

The contract pays cumulativeAmount − claimed[account]. Read it exactly with the claimableAmount(account, cumulativeAmount) view, or approximate it as cumulativeMicroUsdc − settledMicroUsdc.Prefer the on-chain view for the amount next to the button: settledMicroUsdc is only as fresh as our indexer, so it can over-report just after a claim.

Send the transaction

Call claim on config.distributor, on config.chainId. Pass cumulativeMicroUsdc unchanged — the contract computes the delta itself.

{
  "type": "function",
  "name": "claim",
  "stateMutability": "nonpayable",
  "inputs": [
    { "name": "account", "type": "address" },
    { "name": "cumulativeAmount", "type": "uint256" },
    { "name": "proof", "type": "bytes32[]" }
  ],
  "outputs": []
}

Payment is native USDC on the hub chain, 6 decimals. The call is permissionless: anyone can submit it and funds always go to account, so a relayer can pay the gas.

Re-fetch the proof immediately before sending. Proofs go stale when a new batch is published, and a stale one reverts InvalidProof. Handle NothingToClaim, InvalidProof and IsPaused.

Referral links

To match the gTrade app:


Query parameter	`ref`
Cookie name	`referral_v2`
Cookie value	the code, lowercased
Lifetime	604800 seconds (7 days)
Precedence	`?ref=` wins over the cookie

Validate against /^[a-z0-9_]{1,31}$/ before storing.

The by and referredBy parameters and the referral cookie belong to the older KOL-link system and are unrelated to this API.

Before you go live

Ask us for the following. The first three are blocking.

Your exact origins added to the write allowlist. Matching is exact string comparison on the Origin header: no wildcards, no subdomain matching. Without it, every write returns 403. Tell us whether you call from a browser or server-side, because a request with no Origin header is also rejected.
Confirmation that signed writes are enabled on the environment you target.
Confirmation that accrual indexing is enabled. If it is off, writes succeed and reads return zeroes indefinitely, with no HTTP signal to detect it.
The API base host for each environment.
The chain ids in the attribution window, so your eligibility check matches ours.
Reserved code namespaces, if you want branded codes protected from squatting.
Rate-limit headroom, if your traffic egresses from a small set of IPs. The limit is 30 writes per minute per IP, shared across both write endpoints and both transports.

Integration checklist

Probe /config. Non-200 disables the feature.
Capture ?ref=, validate it, store it in referral_v2 for 7 days.
Resolve the code with /code/{code}/address. A null owner means do not attempt a bind.
Check eligibility across every attribution chain. Treat anything unresolved as not eligible.
Check /binding/{address}. Non-null means already bound.
Sign with values from /config, one write in flight per wallet.
On 201 you are done. On 409 or 500, re-read state before concluding anything.
Offer the claim only on a 200 proof with a positive delta, with the wallet on config.chainId.

API Reference

Integrators

Technical Reference

Check availability first

Three rules that break integrations

Signing

Types

Message fields

Sending it

Worked example

Write errors

Reading

Units

What to display

Claiming

Referral links

Before you go live

Integration checklist

​Check availability first

​Three rules that break integrations

​Signing

​Types

​Message fields

​Sending it

​Worked example

​Write errors

​Reading

​Units

​What to display

​Claiming

​Referral links

​Before you go live

​Integration checklist

Check availability first

Three rules that break integrations

Signing

Types

Message fields

Sending it

Worked example

Write errors

Reading

Units

What to display

Claiming

Referral links

Before you go live

Integration checklist