FXP Rates

Manage FXP exchange rates. Rates are one-directional, identified by source and destination IA account references, and remain live until replaced by a new rate for the same account pair or voluntarily withdrawn. Nexus does not impose time-based expiry on rates; isExpired marks superseded or voluntarily withdrawn records only.

List FXP rates

get

Returns the authenticated FXP's current (live, non-superseded) rates, optionally filtered by currency pair and IPSs. When includeExpired=true, historical rates from the last 13 months are included and limit is required (maximum 100). Nexus does not impose time-based expiry on rates; isExpired marks superseded or voluntarily withdrawn records only.

Required scopes

This endpoint requires the following scopes:

• : Read FXP rate 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 to rates for this source currency.

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

destinationCurrencystring · min: 3 · max: 3Optional

ISO 4217 3-letter destination currency code (uppercase). Filters to rates for this destination currency.

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

sourceIpsstringOptional

Source IPS identifier. Filters to rates where the FXP receives source currency via this IPS.

Example: EURTIPS

destinationIpsstringOptional

Destination IPS identifier. Filters to rates where the FXP pays out destination currency via this IPS.

Example: AUSNPP

includeExpiredbooleanOptional

If true, include historical (withdrawn or superseded) rates 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

Rates retrieved successfully.

application/json

Paginated list of rate records.

cursorstring · nullableOptional

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

Example: eyJwayI6Li4ufQ==

400

Invalid Request

application/json

401

Authentication Failure

application/json

403

Authorization Failure

application/json

405

Method Not Allowed. The HTTP method is not supported for this endpoint. Use the correct HTTP method.

429

Too Many Requests. Rate limit exceeded. The Retry-After header indicates when to retry. Back off and retry after the indicated duration.

500

Internal Server Error

application/json

502

Bad Gateway. The gateway received an invalid response from the upstream service. Retry with exponential backoff. If persistent, escalate.

503

Service Unavailable. The upstream service is temporarily unavailable, for example during rolling deployment. Retry with exponential backoff.

504

Gateway Timeout. The upstream service did not respond within the gateway's timeout window. Retry with exponential backoff.

get/v1/rates

GET /v1/rates HTTP/1.1
Host: localhost:8080
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: application/json

{
  "items": [
    {
      "id": "9929ea23-f29c-4053-b54a-5bf7a1bb348e",
      "fxpId": "FXP-A",
      "sourceIAAccount": {
        "addressTypeCode": "IBAN",
        "fields": {
          "iban": "DE89370400440532013000"
        }
      },
      "destinationIAAccount": {
        "addressTypeCode": "IBAN",
        "fields": {
          "iban": "DE89370400440532013000"
        }
      },
      "sourceCurrency": "EUR",
      "destinationCurrency": "AUD",
      "sourceIps": "EURTIPS",
      "destinationIps": "AUSNPP",
      "rate": 1.5019,
      "createdDateTime": "2024-11-01T10:00:00Z",
      "isExpired": false,
      "expiryDateTime": null
    }
  ],
  "cursor": "eyJwayI6Li4ufQ=="
}

Create or replace a rate

post

Creates a new rate record identified by the FXP's source and destination IA account references. Nexus resolves source currency, destination currency, source IPS, and destination IPS from the IA account records registered for the submitting FXP. If a live rate already exists for the same (sourceIAAccount, destinationIAAccount) pair, Nexus marks the prior record as superseded (isExpired=true — a historical marker, not time-based expiry) and creates the new rate.

Required scopes

This endpoint requires the following scopes:

• : Create or withdraw FXP rate 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 rate.

ratenumber · doubleRequired

Exchange rate: number of destination currency units per one source currency unit.

Example: 1.5019

Responses

200

Rate created successfully. Returns the new rate record.

application/json

A single FXP rate record.

idstring · uuidOptional

Nexus-assigned unique identifier for the rate record.

Example: 9929ea23-f29c-4053-b54a-5bf7a1bb348e

fxpIdstringOptional

Nexus internal identifier for the FXP that owns this rate.

Example: FXP-A

sourceCurrencystring · min: 3 · max: 3Optional

ISO 4217 source currency code resolved from sourceIAAccount.

Example: EUR

destinationCurrencystring · min: 3 · max: 3Optional

ISO 4217 destination currency code resolved from destinationIAAccount.

Example: AUD

sourceIpsstringOptional

Source IPS identifier resolved from sourceIAAccount.

Example: EURTIPS

destinationIpsstringOptional

Destination IPS identifier resolved from destinationIAAccount.

Example: AUSNPP

ratenumber · doubleOptional

The exchange rate.

Example: 1.5019

createdDateTimestring · date-timeOptional

ISO 8601 UTC timestamp when this rate record was created.

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

isExpiredbooleanOptional

If true, this rate has been superseded by a newer rate for the same account pair, or voluntarily withdrawn. Not a time-based expiry.

Example: false

expiryDateTimestring · nullableOptional

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

400

Invalid Request

application/json

401

Authentication Failure

application/json

403

Authorization Failure

application/json

405

Method Not Allowed. The HTTP method is not supported for this endpoint. Use the correct HTTP method.

409

Conflict. The rate could not be created due to a conflicting state.

application/json

429

Too Many Requests. Rate limit exceeded. The Retry-After header indicates when to retry. Back off and retry after the indicated duration.

500

Internal Server Error

application/json

502

Bad Gateway. The gateway received an invalid response from the upstream service. Retry with exponential backoff. If persistent, escalate.

503

Service Unavailable. The upstream service is temporarily unavailable, for example during rolling deployment. Retry with exponential backoff.

504

Gateway Timeout. The upstream service did not respond within the gateway's timeout window. Retry with exponential backoff.

post/v1/rates

POST /v1/rates HTTP/1.1
Host: localhost:8080
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: application/json
Content-Type: application/json
Content-Length: 209

{
  "sourceIAAccount": {
    "addressTypeCode": "IBAN",
    "fields": {
      "iban": "DE89370400440532013000"
    }
  },
  "destinationIAAccount": {
    "addressTypeCode": "AU-BSB",
    "fields": {
      "bsb": "062-000",
      "accountNumber": "12345678"
    }
  },
  "rate": 1.5019
}

{
  "id": "9929ea23-f29c-4053-b54a-5bf7a1bb348e",
  "fxpId": "FXP-A",
  "sourceIAAccount": {
    "addressTypeCode": "IBAN",
    "fields": {
      "iban": "DE89370400440532013000"
    }
  },
  "destinationIAAccount": {
    "addressTypeCode": "IBAN",
    "fields": {
      "iban": "DE89370400440532013000"
    }
  },
  "sourceCurrency": "EUR",
  "destinationCurrency": "AUD",
  "sourceIps": "EURTIPS",
  "destinationIps": "AUSNPP",
  "rate": 1.5019,
  "createdDateTime": "2024-11-01T10:00:00Z",
  "isExpired": false,
  "expiryDateTime": null
}

Get rate count

get

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

Required scopes

This endpoint requires the following scopes:

• : Read FXP rate 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 historical (withdrawn or superseded) rates 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

400

Invalid Request

application/json

401

Authentication Failure

application/json

403

Authorization Failure

application/json

405

Method Not Allowed. The HTTP method is not supported for this endpoint. Use the correct HTTP method.

429

Too Many Requests. Rate limit exceeded. The Retry-After header indicates when to retry. Back off and retry after the indicated duration.

500

Internal Server Error

application/json

502

Bad Gateway. The gateway received an invalid response from the upstream service. Retry with exponential backoff. If persistent, escalate.

503

Service Unavailable. The upstream service is temporarily unavailable, for example during rolling deployment. Retry with exponential backoff.

504

Gateway Timeout. The upstream service did not respond within the gateway's timeout window. Retry with exponential backoff.

get/v1/rates/count

GET /v1/rates/count HTTP/1.1
Host: localhost:8080
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: application/json

{
  "count": 2
}

Withdraw a rate

delete

Voluntarily withdraws a rate by id so it is no longer used to generate quotes for PSPs. Sets isExpired=true and records expiryDateTime as a historical marker — not a time-based expiry. Already-issued quotes remain honoured for the NQVT window (600 seconds). Returns the withdrawn rate record.

Required scopes

This endpoint requires the following scopes:

• : Create or withdraw FXP rate 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

idstring · uuidRequired

UUID of the rate record to withdraw.

Example: 9929ea23-f29c-4053-b54a-5bf7a1bb348e

Header parameters

AcceptstringRequired

application/json

Default: application/jsonExample: application/json

Responses

200

Rate withdrawn successfully. Returns the withdrawn rate record with isExpired=true.

application/json

A single FXP rate record.

idstring · uuidOptional

Nexus-assigned unique identifier for the rate record.

Example: 9929ea23-f29c-4053-b54a-5bf7a1bb348e

fxpIdstringOptional

Nexus internal identifier for the FXP that owns this rate.

Example: FXP-A

sourceCurrencystring · min: 3 · max: 3Optional

ISO 4217 source currency code resolved from sourceIAAccount.

Example: EUR

destinationCurrencystring · min: 3 · max: 3Optional

ISO 4217 destination currency code resolved from destinationIAAccount.

Example: AUD

sourceIpsstringOptional

Source IPS identifier resolved from sourceIAAccount.

Example: EURTIPS

destinationIpsstringOptional

Destination IPS identifier resolved from destinationIAAccount.

Example: AUSNPP

ratenumber · doubleOptional

The exchange rate.

Example: 1.5019

createdDateTimestring · date-timeOptional

ISO 8601 UTC timestamp when this rate record was created.

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

isExpiredbooleanOptional

If true, this rate has been superseded by a newer rate for the same account pair, or voluntarily withdrawn. Not a time-based expiry.

Example: false

expiryDateTimestring · nullableOptional

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

400

Invalid Request

application/json

401

Authentication Failure

application/json

403

Authorization Failure

application/json

404

Rate Not Found

application/json

405

Method Not Allowed. The HTTP method is not supported for this endpoint. Use the correct HTTP method.

429

Too Many Requests. Rate limit exceeded. The Retry-After header indicates when to retry. Back off and retry after the indicated duration.

500

Internal Server Error

application/json

502

Bad Gateway. The gateway received an invalid response from the upstream service. Retry with exponential backoff. If persistent, escalate.

503

Service Unavailable. The upstream service is temporarily unavailable, for example during rolling deployment. Retry with exponential backoff.

504

Gateway Timeout. The upstream service did not respond within the gateway's timeout window. Retry with exponential backoff.

delete/v1/rates/{id}

DELETE /v1/rates/{id} HTTP/1.1
Host: localhost:8080
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: application/json

{
  "id": "9929ea23-f29c-4053-b54a-5bf7a1bb348e",
  "fxpId": "FXP-A",
  "sourceIAAccount": {
    "addressTypeCode": "IBAN",
    "fields": {
      "iban": "DE89370400440532013000"
    }
  },
  "destinationIAAccount": {
    "addressTypeCode": "IBAN",
    "fields": {
      "iban": "DE89370400440532013000"
    }
  },
  "sourceCurrency": "EUR",
  "destinationCurrency": "AUD",
  "sourceIps": "EURTIPS",
  "destinationIps": "AUSNPP",
  "rate": 1.5019,
  "createdDateTime": "2024-11-01T10:00:00Z",
  "isExpired": false,
  "expiryDateTime": null
}