> ## Documentation Index > Fetch the complete documentation index at: https://docs.0xmonaco.com/llms.txt > Use this file to discover all available pages before exploring further. # Get your referral downline and earnings > Read your own downline earnings (self-scoped). Return who the authenticated caller earns from and how much: an earnings-by-source breakdown aggregated from the caller's reward rows across all three reward levels (L1/L2/L3), their L1 direct-referee roster (including referees who have not traded yet), and a per-level earnings summary. Self-scoped — identity comes only from the session, never a path id. Every source and referee is identified by their public wallet address, never an internal id. ## OpenAPI ````yaml /proto-openapi/api/openapi.yaml get /api/v1/pitpass/referrals/me/downline openapi: 3.0.3 info: title: Monaco Protocol API description: REST API for the Monaco Protocol hybrid CLOB exchange. version: 1.0.0 servers: - url: https://staging.apimonaco.xyz description: Staging server (Testnet) security: [] tags: - name: AccountsService - name: ApplicationsService - name: AuthService - name: BuildercodeRewardsService - name: DelegatedAgentsService - name: FaucetService - name: FeesService - name: HealthService - name: ManagedMarketsService description: |- Wallet-authenticated maker assignments. The signed session must match both configured maker user and application. Owner IDs are process fences, never auth. Only wallet sessions are supported; delegated-agent sessions receive 403. - name: MarginAccountsService description: |- Current public isolated-margin semantics: - a user has one parent margin account per application scope - opening orders create or reuse isolated position buckets under that parent - parent account creation is handled internally by margin workflows - name: MarketService - name: OrderbookService - name: OrdersService - name: PositionsService description: |- Current public isolated-margin semantics: - positions link to a parent margin account and, when applicable, a bucket id - opening orders create or reuse isolated position buckets under the parent - users can open another isolated position by reusing the parent account with a different market bucket - name: PulseService - name: SweeperService - name: TraderCodeService - name: TradesService - name: WhitelistService - name: WithdrawalsService paths: /api/v1/pitpass/referrals/me/downline: get: tags: - TraderCodeService - PitPass summary: Get your referral downline and earnings description: |- Read your own downline earnings (self-scoped). Return who the authenticated caller earns from and how much: an earnings-by-source breakdown aggregated from the caller's reward rows across all three reward levels (L1/L2/L3), their L1 direct-referee roster (including referees who have not traded yet), and a per-level earnings summary. Self-scoped — identity comes only from the session, never a path id. Every source and referee is identified by their public wallet address, never an internal id. operationId: get_my_referral_downline responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/GetMyReferralDownlineResponse' '401': description: Authentication required '429': description: >- Read rate limit exceeded — every authenticated read draws one request from the account's read budget; retry after the interval in details.retryAfter '500': description: Internal server error security: - monacoSignature: [] - monacoHttpSignature: [] components: schemas: GetMyReferralDownlineResponse: type: object properties: earningsBySource: type: array items: $ref: '#/components/schemas/ReferralEarningsSource' description: >- One row per (source trader, level, token) the caller earns from, across all three reward levels. Comes straight from the caller's reward rows — no tree walk. nullable: true directReferees: type: array items: $ref: '#/components/schemas/ReferralDirectReferee' description: >- The caller's direct (L1) referees, newest first, including referees who have not traded yet (0 earned). Bounded to the most recent 500 EFFECTIVE referees (after per-wallet dedupe and the winning-edge filter). The earnings views (`earnings_by_source` and the summary) are unbounded and count every level, so a caller past the roster cap still sees their full earnings; only this roster listing is capped. nullable: true summary: allOf: - $ref: '#/components/schemas/ReferralEarningsSummary' description: Total earned broken down by level (L1/L2/L3). nullable: true ReferralEarningsSource: type: object properties: source: example: '0x0000000000000000000000000000000000000002' type: string description: >- Public wallet address of the trader (taker) the caller earns from. Never an internal id. nullable: true level: example: 1 type: integer description: >- Referral level the caller earns from this source at: 1 (direct), 2, or 3. format: int32 nullable: true totalEarned: example: '900000' type: string description: >- Total earned from this source at this level and token, in RAW atomic units. nullable: true token: example: '0x0000000000000000000000000000000000000002' type: string description: Reward token contract address (0x-prefixed). nullable: true sourceDisplay: example: cooltrader123 type: string description: >- Human-facing name for the source: their custom TraderCode handle when they have claimed one, otherwise the wallet address (same as `source`). Render this instead of raw hex. nullable: true description: |- One aggregated earnings row per (source trader, level, token) the caller earns from. ReferralDirectReferee: type: object properties: wallet: example: '0x0000000000000000000000000000000000000002' type: string description: Public wallet address of the direct referee. Never an internal id. nullable: true referredAt: example: '2026-07-07T18:00:00Z' type: string description: >- RFC 3339 timestamp when the referral relationship was recorded (the referee's sign-up under the caller). nullable: true totalEarned: example: '900000' type: string description: >- Total the caller has earned from this referee's own (L1) trades, in RAW atomic units. `0` for a referee who has not traded yet. nullable: true display: example: cooltrader123 type: string description: >- Human-facing name for the referee: their custom TraderCode handle when they have claimed one, otherwise the wallet address (same as `wallet`). Render this instead of raw hex. nullable: true description: >- One direct (L1) referee of the caller, whether or not they have traded yet. ReferralEarningsSummary: type: object properties: totalEarned: example: '1400000' type: string description: >- All-time credited earnings across all levels, in the reward token's RAW atomic units (see the message note — this is not the spendable rewards balance). nullable: true level1Earned: example: '900000' type: string description: Total earned from direct (L1) referees, in RAW atomic units. nullable: true level2Earned: example: '400000' type: string description: Total earned from L2 downline, in RAW atomic units. nullable: true level3Earned: example: '100000' type: string description: Total earned from L3 downline, in RAW atomic units. nullable: true description: |- Per-level breakdown of the caller's total referral earnings. These are ALL-TIME CREDITED earnings — a raw sum of the immutable `referral_rewards` audit rows — and match the `total_earned` on the referral position. They are NOT the caller's current spendable rewards balance: `GetRewardsBalance` reports the live bucket, which `TransferRewards` draws down, so the two diverge after any transfer. Read the rewards balance for current availability. Denominated in the single reward token's atomic units (Monaco pays PitPass rewards in one token — the quote asset); if a deployment ever pays in more than one reward token, atomic units across tokens are not additive, so read the per-token `earnings_by_source` rows for a correct breakdown. securitySchemes: monacoSignature: type: apiKey description: >- Ed25519 session-key request signing. Every authenticated request carries three headers: `X-Monaco-PublicKey` (64-char lowercase-hex session public key), `X-Monaco-Timestamp` (Unix milliseconds, within 30s of server time), and `X-Monaco-Signature` (hex ed25519 signature). The signature is over `METHOD\npath?query\ntimestamp_ms\nSHA256_hex(body)`, where the body hash is the SHA-256 of the empty byte string when there is no body. Obtain the session keypair from `POST /api/v1/auth/challenge` followed by `POST /api/v1/auth/verify`. name: X-Monaco-Signature in: header monacoHttpSignature: type: apiKey description: >- RFC 9421 Ed25519 session-key request signatures. Send Signature-Input, Signature, and Content-Digest together; never combine them with X-Monaco-* credentials. The monaco signature covers @method, @path, @query, and content-digest in that order, with created (Unix seconds within 30s of server time), keyid (registered lowercase-hex session public key), and alg=ed25519 parameters. Content-Digest uses RFC 9530 sha-256 over the exact body bytes, including the empty body. Query coverage retains ordering and percent encoding. Timestamp freshness does not reject repeated identical requests; use endpoint idempotency where supported. Existing legacy signing remains supported during server-first migration; SDK RFC 9421 signing is opt-in. See https://docs.0xmonaco.com/reference/http-message-signatures for the complete profile and trust model. name: Signature in: header ````