Skip to content
/
Retrieve Exchange

rail API Specification (1.1.2)

Welcome to the rail Developer Guide!

Download OpenAPI description
rail-spec.json
rail-spec.yaml
Languages
Servers
Mock server

https://docs.rail.io/_mock/api-docs/openapi/rail-spec/

Sandbox - Stable API Instance

https://sandbox.layer2financial.com/api/

Production - Stable API Instance

https://platform.layer2financial.com/api/

Applications

Applications represent the onboarding journey for your customers. They are used to collect KYC information and documents required to open accounts on the platform. Visit our guides for a detailed understanding on how to use these APIs.

Operations

Accounts

Accounts are used to hold funds on the platform. Once a customer is onboarded via the application process, you can create accounts for them in various currencies.

Operations

Counterparties

Counterparties represent external entities that you may wish to send or receive funds from. All counterparties are verified to ensure compliance with regulatory requirements prior to being available for use for withdrawals.

Operations

Customers

Customers can only be created via the application process. Once created, customers can have multiple accounts associated with them.

Operations

Deposits

Deposits are used to request instructions for funding platform managed accounts from external sources. A given account may have many deposits associated with it depending on the supported rails and configurations.

Operations

Documents

Document uploading and management functions.

Operations

Exchanges

Exchanges are used to convert funds from one currency to another. This is achieved by moving money between 2 platform accounts that are denominated in different currencies. We have eliminated the complexity of traditional currency trading.

Operations

Accept Exchange

Request

Accept an exchange quote. This will execute the exchange and is not reversible

Security
OAuth2Flow
Path
idstringrequired

Exchange ID

Headers
Authorizationstring

OAuth bearer token (see authentication flows)

x-l2f-request-idstring

Optional Unique ID per request, useful for fault resolution/diagnosis and audit.

x-l2f-idempotency-idstring

Unique ID used to safely retry an operation. See idempotency section for more details.

x-signaturestring

Client signature to validate the provence of the API request. See signing section for more details.

x-timestampstring

Current timestamp, represented AS unix epoch seconds. Mandatory when x-signature is provided.

Bodyapplication/jsonrequired
maximum_slippagenumber

Default value: 0.01

The maximum slippage rail will consider when accepting this order. Defined in bps and represented as a percentage. So 10bps would be presented as 0.001. Must be greater than or equal to 0.

We calculate slippage based on the quote you are accepting. While the slippage may not always be used, it is there to ensure a better completion/fill rate with our market makers.

Where the quote cannot be fulfilled within the slippage tolerance, the exchange response status will be CANCELLED.

curl -i -X POST \
  'https://docs.rail.io/_mock/api-docs/openapi/rail-spec/v1/exchanges/{exchange_id}/accept' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'x-l2f-idempotency-id: string' \
  -H 'x-l2f-request-id: string' \
  -H 'x-signature: string' \
  -H 'x-timestamp: string' \
  -d '{
    "maximum_slippage": 0
  }'

Responses

Success

Bodyapplication/json
dataobject(Exchange)required
data.​idstringread-onlyrequired

Unique ID of the exchange request

data.​statusstringread-onlyrequired

Status of the Exchange. Cannot be modified directly by the client.

  • REQUESTED - Exchange request is created and has passed validation. It must be accepted at which point it will be executed.
  • ACCEPTED - Exchange request has been accepted and is waiting execution. At this point it cannot be cancelled.
  • EXPIRED - Occurs when an exchange request was not accepted within a reasonable time frame. The exchange cannot be replayed from this state.
  • CANCELLED - Exchange request was cancelled. Only available prior to acceptance. The exchange request cannot be replayed from this state.
  • EXECUTED - Exchange request has been executed, it is completed with all ledger entries performed.
  • REJECTED - Exchange request was rejected and cannot be executed.
Enum"REQUESTED""ACCEPTED""EXPIRED""CANCELLED""EXECUTED""REJECTED"
data.​created_timestampstring(date-time)required

Time when the exchange request was generated

data.​exchange_typestringread-onlyrequired

The type of exchange being performed.

Enum"MARKET""QUOTE"
data.​actionstringrequired

The action defines which side of the exchange to fix.

  • FIX_DESTINATION - This fixes the amount to credit to the DESTINATION account, therefore the quote provided is for how much to deduct from the SOURCE account. Think of this as 'buying' the destination amount.
  • FIX_SOURCE - This fixes the amount you want to debit from the SOURCE account, therefore the quote provided is for how much would be credited to the DESTINATION account. Think of this as 'selling' the source amount.
Enum"FIX_DESTINATION""FIX_SOURCE"
data.​source_detailsobject(TransferSourceAccount)required

Details of transaction to be performed on the source account on acceptance

data.​source_details.​source_account_idstringrequired

Source account ID

data.​source_details.​asset_type_idstring

Asset type IDs follow a simple structure as follows: {$BLOCKCHAIN}_{$NETWORK}_{$CURRENCY_CODE} Simple asset type to test with include.

  • ETHEREUM_SEPOLIA_ETH
  • ETHEREUM_SEPOLIA_USDC
  • SOLANA_DEVNET_SOL
  • BITCOIN_TESTNET_BTC
  • FIAT_TESTNET_USD
  • FIAT_TESTNET_USD
  • FIAT_MAINNET_USD
  • FIAT_TESTNET_EUR
data.​source_details.​amount_to_debitnumberrequired

Amount that will be debited from the source account

data.​destination_detailsobject(TransferDestinationAccount)required

Details of transaction to be performed on the destination account on acceptance

data.​destination_details.​destination_account_idstringrequired

Destination account ID

data.​destination_details.​asset_type_idstring

Asset type IDs follow a simple structure as follows: {$BLOCKCHAIN}_{$NETWORK}_{$CURRENCY_CODE} Simple asset type to test with include

  • ETHEREUM_SEPOLIA_ETH
  • ETHEREUM_SEPOLIA_USDC
  • SOLANA_DEVNET_SOL
  • BITCOIN_TESTNET_BTC
  • FIAT_TESTNET_USD
  • FIAT_TESTNET_USD
  • FIAT_MAINNET_USD
  • FIAT_TESTNET_EUR
data.​destination_details.​amount_to_creditnumberrequired

Amount that will be credited to the destination account

Response
application/json
{
  "data": {
    "id": "string",
    "status": "REQUESTED",
    "created_timestamp": "2019-08-24T14:15:22Z",
    "exchange_type": "MARKET",
    "action": "FIX_DESTINATION",
    "source_details": { … },
    "destination_details": { … }
  }
}

Create Exchange (Market)

Request

When requesting a market exchange, the quote received is indicative ONLY. This represents an approximate rate from our liquidity providers. On accepting a market exchange the trade is performed at the current market rate which will be different to the quote presented to you.

Note: Not all custodians support all order types. Where the order type is not possible (Quote/Market/Fix Destination/ Fix Source) an error will be returned.

Security
OAuth2Flow
Headers
Authorizationstring

OAuth bearer token (see authentication flows)

x-l2f-request-idstring

Optional Unique ID per request, useful for fault resolution/diagnosis and audit.

x-l2f-idempotency-idstring

Unique ID used to safely retry an operation. See idempotency section for more details.

Bodyapplication/jsonrequired
source_account_idstringrequired

Source account from which funds will be withdrawn

destination_account_idstringrequired

Destination account where funds will be deposited

amountnumberrequired

The amount to be exchanged depending on the the action.

actionstringrequired

Type of exchange being performed.

  • FIX_DESTINATION - This fixes the amount to credit to the DESTINATION account, therefore the quote provided is for how much to deduct from the SOURCE account. Think of this as 'buying' the destination amount.
  • FIX_SOURCE - This fixes the amount you want to debit from the SOURCE account, therefore the quote provided is for how much would be credited to the DESTINATION account. Think of this as 'selling' the source amount.
Enum"FIX_DESTINATION""FIX_SOURCE"
descriptionstring

(Optional) Description of the transaction

curl -i -X POST \
  https://docs.rail.io/_mock/api-docs/openapi/rail-spec/v1/exchanges/market \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'x-l2f-idempotency-id: string' \
  -H 'x-l2f-request-id: string' \
  -d '{
    "source_account_id": "string",
    "destination_account_id": "string",
    "amount": 0,
    "action": "FIX_DESTINATION",
    "description": "string"
  }'

Responses

Success

Bodyapplication/json
dataobject(Exchange)required
data.​idstringread-onlyrequired

Unique ID of the exchange request

data.​statusstringread-onlyrequired

Status of the Exchange. Cannot be modified directly by the client.

  • REQUESTED - Exchange request is created and has passed validation. It must be accepted at which point it will be executed.
  • ACCEPTED - Exchange request has been accepted and is waiting execution. At this point it cannot be cancelled.
  • EXPIRED - Occurs when an exchange request was not accepted within a reasonable time frame. The exchange cannot be replayed from this state.
  • CANCELLED - Exchange request was cancelled. Only available prior to acceptance. The exchange request cannot be replayed from this state.
  • EXECUTED - Exchange request has been executed, it is completed with all ledger entries performed.
  • REJECTED - Exchange request was rejected and cannot be executed.
Enum"REQUESTED""ACCEPTED""EXPIRED""CANCELLED""EXECUTED""REJECTED"
data.​created_timestampstring(date-time)required

Time when the exchange request was generated

data.​exchange_typestringread-onlyrequired

The type of exchange being performed.

Enum"MARKET""QUOTE"
data.​actionstringrequired

The action defines which side of the exchange to fix.

  • FIX_DESTINATION - This fixes the amount to credit to the DESTINATION account, therefore the quote provided is for how much to deduct from the SOURCE account. Think of this as 'buying' the destination amount.
  • FIX_SOURCE - This fixes the amount you want to debit from the SOURCE account, therefore the quote provided is for how much would be credited to the DESTINATION account. Think of this as 'selling' the source amount.
Enum"FIX_DESTINATION""FIX_SOURCE"
data.​source_detailsobject(TransferSourceAccount)required

Details of transaction to be performed on the source account on acceptance

data.​source_details.​source_account_idstringrequired

Source account ID

data.​source_details.​asset_type_idstring

Asset type IDs follow a simple structure as follows: {$BLOCKCHAIN}_{$NETWORK}_{$CURRENCY_CODE} Simple asset type to test with include.

  • ETHEREUM_SEPOLIA_ETH
  • ETHEREUM_SEPOLIA_USDC
  • SOLANA_DEVNET_SOL
  • BITCOIN_TESTNET_BTC
  • FIAT_TESTNET_USD
  • FIAT_TESTNET_USD
  • FIAT_MAINNET_USD
  • FIAT_TESTNET_EUR
data.​source_details.​amount_to_debitnumberrequired

Amount that will be debited from the source account

data.​destination_detailsobject(TransferDestinationAccount)required

Details of transaction to be performed on the destination account on acceptance

data.​destination_details.​destination_account_idstringrequired

Destination account ID

data.​destination_details.​asset_type_idstring

Asset type IDs follow a simple structure as follows: {$BLOCKCHAIN}_{$NETWORK}_{$CURRENCY_CODE} Simple asset type to test with include

  • ETHEREUM_SEPOLIA_ETH
  • ETHEREUM_SEPOLIA_USDC
  • SOLANA_DEVNET_SOL
  • BITCOIN_TESTNET_BTC
  • FIAT_TESTNET_USD
  • FIAT_TESTNET_USD
  • FIAT_MAINNET_USD
  • FIAT_TESTNET_EUR
data.​destination_details.​amount_to_creditnumberrequired

Amount that will be credited to the destination account

Response
application/json
{
  "data": {
    "id": "string",
    "status": "REQUESTED",
    "created_timestamp": "2019-08-24T14:15:22Z",
    "exchange_type": "MARKET",
    "action": "FIX_DESTINATION",
    "source_details": { … },
    "destination_details": { … }
  }
}

Retrieve Exchange

Request

Retrieves details of a previously requested exchange

Security
OAuth2Flow
Path
idstringrequired

Exchange ID

Headers
Authorizationstring

OAuth bearer token (see authentication flows)

x-l2f-request-idstring

Optional Unique ID per request, useful for fault resolution/diagnosis and audit.

curl -i -X GET \
  'https://docs.rail.io/_mock/api-docs/openapi/rail-spec/v1/exchanges/{exchange_id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'x-l2f-request-id: string'

Responses

Success

Bodyapplication/json
dataobject(Exchange)required
data.​idstringread-onlyrequired

Unique ID of the exchange request

data.​statusstringread-onlyrequired

Status of the Exchange. Cannot be modified directly by the client.

  • REQUESTED - Exchange request is created and has passed validation. It must be accepted at which point it will be executed.
  • ACCEPTED - Exchange request has been accepted and is waiting execution. At this point it cannot be cancelled.
  • EXPIRED - Occurs when an exchange request was not accepted within a reasonable time frame. The exchange cannot be replayed from this state.
  • CANCELLED - Exchange request was cancelled. Only available prior to acceptance. The exchange request cannot be replayed from this state.
  • EXECUTED - Exchange request has been executed, it is completed with all ledger entries performed.
  • REJECTED - Exchange request was rejected and cannot be executed.
Enum"REQUESTED""ACCEPTED""EXPIRED""CANCELLED""EXECUTED""REJECTED"
data.​created_timestampstring(date-time)required

Time when the exchange request was generated

data.​exchange_typestringread-onlyrequired

The type of exchange being performed.

Enum"MARKET""QUOTE"
data.​actionstringrequired

The action defines which side of the exchange to fix.

  • FIX_DESTINATION - This fixes the amount to credit to the DESTINATION account, therefore the quote provided is for how much to deduct from the SOURCE account. Think of this as 'buying' the destination amount.
  • FIX_SOURCE - This fixes the amount you want to debit from the SOURCE account, therefore the quote provided is for how much would be credited to the DESTINATION account. Think of this as 'selling' the source amount.
Enum"FIX_DESTINATION""FIX_SOURCE"
data.​source_detailsobject(TransferSourceAccount)required

Details of transaction to be performed on the source account on acceptance

data.​source_details.​source_account_idstringrequired

Source account ID

data.​source_details.​asset_type_idstring

Asset type IDs follow a simple structure as follows: {$BLOCKCHAIN}_{$NETWORK}_{$CURRENCY_CODE} Simple asset type to test with include.

  • ETHEREUM_SEPOLIA_ETH
  • ETHEREUM_SEPOLIA_USDC
  • SOLANA_DEVNET_SOL
  • BITCOIN_TESTNET_BTC
  • FIAT_TESTNET_USD
  • FIAT_TESTNET_USD
  • FIAT_MAINNET_USD
  • FIAT_TESTNET_EUR
data.​source_details.​amount_to_debitnumberrequired

Amount that will be debited from the source account

data.​destination_detailsobject(TransferDestinationAccount)required

Details of transaction to be performed on the destination account on acceptance

data.​destination_details.​destination_account_idstringrequired

Destination account ID

data.​destination_details.​asset_type_idstring

Asset type IDs follow a simple structure as follows: {$BLOCKCHAIN}_{$NETWORK}_{$CURRENCY_CODE} Simple asset type to test with include

  • ETHEREUM_SEPOLIA_ETH
  • ETHEREUM_SEPOLIA_USDC
  • SOLANA_DEVNET_SOL
  • BITCOIN_TESTNET_BTC
  • FIAT_TESTNET_USD
  • FIAT_TESTNET_USD
  • FIAT_MAINNET_USD
  • FIAT_TESTNET_EUR
data.​destination_details.​amount_to_creditnumberrequired

Amount that will be credited to the destination account

Response
application/json
{
  "data": {
    "id": "string",
    "status": "REQUESTED",
    "created_timestamp": "2019-08-24T14:15:22Z",
    "exchange_type": "MARKET",
    "action": "FIX_DESTINATION",
    "source_details": { … },
    "destination_details": { … }
  }
}

Payments

Payments are used to orchestrate end to end payment flows from external parties or from within the platform.

Operations

Transactions

Transactions are created to record the movement of funds between accounts. The transactions endpoint allows the bulk retrieval of transaction data for reconciliation and reporting purposes.

Operations

Transfers

Transfer are used to move funds between two platform managed accounts that are denominated in the same currency.

Operations

Withdrawals

Move funds from a platform managed account to an external counterparty via supported rails.

Operations

Settlements

Settlement services for funds confirmation and reconciliation. Settlements are a deprecated concept and will be removed in future versions of the API. Please use Payments for all new integrations.

Operations

Subscriptions (Webhooks)

Manage your callback (webhook) subscriptions. Subscriptions allow you to receive real-time notifications of events that occur within your platform instance. Visit the guides for a full breakdown of all available events.

Operations
© 2026 Rail. All Rights Reserved.