> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rolla.xyz/llms.txt
> Use this file to discover all available pages before exploring further.
# Get Commissions
> Retrieves a paginated list of the commissions you have earned from referred businesses, newest first. Every money field is an integer in the smallest unit of the currency named beside it.
Retrieve a paginated list of commissions earned from your referrals. Filter by date range or currency.
**Broker activation is required.** Broker accounts are activated by the Rolla admin team — you cannot activate a broker account yourself through the API. Once your business has been activated as a broker by Rolla, all broker endpoints become available. Until then, all requests will return a `403 Forbidden` error. Contact [support@rolla.xyz](mailto:support@rolla.xyz) to request broker activation.
## Example Request
```bash theme={null}
curl -X GET "https://api.rolla.xyz/api/v1/external/broker/commissions?page=1&pageSize=20¤cy=USD&startDate=2024-01-01&endDate=2024-01-31" \
-H "X-API-Key: your_api_key_here"
```
## Query Parameters
| Parameter | Type | Description |
| -------------------- | ------- | --------------------------------------------------------------- |
| `page` | integer | Page number (default: 1) |
| `pageSize` | integer | Results per page (default: 20, max: 100) |
| `startDate` | string | Start date filter (YYYY-MM-DD) |
| `endDate` | string | End date filter (YYYY-MM-DD) |
| `currency` | string | Filter by currency code (uppercase, 3 or 4 letters, e.g. `USD`) |
| `referredBusinessId` | string | Only commissions earned from this referred business (UUID) |
Commissions are returned newest first. Every amount is an integer in the currency's smallest unit: `commission_amount` is in the smallest unit of `commission_currency`, `source_amount` of `source_currency`, and `destination_amount` of `destination_currency`.
## Example Response
```json theme={null}
{
"status": 200,
"message": "Commissions fetched successfully",
"success": true,
"data": {
"commissions": [
{
"id": "e5f6a7b8-c9d0-4234-8fab-567890123456",
"commission_amount": 1550,
"commission_currency": "USD",
"commission_margin": "0.01000000",
"currency_pair": "USD/NGN",
"rate_margin": "5.00000000",
"rate_margin_type": "flat",
"referred_business_id": "d4e5f6a7-b8c9-4123-9def-456789012345",
"transaction_id": "8f1c2d3e-4a5b-4c6d-8e9f-0a1b2c3d4e5f",
"created_at": "2024-01-20T14:00:00.000Z",
"business_name": "Acme Corp Ltd",
"exchange_rate": 1480,
"base_rate": 1475,
"source_currency": "USD",
"source_amount": 100000,
"destination_currency": "NGN",
"destination_amount": 148000000,
"swap_transaction": {
"id": "3b9d5a7c-2e18-4f60-9a7d-1c0b5e8f4d22",
"transaction_type": "swap",
"status": "completed",
"description": "Swap USD to NGN",
"external_reference": "SWP-20240120-0001",
"source_currency": "USD",
"source_amount": 100000,
"destination_currency": "NGN",
"destination_amount": 148000000,
"created_at": "2024-01-20T13:59:58.000Z"
}
}
],
"pagination": {
"page": 1,
"pageSize": 20,
"total": 45,
"totalPages": 3
}
}
}
```
In the row above the broker earned USD 15.50 on a USD 1,000 swap into NGN at a rate of 1,480 against a base rate of 1,475.
`swap_transaction` is `null` for a commission with no underlying swap on record, and `exchange_rate`, `base_rate`, `source_amount` and `destination_amount` are `null` when the pricing detail was not captured. Rows also carry `meta`, `transaction` and `referredBusiness` objects holding internal pricing detail; treat them as informational and do not depend on their contents.
Use the `startDate` and `endDate` filters to generate commission reports for specific periods. Both accept a date (`2024-01-01`) or a full ISO 8601 timestamp, and are matched against `created_at`.
## OpenAPI
````yaml GET /broker/commissions
openapi: 3.1.0
info:
title: Rolla Developer API
description: >-
API for programmatic transaction management on the Rolla platform. Monetary
`amount` fields use the smallest unit of the referenced currency unless an
endpoint says otherwise (e.g. NGN = kobo, USD = cents, where **100 cents =
USD 1.00**).
version: 1.0.0
servers:
- url: https://api.rolla.xyz/api/v1/external
description: Production server
security:
- apiKeyAuth: []
paths:
/broker/commissions:
get:
summary: Get Commissions
description: >-
Retrieves a paginated list of the commissions you have earned from
referred businesses, newest first. Every money field is an integer in
the smallest unit of the currency named beside it.
operationId: getCommissions
parameters:
- name: page
in: query
description: Page number
schema:
type: integer
default: 1
minimum: 1
example: 1
- name: pageSize
in: query
description: Results per page
schema:
type: integer
default: 20
minimum: 1
maximum: 100
example: 20
- name: startDate
in: query
description: >-
Only commissions earned on or after this date (date or ISO 8601
timestamp)
schema:
type: string
example: '2024-01-01'
- name: endDate
in: query
description: >-
Only commissions earned on or before this date (date or ISO 8601
timestamp)
schema:
type: string
example: '2024-01-31'
- name: currency
in: query
description: Filter by commission currency, uppercase, 3 or 4 letters
schema:
type: string
minLength: 3
maxLength: 4
pattern: ^[A-Z]+$
example: USD
- name: referredBusinessId
in: query
description: Only commissions earned from this referred business
schema:
type: string
format: uuid
example: d4e5f6a7-b8c9-4123-9def-456789012345
responses:
'200':
description: Commissions fetched successfully
content:
application/json:
schema:
type: object
required:
- status
- message
- success
- data
properties:
status:
type: integer
example: 200
message:
type: string
example: Commissions fetched successfully
success:
type: boolean
example: true
data:
type: object
required:
- commissions
- pagination
properties:
commissions:
type: array
items:
$ref: '#/components/schemas/Commission'
pagination:
$ref: '#/components/schemas/Pagination'
example:
status: 200
message: Commissions fetched successfully
success: true
data:
commissions:
- id: e5f6a7b8-c9d0-4234-8fab-567890123456
commission_amount: 1550
commission_currency: USD
commission_margin: '0.01000000'
currency_pair: USD/NGN
rate_margin: '5.00000000'
rate_margin_type: flat
referred_business_id: d4e5f6a7-b8c9-4123-9def-456789012345
transaction_id: 8f1c2d3e-4a5b-4c6d-8e9f-0a1b2c3d4e5f
created_at: '2024-01-20T14:00:00.000Z'
business_name: Acme Corp Ltd
exchange_rate: 1480
base_rate: 1475
source_currency: USD
source_amount: 100000
destination_currency: NGN
destination_amount: 148000000
swap_transaction:
id: 3b9d5a7c-2e18-4f60-9a7d-1c0b5e8f4d22
transaction_type: swap
status: completed
description: Swap USD to NGN
external_reference: SWP-20240120-0001
source_currency: USD
source_amount: 100000
destination_currency: NGN
destination_amount: 148000000
created_at: '2024-01-20T13:59:58.000Z'
pagination:
page: 1
pageSize: 20
total: 45
totalPages: 3
'400':
description: Invalid query parameters
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
status: 400
message: Validation failed
errors:
- path:
- currency
message: Invalid
'401':
description: Unauthorized - Invalid or missing API key
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Forbidden - the business is not activated as a broker
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
status: 403
message: Business is not activated as a broker
components:
schemas:
Commission:
type: object
description: >-
One commission earned from a referred business. Money fields are
integers in the smallest unit of the currency named beside them.
additionalProperties: true
required:
- id
- commission_amount
- commission_currency
- transaction_id
- created_at
properties:
id:
type: string
format: uuid
description: Commission identifier
example: e5f6a7b8-c9d0-4234-8fab-567890123456
commission_amount:
type: integer
description: >-
Commission earned, in the smallest unit of commission_currency (1550
= USD 15.50).
example: 1550
commission_currency:
type: string
description: Currency the commission was paid in
example: USD
commission_margin:
type: string
nullable: true
description: Share of the spread earned, as a decimal string (0.01 is 1%).
example: '0.01000000'
currency_pair:
type: string
nullable: true
description: Pair the underlying swap traded
example: USD/NGN
rate_margin:
type: string
nullable: true
description: Markup applied to the rate, as a decimal string.
example: '5.00000000'
rate_margin_type:
type: string
nullable: true
enum:
- flat
- percentage
- null
description: Whether rate_margin is a flat amount or a percentage.
example: flat
referred_business_id:
type: string
format: uuid
nullable: true
description: The referred business the commission came from.
example: d4e5f6a7-b8c9-4123-9def-456789012345
transaction_id:
type: string
format: uuid
description: Transaction that paid the commission out.
example: 8f1c2d3e-4a5b-4c6d-8e9f-0a1b2c3d4e5f
created_at:
type: string
format: date-time
description: When the commission was earned
example: '2024-01-20T14:00:00.000Z'
business_name:
type: string
nullable: true
description: Name of the referred business
example: Acme Corp Ltd
exchange_rate:
type: number
nullable: true
description: Rate the customer traded at
example: 1480
base_rate:
type: number
nullable: true
description: Rate before your markup
example: 1475
source_currency:
type: string
nullable: true
description: Currency sold on the underlying swap
example: USD
source_amount:
type: integer
nullable: true
description: Amount sold, in the smallest unit of source_currency.
example: 100000
destination_currency:
type: string
nullable: true
description: Currency bought on the underlying swap
example: NGN
destination_amount:
type: integer
nullable: true
description: Amount bought, in the smallest unit of destination_currency.
example: 148000000
swap_transaction:
type: object
nullable: true
description: >-
The swap the commission was earned on, or null when none is on
record. Amounts are integers in the smallest unit of their currency.
Also carries a `meta` object of internal pricing detail.
additionalProperties: true
properties:
id:
type: string
format: uuid
example: 3b9d5a7c-2e18-4f60-9a7d-1c0b5e8f4d22
transaction_type:
type: string
example: swap
status:
type: string
example: completed
description:
type: string
nullable: true
example: Swap USD to NGN
external_reference:
type: string
nullable: true
example: SWP-20240120-0001
source_currency:
type: string
example: USD
source_amount:
type: integer
nullable: true
description: Smallest units of source_currency
example: 100000
destination_currency:
type: string
example: NGN
destination_amount:
type: integer
nullable: true
description: Smallest units of destination_currency
example: 148000000
created_at:
type: string
format: date-time
example: '2024-01-20T13:59:58.000Z'
meta:
type: object
nullable: true
additionalProperties: true
description: >-
Internal pricing detail recorded with the commission. Informational
only.
Pagination:
type: object
description: >-
Paging block used by the listings that nest one. The transaction
listings do not: they return `totalCount`, `page`, `pageSize` and
`totalPages` flat alongside `transactions`.
required:
- page
- pageSize
- total
- totalPages
properties:
page:
type: integer
description: Page just returned, starting at 1.
example: 1
pageSize:
type: integer
description: Rows per page.
example: 20
total:
type: integer
description: Total rows matching the filters.
example: 150
totalPages:
type: integer
description: How many pages there are in total.
example: 8
Error:
type: object
required:
- status
- message
description: >-
Error envelope. Some errors add further top-level fields (for example
`accountBlocked`, `provider`, `missingFields`); the endpoint documents
them where they apply.
additionalProperties: true
properties:
status:
type: integer
description: HTTP status code, repeated in the body as a number
example: 400
message:
type: string
description: Human-readable description of what went wrong
example: Validation failed
code:
type: string
description: >-
Machine-readable error code, present on some errors only. See the
Errors concept page for the taxonomy.
example: ACCOUNT_RESTRICTED
errors:
type: array
description: 'Present on `400` validation failures: one entry per offending field'
items:
type: object
properties:
path:
type: array
items:
type: string
example:
- amount
message:
type: string
example: >-
amount must be a whole number of smallest currency units (e.g.
cents)
securitySchemes:
apiKeyAuth:
type: apiKey
in: header
name: X-API-Key
description: Your Rolla API key
````