> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tradeatlas.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Referral Integration

> Contract and API integration reference for referral attribution and rewards.

## Contracts (Arbitrum)

Atlas frontend reads these addresses from environment-backed network config:

* `NEXT_PUBLIC_ARBITRUM_REFERRAL_REGISTRY_ADDRESS`
* `NEXT_PUBLIC_ARBITRUM_DEPOSIT_ROUTER_ADDRESS`
* `NEXT_PUBLIC_ARBITRUM_REFERRAL_REWARD_POOL_ADDRESS`

See `apps/web/src/config/arbitrum.ts` for the current wiring source of truth.

## Key contract functions

### ReferralRegistry

* `registerCode(bytes32 _code)`
* `setTraderReferralCode(address _vault, address _trader, bytes32 _code)`
* `getTraderReferralInfo(address _vault, address _trader) returns (bytes32 code, address referrer)`
* `codeOwners(bytes32) returns (address)`
* `getAffiliateCodes(address _affiliate) returns (bytes32[])`
* `freezeCode(bytes32 _code)`
* `unfreezeCode(bytes32 _code)`

### DepositRouter

* `depositWithReferral(address _vault, address _depositAsset, uint256 _amount, bytes32 _referralCode, uint256 _expectedAmountReceived)`
* `setMinQualifyingDeposit(uint256 _nextThreshold)`

### ReferralRewardPool

* `accrueReward(address _referrer, uint256 _amount)`
* `getClaimableInfo(address _referrer) returns (uint256 claimable, uint256 cooldownEndsAt, uint256 cooldownRemaining)`
* `claim()`

## API endpoints

Frontend proxy routes:

* `GET /api/referrals/:address`
* `GET /api/referrals/vault/:vault`
* `GET /api/referrals/stats`

Upstream (kairon-api/atlas-api) additionally exposes:

* `GET /api/referrals/vault/:vault/allocation`

## Events

### ReferralRegistry

* `TraderReferralCodeSet(address indexed vault, address indexed trader, bytes32 indexed code, address referrer)`
* `CodeFrozen(bytes32 indexed code)`
* `CodeUnfrozen(bytes32 indexed code)`

### DepositRouter

* `ReferredDeposit(address indexed vault, address indexed trader, bytes32 indexed referralCode, uint256 amount, uint256 shares)`
* `MinQualifyingDepositUpdated(uint256 previousThreshold, uint256 nextThreshold)`

### ReferralRewardPool

* `RewardAccrued(address indexed referrer, uint256 amount, uint256 totalAccrued)`
* `RewardClaimed(address indexed referrer, uint256 amount)`

## Integration notes

* Referral code input should be normalized to bytes32.
* Binding is first-touch and immutable per `(vault, trader)`.
* Deposits below the qualifying threshold do not bind referrals.
* Frozen codes cannot create new bindings.
* Reward claims are gated by cooldown.