Skip to content
/
Create Deposit

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

Create Deposit

Request

Create a deposit request for a platform account in order to send funds into the account.

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
deposit_typestringrequired

How should the deposit be made. PUSH (manually sent by customer) or PULL (automatically pulled via a linked counterparty using a supported rail). If performing a PULL, several conditions apply.

Conditions:

  • The destination account must be for an asset type that supports pull deposits (e.g. USD, CAD)

  • The source counterparty must be linked and have an available rail that supports ones of the deposit mechanisms on the destination account (e.g. ACH, EFT).

  • The deposit request MUST be accepted using the /deposit/accept endpoint to initiate the pull deposit

Enum"PUSH""PULL"
Discriminator
deposit_destinationobject(DepositDestinationAccount)required

Destination account on platform into which funds will be deposited

deposit_destination.​destination_account_idstringrequired

Destination account ID

customer_namestringrequired

Customer name for whom the deposit was created

curl -i -X POST \
  https://docs.rail.io/_mock/api-docs/openapi/rail-spec/v1/deposits \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'x-l2f-idempotency-id: string' \
  -H 'x-l2f-request-id: string' \
  -d '{
    "deposit_type": "PUSH",
    "deposit_destination": {
      "destination_account_id": "string"
    },
    "customer_name": "string"
  }'

Responses

Success

Bodyapplication/json
One of:
dataobject(DepositPush)required
data.​idstringread-onlyrequired

Unique ID of the deposit instance, to be used to lookup deposit status and historical deposits

data.​statusstringread-onlyrequired

Status of the deposit.

  • REQUESTED - Deposit request is created and deposits can be made.
  • EXECUTED - At least 1 deposit was received and successfully processed.
  • FAILURE - There is a problem or failure with an incoming deposit. View deposit details for more information.
Enum"REQUESTED""EXECUTED""FAILURE"
data.​created_timestampstring(date-time)read-onlyrequired

Time when the deposit request was generated

data.​deposit_typestringrequired

How should the deposit be made. PUSH (manually sent by customer) or PULL (automatically pulled via a linked counterparty using a supported rail). If performing a PULL, several conditions apply.

Conditions:

  • The destination account must be for an asset type that supports pull deposits (e.g. USD, CAD)

  • The source counterparty must be linked and have an available rail that supports ones of the deposit mechanisms on the destination account (e.g. ACH, EFT).

  • The deposit request MUST be accepted using the /deposit/accept endpoint to initiate the pull deposit

Enum"PUSH""PULL"
data.​deposit_destinationobject(DepositDestinationAccount)required

Destination account on platform into which funds will be deposited

data.​deposit_destination.​destination_account_idstringrequired

Destination account ID

data.​deposit_destination.​asset_type_idstringread-onlyrequired

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.​customer_namestringrequired

Customer name for whom the deposit was created

data.​deposit_sourceobject(DepositSource)read-onlyrequired

Instructions of where to send (push) deposits.

data.​deposit_source.​deposit_instructionsArray of objects(Instruction)read-onlyrequired

List of all available deposit instructions for this account. For crypto accounts typically expect a single entry. For FIAT accounts, there may be several entries for each of the supported rails on that account type.

Example: [{"instruction_type":"CRYPTO","address":"0x000121","blockchain":"ETHEREUM","network":"MAINNET","asset_type_id":"ETHEREUM_MAINNET_ETH"},{"instruction_type":"SWIFT","account_holder_name":"string","account_number":"string","account_routing_number":"string","swift_bic":"string","account_holder_address":{"unit_number":"string","address_line1":"string","address_line2":"string","address_line3":"string","city":"string","state":"string","postal_code":"string","country_code":"string"},"institution_name":"string","institution_address":{"unit_number":"string","address_line1":"string","address_line2":"string","address_line3":"string","city":"string","state":"string","postal_code":"string","country_code":"string"},"asset_type_id":"string"},{"instruction_type":"FEDWIRE","account_holder_name":"string","account_number":"string","account_routing_number":"string","account_holder_address":{"unit_number":"string","address_line1":"string","address_line2":"string","address_line3":"string","city":"string","state":"string","postal_code":"string","country_code":"string"},"institution_name":"string","institution_address":{"unit_number":"string","address_line1":"string","address_line2":"string","address_line3":"string","city":"string","state":"string","postal_code":"string","country_code":"string"},"memo":"string","asset_type_id":"string"},{"instruction_type":"ACH","account_holder_name":"string","account_number":"string","account_routing_number":"string","description":"string","asset_type_id":"string"}]
data.​deposit_source.​deposit_instructions[].​instruction_typestringrequired

Type of Instruction

Enum"CRYPTO""ACH""FEDWIRE"
Example: "CRYPTO"
Discriminator
data.​deposit_source.​deposit_instructions[].​addressstringrequired

Issued address for the receipt of funds.

data.​deposit_source.​deposit_instructions[].​blockchainstringrequired

Blockchain the address is issued for use on

data.​deposit_source.​deposit_instructions[].​networkstringrequired

Network (on the target blockchain) that the address is issued for use on

data.​deposit_source.​deposit_instructions[].​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
Response
application/json
{
  "data": {
    "id": "string",
    "status": "REQUESTED",
    "created_timestamp": "2019-08-24T14:15:22Z",
    "deposit_type": "PUSH",
    "deposit_destination": { … },
    "customer_name": "string",
    "deposit_source": { … }
  }
}

Accept Deposit

Request

Accept a Deposit. This is only needed for PULL deposits, PUSH deposits do not need to be accepted. On acceptance, this will initiate the funds pull from the source counterparty. It is not reversible

Security
OAuth2Flow
Path
idstringrequired

Deposit 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.

curl -i -X POST \
  'https://docs.rail.io/_mock/api-docs/openapi/rail-spec/v1/deposits/{deposit_id}/accept' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'x-l2f-idempotency-id: string' \
  -H 'x-l2f-request-id: string' \
  -H 'x-signature: string' \
  -H 'x-timestamp: string'

Responses

Success

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

Unique ID of the deposit instance, to be used to lookup deposit status and historical deposits

data.​statusstringread-onlyrequired

Status of the deposit.

  • REQUESTED - Deposit request is created and deposits can be made.
  • EXECUTED - At least 1 deposit was received and successfully processed.
  • FAILURE - There is a problem or failure with an incoming deposit. View deposit details for more information.
Enum"REQUESTED""EXECUTED""FAILURE"
Response
application/json
{
  "data": {
    "id": "string",
    "status": "REQUESTED"
  }
}

Retrieve Deposit

Request

Retrieves details of a previously requested deposit

Security
OAuth2Flow
Path
idstringrequired

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

Responses

Success

Bodyapplication/json
One of:
dataobject(DepositPush)required
data.​idstringread-onlyrequired

Unique ID of the deposit instance, to be used to lookup deposit status and historical deposits

data.​statusstringread-onlyrequired

Status of the deposit.

  • REQUESTED - Deposit request is created and deposits can be made.
  • EXECUTED - At least 1 deposit was received and successfully processed.
  • FAILURE - There is a problem or failure with an incoming deposit. View deposit details for more information.
Enum"REQUESTED""EXECUTED""FAILURE"
data.​created_timestampstring(date-time)read-onlyrequired

Time when the deposit request was generated

data.​deposit_typestringrequired

How should the deposit be made. PUSH (manually sent by customer) or PULL (automatically pulled via a linked counterparty using a supported rail). If performing a PULL, several conditions apply.

Conditions:

  • The destination account must be for an asset type that supports pull deposits (e.g. USD, CAD)

  • The source counterparty must be linked and have an available rail that supports ones of the deposit mechanisms on the destination account (e.g. ACH, EFT).

  • The deposit request MUST be accepted using the /deposit/accept endpoint to initiate the pull deposit

Enum"PUSH""PULL"
data.​deposit_destinationobject(DepositDestinationAccount)required

Destination account on platform into which funds will be deposited

data.​deposit_destination.​destination_account_idstringrequired

Destination account ID

data.​deposit_destination.​asset_type_idstringread-onlyrequired

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.​customer_namestringrequired

Customer name for whom the deposit was created

data.​deposit_sourceobject(DepositSource)read-onlyrequired

Instructions of where to send (push) deposits.

data.​deposit_source.​deposit_instructionsArray of objects(Instruction)read-onlyrequired

List of all available deposit instructions for this account. For crypto accounts typically expect a single entry. For FIAT accounts, there may be several entries for each of the supported rails on that account type.

Example: [{"instruction_type":"CRYPTO","address":"0x000121","blockchain":"ETHEREUM","network":"MAINNET","asset_type_id":"ETHEREUM_MAINNET_ETH"},{"instruction_type":"SWIFT","account_holder_name":"string","account_number":"string","account_routing_number":"string","swift_bic":"string","account_holder_address":{"unit_number":"string","address_line1":"string","address_line2":"string","address_line3":"string","city":"string","state":"string","postal_code":"string","country_code":"string"},"institution_name":"string","institution_address":{"unit_number":"string","address_line1":"string","address_line2":"string","address_line3":"string","city":"string","state":"string","postal_code":"string","country_code":"string"},"asset_type_id":"string"},{"instruction_type":"FEDWIRE","account_holder_name":"string","account_number":"string","account_routing_number":"string","account_holder_address":{"unit_number":"string","address_line1":"string","address_line2":"string","address_line3":"string","city":"string","state":"string","postal_code":"string","country_code":"string"},"institution_name":"string","institution_address":{"unit_number":"string","address_line1":"string","address_line2":"string","address_line3":"string","city":"string","state":"string","postal_code":"string","country_code":"string"},"memo":"string","asset_type_id":"string"},{"instruction_type":"ACH","account_holder_name":"string","account_number":"string","account_routing_number":"string","description":"string","asset_type_id":"string"}]
data.​deposit_source.​deposit_instructions[].​instruction_typestringrequired

Type of Instruction

Enum"CRYPTO""ACH""FEDWIRE"
Example: "CRYPTO"
Discriminator
data.​deposit_source.​deposit_instructions[].​addressstringrequired

Issued address for the receipt of funds.

data.​deposit_source.​deposit_instructions[].​blockchainstringrequired

Blockchain the address is issued for use on

data.​deposit_source.​deposit_instructions[].​networkstringrequired

Network (on the target blockchain) that the address is issued for use on

data.​deposit_source.​deposit_instructions[].​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
Response
application/json
{
  "data": {
    "id": "string",
    "status": "REQUESTED",
    "created_timestamp": "2019-08-24T14:15:22Z",
    "deposit_type": "PUSH",
    "deposit_destination": { … },
    "customer_name": "string",
    "deposit_source": { … }
  }
}

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

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.