Part of the FX Service. Used by FXPs.

Using the Nexus APIs

Nexus provides three APIs to FX Providers:

  • POST /rates/ - to issue new rates

  • POST /improvements/tiers/ - to register or update a tier-based improvement for a specific currency

  • POST /improvements/psps/ - to register or update an improvement for a specific PSP

In a production system, APIs would also be provided to allow to see FXP to “delete” or withdraw PSP-based and tier-based improvements. Rates could be withdrawn / expired by an FXP, but this is equivalent to the FXP exiting the market and should only be used in certain circumstances.

Posting a new rate

An FXP will submit a new rate using the Rates API. Note: FXPs cannot update existing rates; instead they simply submit a new rate that takes effect immediately.

Post a new rate

POST https://local.nexus.gateway/api/v1/rates

Request Body




The Source Currency (ISO 4217 alpha-3)



Destination Currency (ISO 4217 alpha-3)



Decimal, 4 decimal places



The Source UPS where the FXP holds an account (either directly or via a SAP)



The Destination UPS where the FXP holds an account (either directly or via a SAP)

    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "fxpId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "unitCcy": "string",
    "qtdCcy": "string",
    "rate": 1.5000,
    "sourceUPS": "string",
    "destUPS": "string",
    "marketRate": 1.5020

When processing the rate update request, Nexus will:

  • validate the request (by checking that the FX Provider is set up to rate for that currency pair and has nominated validated Settlement Account Providers in both the Source and Destination Country)

  • save the new rate in the rates table

  • set any existing rates for this FXP-corridor combination to expire immediately

  • retrieve any tier-based improvements set by the FXP for this Source Currency

    • for each tier, calculate the improved rate

    • save a new rate in the rates table with the threshold defined in this tier and the new improved rate

The new rate is immediately shown to Source PSPs when they use the GET /rates/ API (alongside rates for that corridor from other FXPs).

Response to POST /rates/

The Nexus Gateway will send a response message to the FX Provider to confirm that a rate has been successfully accepted and saved. The response message includes the newly created quote.

The response message also includes the current best available rate on the market (but not the identity of the FX Provider offering that rate). This allows each FX Provider to see whether the rates they offer are competitive, and to adjust those rates if necessary.

FXPs are NOT permitted to use the GET Rate API to see the full list of rates offered by their competitors; this will be enforced by both API permissions and the Nexus scheme rulebook.

Setting tier-based improvements for larger transactions

FXPs can set tier-based improvements using the API:

Post a new tier improvement

POST https://local.nexus.gateway/api/v1/tier_improvements

Allows an FXP to set a new tier improvement for a specific Source Currency

Request Body




Source Currency to which this tier improvement applies



Minimum value at which a payment will qualify for this tier improvement (Payment must be equal or greater than the threshold)



Improvement to add to the base rate in basis points

    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "unitCcy": "SGD",
    "threshold": 50000.00
    "improvement": 50,
    "fxpId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"

Each tier-based improvement must specify:

  • FXP Id – the FXP offering the improvement

  • UnitCcy – the Source Currency to which the improvement applies. (Tier-based improvements are always based on the Source Currency, not the Destination Currency)

  • Threshold – the smallest amount, in the Source Currency, at which the improvement rate applies. The Source Currency Amount of the payment must be greater than or equal to the threshold.

  • Improvement – a rate of improvement, recorded in basis points, which should be applied to the base rate.

For transaction values below the lowest threshold, the base rate provided by the FXP in POST /rates/ applies.

APIs to delete or “revoke” tier-based improvements have not yet been built and would need to be added to a production version.

Setting PSP-based improvements for specific PSPs

FXPs can improvements for specific PSPs using the API below.

PSP-specific improvements are additional to any tier-based improvements. (Nexus calculates relevant tier-based improvements first, then applies any PSP-based improvements.)

A PSP-specific improvement needs to specify:

  • FXP Id – the FXP offering the improvement to a PSP

  • PSP Id – the PSP to which the improvement is being offered

  • Improvement – the improvement, in basis points, which should be applied to any rate offered by this PSP.

Post a new PSP improvement

POST http://local.nexus.gateway/api/v1/psp_improvements

Alllows an FX Provider to post a new improvement for a specific PSP. The improvement will apply to all quotes issued to that PSP, for all currencies that the FXP offers.

Request Body






BIC, LEI or Other



Id of the PSP



Improvement in basis points to add to the base rate

    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "fxpId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "pspIdType": "BIC",
    "pspId": "CCCCSGCC",
    "improvement": 100

APIs to delete or “revoke” PSP-specific improvements have not yet been built.

Receiving notifications of completed payments

Whenever Nexus successfully processes a payment (ie. receives a pacs.002 with a “ACCC” status code from the Destination IPS), it will send a notification to FX Provider whose rate was referenced. This notification should be used by the FXP to update its internal records of the balances of all its settlement accounts.

The FXP will provide the API endpoints or message queue to which these notifications should be sent during technical onboarding to Nexus.

This notification is structured as an ISO 20022 fxtr.017 message. The key elements of the fxtr.017 are described below:

ISO 20022 fxtr.017 ELEMENT



ID of the underlying Nexus payment that made use of the FXP’s quote


ID of the quote issued by Nexus to the PSP




  • SubmittingParty

BIC of the Source PSP


  • SubmittingParty

BIC of the FXP


  • TradingSideBuyAmount

Amount in target/destination currency that was transferred from the FXP’s account to the Destination PSP via the Destination IPS

  • TradingSideSellAmount

Amount in source currency that the Source PSP paid to the FXP’s account via the Source IPS


  • ExchangeRate

Exchange rate applied (from the original quote, after any tier-improvements or PSP-based improvements have been added)

  • UnitCurrency

Source Currency

  • QuotedCurrency

Destination/Target Currency


  • DeliveryAgent

BIC of the Destination Settlement Account provider and the account number of the FXP’s account at the SAP

  • ReceivingAgent

BIC of the Destination PSP


  • DeliveryAgent

BIC of the Source PSP

  • ReceivingAgent

BIC of the Source Settlement Account Provider and the account number of the FXP’s account at the SAP

A production version of Nexus would also include the ability for FXPs to generate aggregate reports on all transactions for which they provided FX in a certain time period. These reports would also include a breakdown of the calculation of the final rate, showing how the base rate, any tier improvements and any PSP improvements were applied to each quote. This functionality has not yet been built.

Last updated