Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

FXP Tier Improvements

Manage tier-based rate improvements per source currency. Tiers apply a basis-point improvement for transactions meeting or exceeding a threshold amount. Nexus selects the tier with the greatest qualifying threshold and combines it with any applicable PSP-based improvement before applying the total to the base rate.

List FXP tiers

get

Returns the authenticated FXP's configured tiers, optionally filtered by source currency. When includeExpired=true, historical tiers from the last 13 months are included and limit is required (maximum 100). Tiers remain live until replaced for the same (fxpId, sourceCurrency, threshold) or voluntarily withdrawn.

Required scopes
This endpoint requires the following scopes:
  • : Read FXP tier records.
Authorizations
mutualTLS

Nexus issued X.509 client certificate presented during the TLS handshake and validated at the Akamai global edge. The FXP generates its own key pair and submits a CSR during onboarding; Vault PKI (edge intermediate CA) signs it and the private key never leaves FXP infrastructure. Fail closed: a missing, expired, revoked or untrusted certificate causes the TLS handshake to fail at the edge and no HTTP response is produced. The certificate is not forwarded to the origin as an HTTP header.

OAuth2clientCredentialsRequired

OAuth2 client credentials token issued per participant.

Token URL:
Query parameters
sourceCurrencystring · min: 3 · max: 3Optional

ISO 4217 3-letter source currency code (uppercase). Filters results to tiers for this source currency.

Example: EURPattern: ^[A-Z]{3}$
includeExpiredbooleanOptional

If true, include expired (withdrawn or superseded) tiers from the last 13 months. Default: false. When true, limit is required.

Default: falseExample: false
limitinteger · min: 1 · max: 100Optional

Max items to return. Default 50. Maximum 100. Required when includeExpired=true.

Default: 50Example: 50
cursorstringOptional

Pagination cursor; omit for first page. This endpoint is limited to a maximum of 100 records.

Example: eyJwayI6Li4ufQ==
Header parameters
AcceptstringRequired

application/json

Default: application/jsonExample: application/json
Responses
200

Tiers retrieved successfully.

application/json

Paginated list of tier records.

cursorstring · nullableOptional

Opaque cursor for the next page. Null if this is the last page.

Example: eyJwayI6Li4ufQ==
get/v1/tiers
GET /v1/tiers HTTP/1.1
Host: localhost:8080
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: application/json

{
  "items": [
    {
      "tierId": "f5cf7e7f-dc78-4f5b-a9d1-1135e10dbf87",
      "fxpId": "FXP-A",
      "sourceCurrency": "EUR",
      "threshold": 50000,
      "improvementBps": 100,
      "createdDateTime": "2024-11-01T10:00:00Z",
      "isExpired": false,
      "expiryDateTime": null
    }
  ],
  "cursor": "eyJwayI6Li4ufQ=="
}

Create or replace a tier

post

Creates a new tier record for the given source currency and threshold. If a live tier already exists for the same fxpId, sourceCurrency, and threshold, Nexus marks the prior record as superseded and creates the new tier. Tiers are PSP-agnostic and apply based on transaction size in the source currency.

Required scopes
This endpoint requires the following scopes:
  • : Create or withdraw FXP tier records.
Authorizations
mutualTLS

Nexus issued X.509 client certificate presented during the TLS handshake and validated at the Akamai global edge. The FXP generates its own key pair and submits a CSR during onboarding; Vault PKI (edge intermediate CA) signs it and the private key never leaves FXP infrastructure. Fail closed: a missing, expired, revoked or untrusted certificate causes the TLS handshake to fail at the edge and no HTTP response is produced. The certificate is not forwarded to the origin as an HTTP header.

OAuth2clientCredentialsRequired

OAuth2 client credentials token issued per participant.

Token URL:
Header parameters
AcceptstringRequired

application/json

Default: application/jsonExample: application/json
Body

Request body for creating or replacing a tier.

sourceCurrencystring · min: 3 · max: 3Required

ISO 4217 source currency code the tier applies to.

Example: EURPattern: ^[A-Z]{3}$
thresholdnumber · doubleRequired

Minimum transaction amount in the source currency for this tier to apply.

Example: 50000
improvementBpsinteger · min: 1Required

Rate improvement in basis points applied to the base rate when this tier is selected.

Example: 100
Responses
200

Tier created successfully. Returns the new tier record.

application/json

A single FXP tier record.

tierIdstring · uuidOptional

Nexus-assigned unique identifier for the tier record.

Example: f5cf7e7f-dc78-4f5b-a9d1-1135e10dbf87
fxpIdstringOptional

Nexus internal identifier for the FXP that owns this tier.

Example: FXP-A
sourceCurrencystring · min: 3 · max: 3Optional

ISO 4217 source currency code this tier applies to.

Example: EUR
thresholdnumber · doubleOptional

Minimum transaction amount (in source currency) for this tier to apply.

Example: 50000
improvementBpsintegerOptional

Improvement in basis points applied when this tier is selected.

Example: 100
createdDateTimestring · date-timeOptional

ISO 8601 UTC timestamp when this tier record was created.

Example: 2024-11-01T10:00:00Z
isExpiredbooleanOptional

If true, this tier has been superseded or voluntarily withdrawn.

Example: false
expiryDateTimestring · nullableOptional

ISO 8601 UTC timestamp when this tier was superseded or withdrawn. Null if still live.

post/v1/tiers
POST /v1/tiers HTTP/1.1
Host: localhost:8080
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: application/json
Content-Type: application/json
Content-Length: 63

{
  "sourceCurrency": "EUR",
  "threshold": 50000,
  "improvementBps": 100
}
{
  "tierId": "f5cf7e7f-dc78-4f5b-a9d1-1135e10dbf87",
  "fxpId": "FXP-A",
  "sourceCurrency": "EUR",
  "threshold": 50000,
  "improvementBps": 100,
  "createdDateTime": "2024-11-01T10:00:00Z",
  "isExpired": false,
  "expiryDateTime": null
}

Get tier count

get

Returns the count of tiers for the authenticated FXP. includeExpired controls whether expired (withdrawn or superseded) tiers are included in the count.

Required scopes
This endpoint requires the following scopes:
  • : Read FXP tier records.
Authorizations
mutualTLS

Nexus issued X.509 client certificate presented during the TLS handshake and validated at the Akamai global edge. The FXP generates its own key pair and submits a CSR during onboarding; Vault PKI (edge intermediate CA) signs it and the private key never leaves FXP infrastructure. Fail closed: a missing, expired, revoked or untrusted certificate causes the TLS handshake to fail at the edge and no HTTP response is produced. The certificate is not forwarded to the origin as an HTTP header.

OAuth2clientCredentialsRequired

OAuth2 client credentials token issued per participant.

Token URL:
Query parameters
includeExpiredbooleanOptional

If true, include expired (withdrawn or superseded) tiers in the count. Default: false.

Default: falseExample: false
Header parameters
AcceptstringRequired

application/json

Default: application/jsonExample: application/json
Responses
200

Count retrieved successfully.

application/json

Count of records matching the query.

countintegerOptional

Total count of matching records.

Example: 2
get/v1/tiers/count
GET /v1/tiers/count HTTP/1.1
Host: localhost:8080
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: application/json

{
  "count": 3
}

Get a single tier

get

Returns a single tier record by tierId for the authenticated FXP.

Required scopes
This endpoint requires the following scopes:
  • : Read FXP tier records.
Authorizations
mutualTLS

Nexus issued X.509 client certificate presented during the TLS handshake and validated at the Akamai global edge. The FXP generates its own key pair and submits a CSR during onboarding; Vault PKI (edge intermediate CA) signs it and the private key never leaves FXP infrastructure. Fail closed: a missing, expired, revoked or untrusted certificate causes the TLS handshake to fail at the edge and no HTTP response is produced. The certificate is not forwarded to the origin as an HTTP header.

OAuth2clientCredentialsRequired

OAuth2 client credentials token issued per participant.

Token URL:
Path parameters
tierIdstring · uuidRequired

UUID of the tier record.

Example: f5cf7e7f-dc78-4f5b-a9d1-1135e10dbf87
Header parameters
AcceptstringRequired

application/json

Default: application/jsonExample: application/json
Responses
200

Tier retrieved successfully.

application/json

A single FXP tier record.

tierIdstring · uuidOptional

Nexus-assigned unique identifier for the tier record.

Example: f5cf7e7f-dc78-4f5b-a9d1-1135e10dbf87
fxpIdstringOptional

Nexus internal identifier for the FXP that owns this tier.

Example: FXP-A
sourceCurrencystring · min: 3 · max: 3Optional

ISO 4217 source currency code this tier applies to.

Example: EUR
thresholdnumber · doubleOptional

Minimum transaction amount (in source currency) for this tier to apply.

Example: 50000
improvementBpsintegerOptional

Improvement in basis points applied when this tier is selected.

Example: 100
createdDateTimestring · date-timeOptional

ISO 8601 UTC timestamp when this tier record was created.

Example: 2024-11-01T10:00:00Z
isExpiredbooleanOptional

If true, this tier has been superseded or voluntarily withdrawn.

Example: false
expiryDateTimestring · nullableOptional

ISO 8601 UTC timestamp when this tier was superseded or withdrawn. Null if still live.

get/v1/tiers/{tierId}
GET /v1/tiers/{tierId} HTTP/1.1
Host: localhost:8080
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: application/json

{
  "tierId": "f5cf7e7f-dc78-4f5b-a9d1-1135e10dbf87",
  "fxpId": "FXP-A",
  "sourceCurrency": "EUR",
  "threshold": 50000,
  "improvementBps": 100,
  "createdDateTime": "2024-11-01T10:00:00Z",
  "isExpired": false,
  "expiryDateTime": null
}

Withdraw a tier

delete

Voluntarily withdraws a tier so it no longer applies to quote generation. Sets isExpired=true and records expiryDateTime as a historical marker. Returns the withdrawn tier record.

Required scopes
This endpoint requires the following scopes:
  • : Create or withdraw FXP tier records.
Authorizations
mutualTLS

Nexus issued X.509 client certificate presented during the TLS handshake and validated at the Akamai global edge. The FXP generates its own key pair and submits a CSR during onboarding; Vault PKI (edge intermediate CA) signs it and the private key never leaves FXP infrastructure. Fail closed: a missing, expired, revoked or untrusted certificate causes the TLS handshake to fail at the edge and no HTTP response is produced. The certificate is not forwarded to the origin as an HTTP header.

OAuth2clientCredentialsRequired

OAuth2 client credentials token issued per participant.

Token URL:
Path parameters
tierIdstring · uuidRequired

UUID of the tier record to withdraw.

Example: f5cf7e7f-dc78-4f5b-a9d1-1135e10dbf87
Header parameters
AcceptstringRequired

application/json

Default: application/jsonExample: application/json
Responses
200

Tier withdrawn successfully. Returns the withdrawn tier record with isExpired=true.

application/json

A single FXP tier record.

tierIdstring · uuidOptional

Nexus-assigned unique identifier for the tier record.

Example: f5cf7e7f-dc78-4f5b-a9d1-1135e10dbf87
fxpIdstringOptional

Nexus internal identifier for the FXP that owns this tier.

Example: FXP-A
sourceCurrencystring · min: 3 · max: 3Optional

ISO 4217 source currency code this tier applies to.

Example: EUR
thresholdnumber · doubleOptional

Minimum transaction amount (in source currency) for this tier to apply.

Example: 50000
improvementBpsintegerOptional

Improvement in basis points applied when this tier is selected.

Example: 100
createdDateTimestring · date-timeOptional

ISO 8601 UTC timestamp when this tier record was created.

Example: 2024-11-01T10:00:00Z
isExpiredbooleanOptional

If true, this tier has been superseded or voluntarily withdrawn.

Example: false
expiryDateTimestring · nullableOptional

ISO 8601 UTC timestamp when this tier was superseded or withdrawn. Null if still live.

delete/v1/tiers/{tierId}
DELETE /v1/tiers/{tierId} HTTP/1.1
Host: localhost:8080
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: application/json

{
  "tierId": "f5cf7e7f-dc78-4f5b-a9d1-1135e10dbf87",
  "fxpId": "FXP-A",
  "sourceCurrency": "EUR",
  "threshold": 50000,
  "improvementBps": 100,
  "createdDateTime": "2024-11-01T10:00:00Z",
  "isExpired": false,
  "expiryDateTime": null
}
PreviousFXP Rates
NextFXP PSP Relationships

Last updated