Skip to content

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

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

Retrieve Transactions

Request

Retrieves a list of transactions across all accounts given the query parameters provided

Security
OAuth2Flow
Query
pageinteger(int32)

Page of records to get (default 0 = first page)

page_sizeinteger(int32)

Records to return per page (default = 20)

orderstring

Sort order by transaction date (ASC or DESC)

Enum"ASC""DESC"
start_datestring(date)

Filter for transactions from this date

end_datestring(date)

Filter for transactions to this date

account_idstring

Filter transactions by account ID

category_idstring

Filter transactions by category ID

category_typestring

Filter transactions by category type

Enum"ADJUSTMENT""DEPOSIT""EXCHANGE""TRANSFER""WITHDRAWAL"
transaction_statusstring

Filter transactions by transaction status

Enum"AUTHORIZED""PENDING""POSTED""CANCELLED"
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/transactions?page=0&page_size=0&order=ASC&start_date=2019-08-24&end_date=2019-08-24&account_id=string&category_id=string&category_type=ADJUSTMENT&transaction_status=AUTHORIZED' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'x-l2f-request-id: string'

Responses

Success

Bodyapplication/json
dataobject(TransactionList)required
data.​transactionsArray of objects(Transaction)required

Transaction List

data.​transactions[].​idstringrequired

Unique Identifier for the transaction

data.​transactions[].​valuenumberrequired

Value of the transaction in the underlying account currency

data.​transactions[].​transaction_datestring(date-time)required

Date time the transaction was performed

data.​transactions[].​transaction_posted_datestring(date-time)

Date time the transaction was posted

data.​transactions[].​transaction_statusstringrequired

Status of transaction

  • AUTHORIZED - Treat as a temporary hold. This transaction impacts the account available balance but does not impact the current balance. Can and should be cancelled and replaced by a pending/posted pair.
  • PENDING - Transaction waiting final confirmation. This transaction impacts the account available balance but does not impact the current balance. Cannot be cancelled as the underlying transaction is in flight.
  • POSTED - Transaction is final. Both the available balance and current balance are impacted. Cannot be reversed.
  • CANCELLED - Transaction is no longer valid. Reverse any impacts to available balance and current balance.
Enum"AUTHORIZED""PENDING""POSTED""CANCELLED"
data.​transactions[].​transaction_typestringrequired

Transaction type

  • TRANSFER_IN - External deposit of crypto funds into an account.
  • TRANSFER_OUT - Withdrawal of crypto funds from an account to an external location .
  • FIAT_TRANSFER_IN - External deposit of FIAT funds into an account.
  • FIAT_TRANSFER_OUT - Withdrawal of FIAT funds from an account to an external location .
  • FIAT_TRANSFER_IN_RETURN - Clawback of a FIAT deposit (e.g. due to bankiing error).
  • FIAT_TRANSFER_OUT_RETURN - Return of a FIAT withdrawal (e.g. due to the destination account being closed)
  • DEBIT_CORRECTION - Debit account adjustment.
  • CREDIT_CORRECTION - Credit account adjustment.
  • TRADE - Currency exchange transaction (applies to both the debit on the source account or credit on the destination account).
  • FEE - Fee deduction.
  • INTERNAL_TRANSFER - Book (internal) movement of funds between account.
Enum"TRANSFER_IN""TRANSFER_OUT""FEE""DEBIT_CORRECTION""CREDIT_CORRECTION""TRADE""INTERNAL_TRANSFER"
data.​transactions[].​category_typestring

If this transaction related to a core platform feature

  • DEPOSIT - When this transaction was a result of a deposit.
  • EXCHANGE - When this transaction was a result of an exchange.
  • TRANSFER - When this transaction was a result of a transfer.
  • WITHDRAWAL - When this transaction was a result of a withdrawal.
Enum"ADJUSTMENT""DEPOSIT""EXCHANGE""TRANSFER""WITHDRAWAL"
data.​transactions[].​category_idstring

Where the category_type is present, this identifier allows you to lookup the category details using the standard APIs. For example, where a category_type is TRANSFER and the category_id is abc-123, you can lookup the original transfer that this transaction relates to using GET /transfers/abc-123

data.​transactions[].​descriptionstring

Description

data.​transactions[].​originatorobject(TransactionOriginator)

Where the type of transaction is TRANSFER_IN, the available details of the originator of the transaction

data.​transactions[].​rail_informationobject(RailInformation)

Where the type of transaction is TRANSFER_IN, the available details of the originator of the transaction

linksobject(Page)required

See the pagination section for additional details on the generic pagination approach.

links.​selfstringrequired

endpoint to the current page of results

links.​firststringrequired

endpoint to the first page of results

links.​prevstringrequired

endpoint to the previous page of results

links.​nextstringrequired

endpoint to the next page of results

links.​laststringrequired

endpoint to the last page of results

Response
application/json
{
  "data": {
    "transactions": [ … ]
  },
  "links": {
    "self": "string",
    "first": "string",
    "prev": "string",
    "next": "string",
    "last": "string"
  }
}

Retrieve Transaction

Request

Retrieves details of a single transaction

Security
OAuth2Flow
Path
idstringrequired

Transaction 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/transactions/{id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'x-l2f-request-id: string'

Responses

Success

Bodyapplication/json
dataobject(TransactionDetails)required
data.​idstringrequired

Unique Identifier for the transaction

data.​valuenumberrequired

Value of the transaction in the underlying account currency

data.​transaction_datestring(date-time)required

Date time the transaction was performed

data.​transaction_posted_datestring(date-time)

Date time the transaction was posted

data.​transaction_statusstringrequired

Status of transaction

  • AUTHORIZED - Treat as a temporary hold. This transaction impacts the account available balance but does not impact the current balance. Can and should be cancelled and replaced by a pending/posted pair.
  • PENDING - Transaction waiting final confirmation. This transaction impacts the account available balance but does not impact the current balance. Cannot be cancelled as the underlying transaction is in flight.
  • POSTED - Transaction is final. Both the available balance and current balance are impacted. Cannot be reversed.
  • CANCELLED - Transaction is no longer valid. Reverse any impacts to available balance and current balance.
Enum"AUTHORIZED""PENDING""POSTED""CANCELLED"
data.​transaction_typestringrequired

Transaction type

  • TRANSFER_IN - External deposit of crypto funds into an account.
  • TRANSFER_OUT - Withdrawal of crypto funds from an account to an external location .
  • FIAT_TRANSFER_IN - External deposit of FIAT funds into an account.
  • FIAT_TRANSFER_OUT - Withdrawal of FIAT funds from an account to an external location .
  • FIAT_TRANSFER_IN_RETURN - Clawback of a FIAT deposit (e.g. due to bankiing error).
  • FIAT_TRANSFER_OUT_RETURN - Return of a FIAT withdrawal (e.g. due to the destination account being closed)
  • DEBIT_CORRECTION - Debit account adjustment.
  • CREDIT_CORRECTION - Credit account adjustment.
  • TRADE - Currency exchange transaction (applies to both the debit on the source account or credit on the destination account).
  • FEE - Fee deduction.
  • INTERNAL_TRANSFER - Book (internal) movement of funds between account.
Enum"TRANSFER_IN""TRANSFER_OUT""FEE""DEBIT_CORRECTION""CREDIT_CORRECTION""TRADE""INTERNAL_TRANSFER"
data.​category_typestring

If this transaction related to a core platform feature

  • DEPOSIT - When this transaction was a result of a deposit.
  • EXCHANGE - When this transaction was a result of an exchange.
  • TRANSFER - When this transaction was a result of a transfer.
  • WITHDRAWAL - When this transaction was a result of a withdrawal.
Enum"ADJUSTMENT""DEPOSIT""EXCHANGE""TRANSFER""WITHDRAWAL"
data.​category_idstring

Where the category_type is present, this identifier allows you to lookup the category details using the standard APIs. For example, where a category_type is TRANSFER and the category_id is abc-123, you can lookup the original transfer that this transaction relates to using GET /transfers/abc-123

data.​descriptionstring

Description

data.​originatorobject(TransactionOriginator)

Where the type of transaction is TRANSFER_IN, the available details of the originator of the transaction

data.​rail_informationobject(RailInformation)

Where the type of transaction is TRANSFER_IN, the available details of the originator of the transaction

Response
application/json
{
  "data": {
    "id": "string",
    "value": 0,
    "transaction_date": "2019-08-24T14:15:22Z",
    "transaction_posted_date": "2019-08-24T14:15:22Z",
    "transaction_status": "AUTHORIZED",
    "transaction_type": "TRANSFER_IN",
    "category_type": "ADJUSTMENT",
    "category_id": "string",
    "description": "string",
    "originator": { … },
    "rail_information": { … }
  }
}

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.