--- title: "Get an affiliate's accrued commission" method: GET path: "/api/v1/referrals/commissions" tags: ["Referrals"] --- # Get an affiliate's accrued commission `GET /api/v1/referrals/commissions` ## Request - Base URL: `https://api.mainnet.aptoslabs.com/decibel` - URL: `https://api.mainnet.aptoslabs.com/decibel/api/v1/referrals/commissions` - Auth: HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) What the affiliate has earned: today, since Monday, and over all time, plus a daily breakdown carrying the tier and any anti-farming penalty that was in force each day. This is not what is claimable. Claimable commission is an on-chain campaign allocation and comes from the campaigns endpoints; this is the off-chain ledger of what is owed. ## Query parameters - `affiliate_account` string, required - `days` integer ## Response `200` The affiliate's accrued commission - AffiliateCommissions: An affiliate's accrued commission: today, the running week, and lifetime. Distinct from what is *claimable*, which lives on chain in `campaign_claims`. This endpoint answers "what have I earned"; the chain answers "what can I take". Keeping them apart is what makes "accrued but not yet swept" and "accrued but forfeited" answerable without trusting either side alone. - `accrued_this_week_usd` number, double, required: Accrued since Monday. This is what the weekly sweep will pay, or forfeit. - `accrued_today_usd` number, double, required: Accrued so far today. Provisional until the week is swept. - `current_nuv_usd` number, double, required: The trailing-window NUV that rung was derived from. - `current_tier` string, required: The rung in force, from the most recent accrual. `bronze` when there is no history: an affiliate whose network brings nobody new still earns, at the lowest rate. - `days` AffiliateCommissionDay[], required: Daily breakdown, oldest first. Days with no activity are absent, not zero-filled. - `accrued_usd` number, double, required: Commission accrued that day, after any anti-farming penalty - `basis_l1_usd` number, double, required: Fee basis from direct referrals - `basis_l2_usd` number, double, required: Fee basis from second-level referrals - `date` string, required: UTC date, `YYYY-MM-DD` - `penalty_multiplier` number, double, required: 1.0 when unpenalised. Below that, an anti-farming override was in force. The multiplier is here and the *reason* is deliberately not. The reason string is the detection's own working notes — `SYBIL_REFERRAL_FARM_ORCHESTRATOR: 5-member R2 cluster of 89 activated, flag_ratio 0.20` — and serving it told anyone who asked both that a wallet was flagged and exactly what tripped it, which is how an anti-abuse system stops working. It also labelled an address as a fraud in a public response. An affiliate needs to know their commission was reduced, which the multiplier says; why it was reduced is a conversation with support, not a field. - `rate_l1` number, double, required: The L1 share that applied that day, as a fraction — 0.25 for bronze. Sent rather than left for the client to derive from `tier`, which would put a second copy of the rate table in the frontend. The server stamped these; it should report them. A caller splitting commission by level needs the day's own rate because the tier moves inside a 30-day window. - `rate_l2` number, double, required: The L2 override share that applied that day, as a fraction — 0.10 for bronze. - `tier` string, required: `bronze` | `silver` | `gold`, as stamped that day - `lifetime_accrued_usd` number, double, required: Accrued over all time, including weeks already paid. - `meets_minimum` boolean, required: Whether the running week currently clears the floor - `minimum_payout_usd` number, double, required: The floor a week must clear to be paid at all - `mode` string, required: `points` | `usd`: the reward mode **in force today** — the affiliate's most recent election whose `effective_from` has already arrived. Read from the election ledger, not from the latest accrual, so it flips the instant an election takes effect rather than lagging until the next accrual is written. Absent history reads `points`, the status quo for every affiliate today. - `nuv_window_days` integer, required: Days in the NUV window. Sent so the caller can label it without hardcoding 30. - `pending_effective_from` string, required: The Monday `pending_mode` starts, `YYYY-MM-DD`, or empty when nothing is pending. - `pending_mode` string, required: A recorded election that has not taken effect yet, or empty. Published because `mode` alone cannot express it. An election lands on a future Monday, so between signing it and that day the affiliate is still earning the old currency and the ledger still stamps it — a screen reading only `mode` shows no trace of a decision that has already been made, irreversibly. The affiliate concludes it failed and tries again. - `previous_week_campaign_id` integer, required: On-chain campaign carrying the previous week, or 0 when it is not on chain yet. A non-zero id means the money is claimable through the campaigns endpoints, not here. - `previous_week_status` string, required: What the sweep decided about that week: `paid`, `forfeited`, `withheld`, or empty when it has not been swept yet. Empty is the common case early in a week. - `previous_week_usd` number, double, required: Accrued over the week before this one. Non-zero for the two or three days between a week closing and its sweep paying out — the window in which the running week reads near zero while real money is still owed. - `progress_to_minimum` number, double, required: 0.0–1.0 progress toward the floor, for a progress indicator - `tiers` CommissionTier[], required: The whole ladder, highest rung first. Static config, published so no client keeps a second copy of the rate table. - `nuv_threshold_usd` number, double, required: Trailing-window NUV, in USD, at or above which this rung applies. Inclusive. - `rate_l1` number, double, required: Share of the direct-referral fee basis, as a fraction — 0.25 for bronze. - `rate_l2` number, double, required: Share of the second-level fee basis, as a fraction — 0.10 for bronze. - `tier` string, required: `bronze` | `silver` | `gold` - `week_start_date` string, required: Monday of the running week, `YYYY-MM-DD` - `weeks` AffiliateCommissionWeek[], required: Weekly history, newest first: what each week accrued and what the sweep decided. Separate from `days` because the two answer different questions — `days` is how the figure was built, `weeks` is what happened to it. - `accrued_usd` number, double, required: What the seven days accrued, from the ledger. - `allocated_usd` number, double, required: What the sweep actually allocated. Zero on a forfeited or unswept week, which is why it is reported alongside `accrued_usd` rather than instead of it. - `campaign_id` integer, required: On-chain campaign, or 0 when the allocation has not been pushed to one yet. - `minimum_usd` number, double, required: The floor in force that week. Stored per sweep because it is program config that can change, and a past week must be explainable under the rule it was judged by. - `reason` string, required: `below_minimum` | `flagged`, or empty. The answer to "why was I not paid?". - `status` string, required: `paid` | `forfeited` | `withheld`, or empty when the sweep has not run. - `week_start_date` string, required: Monday of the week, `YYYY-MM-DD` ## Other responses - `400`: Invalid address - `500`: Database error ## Changes - **2026-11-03** `bb095628df0a`: 1 info - endpoint added [Operation history](https://skmtc.dev/decibel/apis/decibel-trading-api/changes/api/v1/referrals/commissions/get.md) --- [API](https://skmtc.dev/decibel/apis/decibel-trading-api.md) - [All operations](https://skmtc.dev/decibel/apis/decibel-trading-api/llms.txt) - [OpenAPI document](https://skmtc.dev/decibel/apis/decibel-trading-api/revisions/ee1bcb5822bd?raw)