FX Transaction Lifecycle

Each FX trade follows a defined lifecycle from execution to settlement. Understanding these stages helps you track and manage your trades effectively.

Transaction States

All FX trades follow a standard lifecycle with the following possible states:

1. Open: State for trades with future value dates or without immediate settlement - including those with immediate settlement submitted during our nightly end-of-day processing period.
2. Settled: State for completed trades where funds have been debited and credited
3. Cancelled: State for cancelled trades (only applicable in specific scenarios)

State Transitions

The lifecycle progression depends on the settlement timing:

• Immediate Settlement (value date today):
  Settled -> (Cancelled, if applicable)

• Future Settlement (value date in future):
  Open -> Settled -> (Cancelled, if applicable)

Example Scenario

Consider a SPOT trade to buy 10,000 EUR against USD:

1. Immediately after execution: Status will be "Open" (settlement occurs in two banking days)
2. On/after settlement date: Status changes to "Settled" (funds are debited/credited to respective currency accounts)

Interpreting the BookingStatus and TransactionStatus fields

Once you submit an FX trade that Banking Circle accepts, you will immediately receive a trade confirmation with trade status marked as Filled. This indicates that Banking Circle has accepted your trade and will book it into our system at soonest possibility - usually within the same second.

However, it is not always possible for Banking Circle to immediately book the trade into our core banking system for settlement, for example during our nightly end-of-day processing period.

At this time, the transaction is visible in our API and the UI. The field BookingStatus indicates whether or not the trade has been booked for settlement on our side.

Success indicates that the trade has entered our core banking system. The TransactionStatus will therefore either appear as Settled, if the trade has been debited/credited, or Open, as described above.

Pending indicates that the trade is currently queued up for booking into our core banking system. Banking Circle is tracking this trade, and will enter it into our core banking system so as soon as it is technically possible. During this period, TransactionStatus will appear as Open.

Reversed or Rolled: in rare cases, a trade may have been cancelled (for example at your request), or rolled to a new trade (at your request).

Tracking FX Trades

Our API provides several endpoints to help you track and manage your FX trades throughout their lifecycle.

Trade History and Status

List All Trades

Query your trade history using one of these endpoints:

• JSON Format: GET /api/v2/fx/transactions

  Text

  GET /api/v2/fx/transactions?clientOrderId=YourUniqueReference

  Returns a JSON response with trade details including status, amounts, and settlement accounts.

• CSV Format: GET /api/v1/fx/reports/transactions
  Same data as above but in CSV format, useful for bulk analysis or reporting.

Single Trade Lookup

Get details of a specific trade:

• GET /api/v2/fx/transactions/{client-order-id}
  Returns detailed information about a single trade identified by your reference.

Active Trades and Rates

• GET /api/v2/fx/held-rates
  Lists all currently active held rates available for trading.

Settlement Information

• GET /api/v1/fx/calendar/settlement-dates
  Returns available settlement dates for FX trades, accounting for holidays and cut-off times.

• GET /api/v1/fx/settlement-accounts
  Lists accounts available for FX trading and settlement.

Risk Management

• GET /api/v1/fx/exposure/customer/{customer-id}
  Returns FX exposure information for a specific customer, including:
  • Trading line details
  • Collateral account information

Filtering Options

When querying trade history, many of the endpoints support filters to narrow down the results, such as:

• Date ranges
• Account information
• Currencies involved
• Transaction status

Refer to our API Reference section for a complete list of filtering criteria.

Note: Multicurrency Payments are tracked separately through payment endpoints, as they are considered payments rather than FX trades.