Version: 1.0.2

Download OpenAPI YAML

Exness Partner API

OpenAPI contract for Exness Partner API.

The paths in this document are public Exness Partner API routes.

Domain model:

• Partner = commercial participant who uses partner links to attract clients and can receive rewards from eligible client activity.
• Partner link = trackable public link or code used to attribute a registering client to a partner.
• Client = person identified by client_uid who registers through partner attribution and can own one or more trading accounts.
• Client attribution = association between a client or a client trading account and a partner. A client and that client's trading accounts can be attributed to different partners.
• Client trading account = trading account owned by a client. The Client accounts and Client transactions reports provide information about activity on that account.
• Campaign = partner-defined grouping of links and tracking attributes used to compare acquisition and conversion performance.
• Reward order = reward contribution calculated from an eligible closed client order.
• Reward = partner earnings from eligible trading activity by referred clients, paid as an aggregate of reward orders. Daily and instant rewards use different processing cycles; the API does not define a delivery-time SLA for either cycle.
• Rebate = portion of partner reward returned to a client. A rebate can be calculated and processed through an automated configuration.
• Rebate row = rebate amount calculated for one client trading account from the corresponding reward and rebate percentage. Its status and error fields show the processing result.
• Rebate payment = aggregate over the rebate rows included in one payment. Its amounts, status, and processing result summarize those rows.
• IB partner = partner whose eligible client trading activity can generate revenue-share rewards.
• Revenue share = reward model in which eligible client trading activity contributes to a partner's reward. Calculation can vary by the client's trading account type.
• Subpartner = partner registered under a master partner. The subpartner receives first-level reward, while the master partner can receive second-level reward.
• Referral agent = agent who attracts clients directly for a master partner through a dedicated link and receives an agreed share of the master's reward for those clients.
• Referral-agent link = link owned by a master partner and used by a referral agent to attract clients for that master partner. The link is used to track which clients were attracted by the referral agent.
• Referral-agent agreement = versioned reward-share terms agreed between a master partner and a referral agent. The effective dates determine which reward-share percentage applies.
• Referral-agent reward row = calculation record that links a processed partner reward to the agreement and reward-share percentage used for the agent payment.
• Shared-report access = configuration that records report access granted by a master partner to a referral agent. This API version returns the configuration but does not include operations to change it or retrieve shared-report data.
• Partner tier = partner reward level determined by qualification conditions. Current tier and qualification tier can differ.
• Progress reward = additional compensation associated with reaching a higher partner tier during an applicable benefit period.
• Report = read-only analytical view over partner-related commercial data. Report data is updated asynchronously, and changes may appear in different report families at different times.

General API rules:

Authorization:

• The primary authentication method is request signing with an API key.
• Signed requests use the EXN-* headers documented in the security schemes.
• EXN-DATA contains a base64url-encoded JSON payload with the fields that are signed.
• EXN-SIGN contains the Ed25519 signature of the decoded EXN-DATA payload.
• EXN-DATA and EXN-SIGN must use base64url without = padding.
• EXN-SIGN-VERSION must be 1.
• The signed payload must contain:
  • api_key: same value as EXN-API-KEY
  • idempotency_key: reserved signing field; use an empty string for the current Partnership API
  • timestamp: Unix time in milliseconds, same value as EXN-TIMESTAMP
  • sign_version: same value as EXN-SIGN-VERSION
  • method: uppercase HTTP method, for example POST
  • path: request path with query string exactly as sent by the client
  • body_hash: SHA-256 hash of the request body, base64url-encoded without padding
• EXN-SIGN signs the decoded EXN-DATA payload bytes, not the base64url string.
• For requests without a body, body_hash is the SHA-256 hash of the empty string, base64url-encoded without padding.
• Query strings must be signed exactly as transmitted. Clients must not reorder or re-encode query parameters after signing.
• Use the query encoding defined for each parameter. Repeat conversion tags for multiple values; keep the query exactly as transmitted when signing.
• The timestamp must be close to the server time. Clients should generate a fresh signature for every request.
• The API key must be allowed to access the requested partner, source IP, and operation scope.
• Authentication headers are modeled as OpenAPI security schemes, not as ordinary operation parameters.
• Authentication and request-processing errors use the numeric envelope documented below. Partnership operation errors use the string-code error response documented below.
• Handle errors using the HTTP status and the returned error code. Use messages as explanations, not as exact strings to match.

Scopes:

• Read operations require partnership.all:read.
• State-changing operations require partnership.all.
• partnership.all includes read and write product access.
• partnership.all:read is read-only and must not allow campaign, rebate, referral-agent, or report-comment mutations.

Resource access:

• Requests operate in the context of the partner associated with the API key.
• Responses include only resources that the API key is allowed to access for that partner.
• When a requested identifier does not exist or is not accessible to the partner, the API returns the string error code NotFound where that error is documented for the operation.

Operation input:

• Send the path, query, header, and request-body fields documented for the operation. Do not rely on behavior for undocumented inputs.
• Operation descriptions list only endpoint-specific rules and restrictions. The general authorization, resource-access, and input rules in this section apply unless an operation says otherwise.

Date and time:

• all date-time values are returned in UTC when the field represents an absolute timestamp
• ISO 8601 format with explicit offset is preferred, for example 2026-08-25T12:30:00+00:00
• report filters may also accept date-only values where the endpoint schema documents them

Pagination and filtering:

• list and report endpoints use offset pagination unless explicitly documented otherwise
• limit controls page size and offset controls the starting row
• clients should keep filter sets stable while paginating through reports
• report endpoints may be eventually consistent; repeat reads with stable filters and interpret the identifiers defined by the selected report
• clients should not infer totals by page size alone; use response metadata when provided

Monetary and volume values:

• monetary, rebate, reward-share, and volume values may be represented as strings or numbers as defined by each operation schema
• clients should parse monetary values as decimals and avoid binary floating-point precision for accounting workflows

Request replay and recovery:

• the current Partnership API does not provide idempotent-write semantics
• idempotency_key remains a reserved field in EXN-DATA and must be an empty string
• no Partnership operation uses an idempotency header, replays a prior response, or prevents duplicate execution by request key
• after an unknown write outcome, read the affected resource or list before deciding whether to retry
• a repeated create request may return a conflict when the resource or unique value was already created

Client journeys:

Before you start:

1. You must have access to Partner Personal Area to create and manage an API key.
2. The integration must use an active API key.
3. The API key must include partnership.all:read for read-only integrations or partnership.all for integrations that create or change Partnership data.
4. Store your API key and private signing key securely in trusted backend infrastructure. Do not expose them to browser code.

Campaign and link journey:

1. Read existing partner links with GET /v1/partnership/partner/links.
2. Create a campaign and its initial link with POST /v1/partnership/campaigns.
3. Add more links to the campaign with POST /v1/partnership/campaigns/{campaign_code}/links.
4. Report operations use different attribution parameters: campaign_code, link_code, or partner_code. partner_code and link_code identify the same partner link; send only the parameter defined for the selected operation. The Client transactions report does not accept campaign or link filters.
5. Update the campaign title, description, or archive state with PATCH /v1/partnership/campaigns/{campaign_code}.

Reports journey:

1. Use GET /v1/partnership/reports/clients for client-level information about referred clients.
2. Use GET /v1/partnership/reports/clients/accounts when trading-account-level information is required.
3. Use GET /v1/partnership/reports/ib/performance for Performance statistics. Use GET /v1/partnership/reports/conversion for conversion metrics. Each report supports its own filters and grouping fields.
4. Use Reward history to analyze credited partner rewards and Client transactions to inspect the closed client orders associated with those rewards.
5. Use progress-reward reports to track qualification progress and compensation details.
6. Keep the same filters and ordering while paginating with limit and offset. Report pagination does not provide a stable snapshot while report data is changing.
7. Report data is updated asynchronously. Recent changes can become visible in different report families at different times.

Rebates journey:

1. Use GET /v1/partnership/autorebates to list generated rebates by period and status.
2. Use the group, client, and rule endpoints to inspect or manage rebate configuration. Write operations require partnership.all.
3. Monitor rebate history, payment status, and payment rebate rows for reconciliation.
4. Interpret batch, row, and payment statuses separately. A processed batch can include rejected rows; use individual row statuses and processed, rejected, and error amounts to reconcile the outcome.
5. Processing error_code values in rebate records are separate from HTTP errors. This API version does not expose payment-retry operations.

Referral-agent journey:

1. Set up a referral agent by creating a dedicated link with POST /v1/partnership/referral-agent-links. The master partner owns the link, and the referral agent uses it to attract clients for the master partner.
2. Read referral-agent links to show each agent's status, reward share, and shared-report configuration.
3. Update the link alias with PATCH /v1/partnership/referral-agent-links/{agent_link_id}.
4. Archive the link when it should no longer be used for new referrals.
5. The current contract returns commercial terms and shared-report configuration, but does not include operations to change them or retrieve shared-report data.

Consistency and recovery:

• read endpoints are safe to retry
• after a write timeout or connection failure, read the affected resource or list before deciding whether to retry the write
• do not assume that reusing an idempotency key prevents duplicate execution or returns the original response
• reports can lag behind write operations and rebate payments; clients should reconcile through report rows and payment identifiers
• public errors are non-retryable by default unless the code indicates rate limiting or temporary unavailability

Public error contract:

Partnership operation errors use this string-code error response:

{
  "code": "ValidationError",
  "message": "Invalid input.",
  "details": [
    {
      "field": "date_from",
      "code": "required",
      "message": "This field is required."
    }
  ]
}

• For Partnership operation errors, use the string code with the HTTP status to identify the error.
• message explains the error. Its wording may vary, so do not match it as an exact string.
• details is optional. It can contain an array, object, or string with additional information about the error.
• For validation errors, structured details may identify the affected field and provide a validation code and explanation.
• Each response represents one top-level error. Multiple field validation failures can be listed in details.
• Errors are non-retryable by default. Retry only when the table explicitly allows it.

Authentication, signature, permission, rate-limit, and request-processing failures use a numeric error response:

{
  "code": 1001,
  "error_message": "AUTH_INVALID_SIGNATURE",
  "description": "signature verification failed"
}

• For numeric errors, code is a number and error_message is its stable error name.
• description is optional additional information. Do not rely on its exact wording.
• retry_after is an optional RFC 3339 timestamp. Rate-limit responses also return Retry-After as seconds.
• Errors can use either format. Check the HTTP status and the fields returned before choosing how to handle them.

code	HTTP	What it means	Retry behavior	Client action
ValidationError	400	Request validation failed, including bad-request or conflict conditions returned as validation errors.	Do not retry unchanged.	Correct the request using details; for an uncertain state, read the resource before deciding whether to submit a changed request.
NotUnique	400	A campaign or campaign-link value conflicts with an existing value.	Do not retry unchanged.	Choose a different unique value or read the existing campaign or link.
ManyItems	400	A campaign or campaign-link limit was reached.	Do not retry unchanged.	Review the existing campaigns or links and reuse an existing resource where possible. Do not retry the same create request until the limit has been resolved.
AuthenticationFailed	401	A Partnership service rejected the authenticated request after request authentication. API-key and request-signature failures use the numeric authentication errors below.	Do not retry unchanged.	Check the request authorization context. When the response uses the numeric envelope, follow the action for its error_message.
PermissionDenied	403	The authenticated identity cannot perform the operation or access the requested partner data.	Do not retry unchanged.	Use credentials with the required Partnership permission and resource access.
NotFound	404	The resource does not exist or is not available to the partner.	Do not retry unchanged.	Verify the identifier and current resource list.
Throttled	429	A Partnership operation rate limit was exceeded.	Retry after waiting; use backoff.	Slow down the request rate and honor Retry-After when it is returned.
Error	500	A Partnership operation failed because a required service could not complete the request.	Retry only when safe.	Retry reads with backoff; for an uncertain write, read current state before deciding whether to retry.
ServiceTransportError	504	A service required by the Partnership operation could not be reached or timed out.	Retry with exponential backoff.	For an uncertain write, read the affected resource before sending another write.

Authentication and request-processing errors:

code	error_message	HTTP	What it means	Retry behavior	Client action
1	SYSTEM_BAD_GATEWAY	502	The API could not complete the request to the Partnership service.	Retry with backoff.	Retry reads; for an uncertain write, read current state before deciding whether to retry.
2	SYSTEM_TEMPORARY_UNAVAILABLE	503	A required service is temporarily unavailable or the request deadline was exceeded.	Retry with backoff.	Retry reads; for an uncertain write, read current state before deciding whether to retry.
3	SYSTEM_INTERNAL_ERROR	500	The API encountered an unexpected internal error.	Retry only when safe.	Retry reads with backoff; check current state before retrying a write.
1000	AUTH_INVALID_API_KEY	401	The API key is invalid, expired, revoked, or not allowed for the request source.	Do not retry unchanged.	Check the API key, its state, and its allowed source IP.
1001	AUTH_INVALID_SIGNATURE	401	The request signature or signed timestamp is invalid.	Do not retry unchanged.	Rebuild the signature from the exact method, path, query, body, headers, and a fresh timestamp.
1002	AUTH_FORBIDDEN	403	The API key does not have a required operation scope.	Do not retry unchanged.	Use an API key with the required Partnership scope.
1003	AUTH_RATE_LIMIT	429	The authentication rate limit was exceeded.	Retry after waiting; use backoff.	Honor Retry-After and reduce request rate.
3001	REQUEST_INVALID_PARAMETERS	400	Required headers or signed request data are malformed or inconsistent.	Do not retry unchanged.	Correct the headers or signed values named by description, then sign the exact request again.

Glossary:

• partner_uid: stable identifier of the partner.
• partner_account: partner account used to receive rewards and fund rebates.
• partner_code: identifier embedded in a partner link and used during client registration to attribute the client to the corresponding partner. In this API, partner_code and link_code refer to the same link identifier; the field name depends on the operation.
• link_code: alternative field name for partner_code, representing the same partner-link identifier.
• campaign_code: stable partner campaign identifier used in campaign links and supported report filters.
• client_uid: identifier of a referred client.
• client_account: trading account associated with a referred client.
• reward_order: reward contribution associated with an eligible closed client order.
• reward: partner earnings from eligible client trading activity, represented as an aggregate of reward orders for a partner, client account, and payout cycle.
• revenue_share: payout category used for IB partner rewards; it is not a separate reward record.
• first-level reward: reward earned by the partner directly attributed to the client activity.
• second-level reward: reward earned by a master partner from eligible activity attributed through a subpartner.
• rebate_id: identifier of a generated rebate batch or period.
• rebate_row_id: identifier of a client-account rebate calculation row.
• payment_id: identifier of a rebate-payment aggregate used to reconcile its included rebate rows.
• group_id: rebate group identifier.
• rule_id: rebate rule identifier.
• agent_link_id: referral-agent link identifier.
• share_perc: percentage of the master's eligible reward assigned to the referral agent by the applicable agreement.
• shared_reports: shared-report configuration returned for a referral-agent link. This API version does not include operations to retrieve shared-report data.
• order_id query parameter: raw numeric trading order number used by the Client transactions report filter.
• order_id in a Client transactions report row: composite string in <server_code>:<order_number> format. Extract the numeric part after : before using it in the order_id filter.
• compensation_id: identifier of a progress-reward compensation record.

Common troubleshooting scenarios:

• A read-only key calling a write endpoint returns 403; use a key with partnership.all or keep the integration read-only.
• An empty report page is a valid result; confirm filters, retry later for recent periods, and reconcile with overlapping windows.
• A campaign, rebate group, or referral-agent link may return 404 when the identifier is wrong or belongs to another partner.

Authentication

API Key: ExnApiKeyAuth

API key identifier used by signed requests.

This value must match the api_key field inside the signed EXN-DATA payload. An unknown, expired, revoked, or source-IP-restricted API key is returned as numeric code 1000 with error_message: AUTH_INVALID_API_KEY. A mismatch between this header and the api_key value in EXN-DATA is a malformed signed request and is returned as numeric code 3001 with error_message: REQUEST_INVALID_PARAMETERS.

Security Scheme Type:	apiKey
Header parameter name:	EXN-API-KEY

API Key: ExnTimestampAuth

Unix timestamp in milliseconds used by signed requests.

This value must match the timestamp field inside the signed EXN-DATA payload. Clients should generate a fresh timestamp and signature for every request. Requests outside the accepted server time window are rejected.

Security Scheme Type:	apiKey
Header parameter name:	EXN-TIMESTAMP

API Key: ExnDataAuth

Base64url-encoded signed data payload, without = padding.

The decoded payload is a JSON object with the following fields:

• api_key: same value as EXN-API-KEY
• idempotency_key: reserved signing field; use an empty string for the current Partnership API
• timestamp: same value as EXN-TIMESTAMP
• sign_version: same value as EXN-SIGN-VERSION
• method: uppercase HTTP method, for example POST
• path: request path with query string exactly as sent by the client
• body_hash: SHA-256 hash of the request body, base64url-encoded without padding

Security Scheme Type:	apiKey
Header parameter name:	EXN-DATA

API Key: ExnSignatureAuth

Ed25519 signature for the decoded EXN-DATA payload, encoded as base64url without = padding.

Invalid signatures are returned as numeric code 1001 with error_message: AUTH_INVALID_SIGNATURE.

Security Scheme Type:	apiKey
Header parameter name:	EXN-SIGN

API Key: ExnSignVersionAuth

Signature protocol version.

The only supported value is 1. This value must match the sign_version field inside EXN-DATA.

Security Scheme Type:	apiKey
Header parameter name:	EXN-SIGN-VERSION