FXP Tier-based Improvement

APIs for FX Providers (FXPs) to manage improvement tiers, which give better rates in basis points for transactions at or above a threshold in a given source currency.

Create an improvement tier

post

http://localhost:8080https://nexus-ai-simulator-683365449922.asia-southeast1.run.app

/v1/tiers

Creates an improvement tier for a source currency. A tier defines a threshold and an improvement in basis points that applies to your base rate for transactions at or above that threshold. If a live tier already exists for the same source currency and threshold, it is automatically superseded. When Nexus generates a quote, it selects the tier with the greatest threshold that does not exceed the transaction amount, and adds tier and PSP improvements together in basis points before applying them, so improvements never compound. An idempotency key header is recommended. Requires the scope tiers.write. Used by: FX Providers (FXPs)

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Header parameters

Idempotency-Keystring · uuidOptional

Recommended for POST requests. A UUID used to deduplicate retried submissions.

Body

application/json

Request body for creating a tier. Any live tier that already exists for the same source currency and threshold is automatically superseded.

sourceCurrencystringRequired

ISO 4217 currency code of the source currency, three uppercase letters.

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

thresholdnumberRequired

Minimum transaction size, in the source currency, at which the tier applies. Must be greater than 0.

Example: 50000

improvementBpsintegerRequired

Improvement applied to the base rate, in basis points. Must be greater than or equal to 0.

Example: 100

Responses

200

The created tier record.

application/json

An improvement tier configured by an FXP for a source currency. A tier applies an improvement in basis points to the base rate for transactions at or above its threshold. Tiers apply to all PSPs equally and remain active until expired.

tierIdstringRequired

Unique ID of the tier record.

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

fxpIdstringRequired

ID of the FXP that owns this tier.

Example: FXP-A

sourceCurrencystringRequired

ISO 4217 currency code of the source currency, three uppercase letters.

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

thresholdnumberRequired

Minimum transaction size, in the source currency, at which the tier applies. Must be greater than 0.

Example: 50000

improvementBpsintegerRequired

Improvement applied to the base rate, in basis points. Must be greater than or equal to 0.

Example: 100

createdDateTimestring · date-timeRequired

Timestamp at which the tier record was created.

isExpiredbooleanRequired

Historical marker set to true when the tier is replaced or withdrawn.

expiryDateTimestring · nullableOptional

Timestamp at which the tier was replaced or withdrawn. A historical marker only.

400

Invalid request — syntax, schema, or field-level validation failure.

application/json

401

Missing or invalid bearer token.

application/json

403

Caller lacks permission for this resource or operation.

application/json

409

Conflicting state (e.g. duplicate tier for the same currency and threshold, or threshold ordering violation).

application/json

429

Rate limit exceeded. Returned by the API gateway and carries no structured Nexus body. The Retry-After response header indicates when to retry.

500

Unexpected server fault; caller may retry.

application/json

post/v1/tiers

HTTPcURLJavaScriptPython

POST /v1/tiers HTTP/1.1
Host: localhost:8080
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
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": "2026-08-10T14:46:54.897Z",
  "isExpired": true,
  "expiryDateTime": null
}

List improvement tiers

get

http://localhost:8080https://nexus-ai-simulator-683365449922.asia-southeast1.run.app

/v1/tiers

Returns the improvement tiers you have configured, with an optional filter by source currency. Each tier gives a better rate, in basis points, for transactions at or above its threshold. Tier records are kept for up to 13 months and a maximum of 100 records is returned. When includeExpired is true, the limit parameter must be provided. Requires the scope tiers.read. Used by: FX Providers (FXPs)

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

sourceCurrencystringOptional

ISO 4217 currency code of the source currency, three uppercase letters.

Pattern: ^[A-Z]{3}$

includeExpiredbooleanOptional

If true, include historical records that were replaced or withdrawn in the last 13 months. Default is false. When true, the limit parameter is required. Note that the word expired in field names is historical naming only; records are never expired based on time.

Default: false

limitinteger · min: 1 · max: 100Optional

Maximum number of items to return. Default is 50 and the maximum is 100. Required when includeExpired is true.

Default: 50

Responses

200

The FXP's tiers.

application/json

List of tier records belonging to the FXP.

400

Invalid request — syntax, schema, or field-level validation failure.

application/json

401

Missing or invalid bearer token.

application/json

403

Caller lacks permission for this resource or operation.

application/json

429

Rate limit exceeded. Returned by the API gateway and carries no structured Nexus body. The Retry-After response header indicates when to retry.

500

Unexpected server fault; caller may retry.

application/json

get/v1/tiers

HTTPcURLJavaScriptPython

GET /v1/tiers HTTP/1.1
Host: localhost:8080
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "tiers": [
    {
      "tierId": "f5cf7e7f-dc78-4f5b-a9d1-1135e10dbf87",
      "fxpId": "FXP-A",
      "sourceCurrency": "EUR",
      "threshold": 50000,
      "improvementBps": 100,
      "createdDateTime": "2026-08-10T14:46:54.897Z",
      "isExpired": true,
      "expiryDateTime": null
    }
  ]
}

Withdraw an improvement tier

delete

http://localhost:8080https://nexus-ai-simulator-683365449922.asia-southeast1.run.app

/v1/tiers/{tierId}

Withdraws a tier so it no longer applies when quotes are generated. The response returns the record with isExpired set to true as a historical marker. Requires the scope tiers.write. Used by: FX Providers (FXPs)

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

tierIdstringRequired

UUID of the tier record.

Responses

200

The withdrawn tier record.

application/json

An improvement tier configured by an FXP for a source currency. A tier applies an improvement in basis points to the base rate for transactions at or above its threshold. Tiers apply to all PSPs equally and remain active until expired.

tierIdstringRequired

Unique ID of the tier record.

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

fxpIdstringRequired

ID of the FXP that owns this tier.

Example: FXP-A

sourceCurrencystringRequired

ISO 4217 currency code of the source currency, three uppercase letters.

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

thresholdnumberRequired

Minimum transaction size, in the source currency, at which the tier applies. Must be greater than 0.

Example: 50000

improvementBpsintegerRequired

Improvement applied to the base rate, in basis points. Must be greater than or equal to 0.

Example: 100

createdDateTimestring · date-timeRequired

Timestamp at which the tier record was created.

isExpiredbooleanRequired

Historical marker set to true when the tier is replaced or withdrawn.

expiryDateTimestring · nullableOptional

Timestamp at which the tier was replaced or withdrawn. A historical marker only.

400

Invalid request — syntax, schema, or field-level validation failure.

application/json

401

Missing or invalid bearer token.

application/json

403

Caller lacks permission for this resource or operation.

application/json

404

Tier not found.

application/json

429

Rate limit exceeded. Returned by the API gateway and carries no structured Nexus body. The Retry-After response header indicates when to retry.

500

Unexpected server fault; caller may retry.

application/json

delete/v1/tiers/{tierId}

HTTPcURLJavaScriptPython

DELETE /v1/tiers/{tierId} HTTP/1.1
Host: localhost:8080
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "tierId": "f5cf7e7f-dc78-4f5b-a9d1-1135e10dbf87",
  "fxpId": "FXP-A",
  "sourceCurrency": "EUR",
  "threshold": 50000,
  "improvementBps": 100,
  "createdDateTime": "2026-08-10T14:46:54.897Z",
  "isExpired": true,
  "expiryDateTime": null
}

Count improvement tiers

get

http://localhost:8080https://nexus-ai-simulator-683365449922.asia-southeast1.run.app

/v1/tiers/count

Returns the number of tier records you have configured. Set includeExpired to true to include expired tiers in the count. Requires the scope tiers.read. Used by: FX Providers (FXPs)

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

includeExpiredbooleanOptional

If true, include historical records that were replaced or withdrawn in the last 13 months. Default is false. When true, the limit parameter is required. Note that the word expired in field names is historical naming only; records are never expired based on time.

Default: false

Responses

200

The tier record count.

application/json

A simple record count.

countintegerRequired

The number of records.

Example: 2

400

Invalid request — syntax, schema, or field-level validation failure.

application/json

401

Missing or invalid bearer token.

application/json

403

Caller lacks permission for this resource or operation.

application/json

429

Rate limit exceeded. Returned by the API gateway and carries no structured Nexus body. The Retry-After response header indicates when to retry.

500

Unexpected server fault; caller may retry.

application/json

get/v1/tiers/count

HTTPcURLJavaScriptPython

GET /v1/tiers/count HTTP/1.1
Host: localhost:8080
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "count": 2
}

Get an improvement tier

get

http://localhost:8080https://nexus-ai-simulator-683365449922.asia-southeast1.run.app

/v1/tiers/{tierId}

Returns a single tier record by its id. Requires the scope tiers.read. Used by: FX Providers (FXPs)

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

tierIdstringRequired

UUID of the tier record.

Responses

200

The tier record.

application/json

An improvement tier configured by an FXP for a source currency. A tier applies an improvement in basis points to the base rate for transactions at or above its threshold. Tiers apply to all PSPs equally and remain active until expired.

tierIdstringRequired

Unique ID of the tier record.

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

fxpIdstringRequired

ID of the FXP that owns this tier.

Example: FXP-A

sourceCurrencystringRequired

ISO 4217 currency code of the source currency, three uppercase letters.

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

thresholdnumberRequired

Minimum transaction size, in the source currency, at which the tier applies. Must be greater than 0.

Example: 50000

improvementBpsintegerRequired

Improvement applied to the base rate, in basis points. Must be greater than or equal to 0.

Example: 100

createdDateTimestring · date-timeRequired

Timestamp at which the tier record was created.

isExpiredbooleanRequired

Historical marker set to true when the tier is replaced or withdrawn.

expiryDateTimestring · nullableOptional

Timestamp at which the tier was replaced or withdrawn. A historical marker only.

400

Invalid request — syntax, schema, or field-level validation failure.

application/json

401

Missing or invalid bearer token.

application/json

403

Caller lacks permission for this resource or operation.

application/json

404

Tier not found.

application/json

429

Rate limit exceeded. Returned by the API gateway and carries no structured Nexus body. The Retry-After response header indicates when to retry.

500

Unexpected server fault; caller may retry.

application/json

get/v1/tiers/{tierId}

HTTPcURLJavaScriptPython

GET /v1/tiers/{tierId} HTTP/1.1
Host: localhost:8080
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "tierId": "f5cf7e7f-dc78-4f5b-a9d1-1135e10dbf87",
  "fxpId": "FXP-A",
  "sourceCurrency": "EUR",
  "threshold": 50000,
  "improvementBps": 100,
  "createdDateTime": "2026-08-10T14:46:54.897Z",
  "isExpired": true,
  "expiryDateTime": null
}