Wallet Guide

This guide will help you create a wallet, manage balances, and perform basic operations using the API.

1. Creating a New Account

Step 1.1: Sending a Request to Create an Account

To create a new account, send a request to the POST /wallet/account endpoint.

In the request, specify the following parameters:

shortName: a short name or identifier for your account.
accountType: the type of account (e.g., CHECKING).
currency: the currency associated with the account.
blockchain: the blockchain platform associated with the account.

Example request:

{
  "shortName": "bank test",  // a short name or identifier for the account.
  "accountType": "CHECKING",  // the type of the account, e.g., checking, savings.
  "currency": "USD",  // the currency code associated with the account, e.g., US Dollar.
  "blockchain": "btc"  // the blockchain platform associated with the account, e.g., Bitcoin (BTC).
}

Example response:

{
  "account": "4adb69c1-9cfa-4341-b9f0-a725c7b86c87",  // unique identifier for the account.
  "accountType": "CHECKING",  // type of the account, e.g., checking, savings.
  "shortName": "bank test",  // a short name or identifier for the account.
  "status": "ACTIVE"  // current status of the account.
}

You will receive a unique account identifier (accountId) in the response, which you will need for further actions.

2. Checking Balance

Step 2.1: Checking Account Balance

To get the current balance of your account, send a request to the GET /wallet/balance endpoint.

Specify the following parameters in the request:

accountId: the unique identifier of your account.
currency: the currency for which you want to check the balance.

Example request:

GET /wallet/balance?accountId=4adb69c1-9cfa-4341-b9f0-a725c7b86c87&currency=USD

Example response:

[
  {
    "account": "4adb69c1-9cfa-4341-b9f0-a725c7b86c87",  // unique identifier for the account.
    "balance": "100.00",  // current balance of the account.
    "currency": "USD",  // currency code for the balance, e.g., US Dollar.
    "lastUpdated": "2024-08-22T13:05:59.437Z"  // timestamp of the last update to the balance.
  }
]

You will receive the current balance in the specified currency.

Step 2.2: Getting Balance Change History

To get the transaction history related to the balance (e.g., deposits, withdrawals), use the GET /wallet/balance/log/{logId} endpoint.

Example request:

GET /balance/logs/4adb69c1-9cfa-4341-b9f0-a725c7b86c87

Example response:

{
  "id": "string",  // unique identifier for the transaction.
  "account": "3fa85f64-5717-4562-b3fc-2c963f66afa6",  // identifier for the account associated with the change.
  "change": "9.87",  // amount of the balance change in the specified currency.
  "currency": "EPI",  // currency code in which the change occurred.
  "createdAt": "2024-08-22T13:05:59.437Z",  // date and time when the transaction was created.
  "reasonId": "string",  // identifier for the reason of the transaction (e.g., order, refund).
  "reasonType": "ORDER",  // type of the reason for the transaction (e.g., ORDER for an order).
  "note": "string",  // additional notes or comments regarding the transaction.
  "receipt": {
    "note": "string",  // note associated with the receipt.
    "rail": "string",  // railway identifier (if applicable).
    "rail_reference": "string",  // reference to the railway identifier.
    "purpose": "string",  // purpose of the transaction.
    "memo": "string",  // memorial note.
    "originator_name": "string",  // name of the originator of the funds.
    "originator_address": "string",  // address of the originator.
    "originator_blockchain_address": "string",  // blockchain address of the originator (if applicable).
    "originator_blockchain_network": "string",  // blockchain network of the originator (if applicable).
    "originator_account_number": "string",  // account number of the originator.
    "originator_routing_number": "string",  // routing number of the originator.
    "originator_swift_bic": "string",  // SWIFT/BIC code of the originator.
    "originator_institution_name": "string",  // name of the originator's institution.
    "originator_institution_address": "string",  // address of the originator's institution.
    "exchange_type": "string",  // type of exchange (if applicable).
    "exchange_source_account_id": "string",  // identifier of the source exchange account.
    "exchange_destination_account_id": "string",  // identifier of the destination exchange account.
    "exchange_amount_debit": "string",  // debit amount of the exchange.
    "exchange_amount_credit": "string",  // credit amount of the exchange.
    "counterparty_name": "string",  // name of the counterparty.
    "counterparty_address": "string",  // address of the counterparty.
    "counterparty_blockchain_address": "string",  // blockchain address of the counterparty (if applicable).
    "counterparty_blockchain_network": "string",  // blockchain network of the counterparty (if applicable).
    "counterparty_account_number": "string",  // account number of the counterparty.
    "counterparty_routing_number": "string",  // routing number of the counterparty.
    "counterparty_swift_bic": "string",  // SWIFT/BIC code of the counterparty.
    "counterparty_institution_name": "string",  // name of the counterparty's institution.
    "counterparty_institution_address": "string",  // address of the counterparty's institution.
    "tranfer_source_account_id": "string",  // identifier of the source transfer account.
    "tranfer_destination_account_id": "string",  // identifier of the destination transfer account.
    "tranfer_amount_debit": "string",  // debit amount of the transfer.
    "tranfer_amount_credit": "string"  // credit amount of the transfer.
  }
}

3. Managing Transfers

Step 3.1: Transferring Funds

To transfer funds between accounts, send a request to the POST /wallet/transfer endpoint.

Specify the sender and receiver account IDs, the transfer amount, currency, and the type of transfer:

INVOICE: Parameters for a transfer associated with invoicing. Use this type when the transfer is linked to a specific invoice.
PAYMENT: Parameters for a standard transfer between accounts. Choose this type for a standard transfer without invoice association.
CORRECTION: Parameters for correcting a previously made transfer. Use this type if you need to amend an error or make changes to a completed transfer.

Example request:

{
  "fromAccountId": "4adb69c1-9cfa-4341-b9f0-a725c7b86c87",  // identifier for the source account from which the funds are being transferred.
  "toAccountId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",  // identifier for the destination account to which the funds are being transferred.
  "amount": "50.00",  // amount of funds being transferred.
  "currency": "USD"  // currency code for the transaction, e.g., US Dollar.
}

Example response:

{
  "transactionId": "tx12347",  // unique identifier for the transaction.
  "status": "COMPLETED",  // current status of the transaction, e.g., COMPLETED.
  "date": "2024-08-22T14:05:00.000Z",  // date and time when the transaction was completed.
  "amount": "50.00",  // amount involved in the transaction.
  "currency": "USD"  // currency code for the transaction, e.g., US Dollar.
}

You will receive information about the transaction status and details.

Step 3.2: Confirming the Transfer

Once the transfer is created, you need to confirm it. To do this, send a request to the POST /wallet/transfer/{uuid}/confirm endpoint, where {uuid} is the transaction ID received in the transfer creation response.

Request parameters:

uuid: the unique identifier of the transfer obtained from the transfer creation response.

Example request:

POST /wallet/transfer/tx12347/confirm

Example response:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", // unique identifier for the transfer.
  "fromAccount": "4adb69c1-9cfa-4341-b9f0-a725c7b86c87", // identifier of the sender's account.
  "toAccount": "3fa85f64-5717-4562-b3fc-2c963f66afa6", // identifier of the recipient's account.
  "currency": "USD", // currency of the transfer.
  "amount": "50.00", // amount of the transfer.
  "status": "INIT", // status of the transfer (e.g., INIT for initialized transfer).
  "statusDescription": "string", // description of the transfer status.
  "note": "string", // additional notes.
  "createdAt": "2024-08-22T13:05:59.437Z", // date and time when the transfer was created.
  "updatedAt": "2024-08-22T13:05:59.437Z", // date and time when the transfer was last updated.
  "type": "ORIGINAL" // type of the transfer (e.g., ORIGINAL).
}

Step 3.3: Checking Transfer Status

To check the status of a transfer, send a request to the GET /wallet/transfer/{uuid} endpoint, where {uuid} is the unique identifier of the transfer.

Example request:

GET /transfer/tx12347

Example response:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", // unique identifier for the transfer.
  "fromAccount": "string", // identifier of the sender's account.
  "toAccount": "string", // identifier of the recipient's account.
  "currency": "USD", // currency of the transfer.
  "amount": "10.2", // amount of the transfer.
  "status": "INIT", // status of the transfer (e.g., INIT for initialized transfer).
  "statusDescription": "string", // description of the transfer status.
  "note": "string", // additional notes.
  "createdAt": "2024-08-22T13:05:59.437Z", // date and time when the transfer was created.
  "updatedAt": "2024-08-22T13:05:59.437Z", // date and time when the transfer was last updated.
  "type": "ORIGINAL" // type of the transfer (e.g., ORIGINAL).
}

4. Managing Withdrawals

Step 4.3: Retrieving Withdrawal Limits

To check the current withdrawal limits, send a request to the GET /wallet/utils/limits endpoint.

Example request:

GET /wallet/utils/limits

Example response:

{
  "withdrawDay": 0, // daily withdrawal limit.
  "withdrawMonth": 0, // monthly withdrawal limit.
  "withdrawYear": 0, // annual withdrawal limit.
  "withdrawGlobal": 0, // global withdrawal limit.
  "currency": "string" // currency code to which the limits apply.
}

Step 4.2: Withdrawing Funds

To withdraw funds to a bank account, send a request to the POST /wallet/withdraw endpoint. Specify the currency code, the amount to withdraw, and select the type of withdrawal.

Available withdrawal types:

ATM: Withdraw funds via an ATM.
BANK_TRANSFER: Bank transfer.
CRYPTO: Cryptocurrency transfer.
PAY_SPOT: Transfer through a payment system.
COUNTERPARTY: Transfer to a third party.

Example request:

{
  "currency": "USD", // the currency code for the withdrawal.
  "amount": "10.2", // the amount of funds to withdraw.
  "conversion": [ // (optional) details of currency conversion, if needed.
    {
      "amount": "1.12", // the amount of funds to be converted.
      "currency": "EUR", // the currency code to which the conversion is applied.
      "rate": { // information about the conversion rate.
        "rateRequest": { // the request for the conversion rate.
          "fromCurrency": "USD", // the source currency for conversion.
          "toCurrency": "EUR", // the target currency for conversion.
          "amount": "10.2", // the amount to be converted.
          "account": "4adb69c1-9cfa-4341-b9f0-a725c7b86c87", // the account identifier.
          "partner": "examplePartner" // the partner providing the rate.
        },
        "rate": "1.12", // the conversion rate.
        "validUntil": "2024-08-23T00:00:00Z", // the date and time until the rate is valid.
        "signature": "signature123" // the signature to verify the rate.
      }
    }
  ],
  "type": "BANK_TRANSFER", // the type of withdrawal request (e.g., bank transfer).
  "meta": { // (optional) additional metadata for the withdrawal request.
    "fromAccount": "4adb69c1-9cfa-4341-b9f0-a725c7b86c87", // the identifier of the account from which the withdrawal is made.
    "to": "123456789", // the destination address for the withdrawal.
    "blockchain": "none" // (optional) blockchain network, if applicable (e.g., for cryptocurrency withdrawals).
  }
}

The API will return confirmation of the request and transaction details:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", // unique identifier for the withdrawal request.
  "currency": "string", // the currency code in which the withdrawal was made.
  "amount": "10.2", // the amount of funds that were withdrawn.
  "conversion": [ // (if applicable) details of currency conversion.
    {
      "amount": "1.12", // the amount of funds subject to conversion.
      "currency": "string", // the currency code to which the conversion was applied.
      "rate": { // information about the conversion rate.
        "rateRequest": { // request for the conversion rate.
          "fromCurrency": "string", // the source currency for conversion.
          "toCurrency": "string", // the target currency for conversion.
          "amount": "string", // the amount to be converted.
          "account": "string", // the account identifier.
          "partner": "string" // the partner providing the rate.
        },
        "rate": "1.12", // the conversion rate.
        "validUntil": "string", // the date and time until the rate is valid.
        "signature": "string" // the signature to verify the rate.
      }
    }
  ],
  "type": "string", // the type of withdrawal request (e.g., bank transfer).
  "meta": {}, // (optional) additional metadata for the withdrawal request.
  "fromAccount": "string", // the identifier of the account from which the withdrawal was made.
  "feeAmount": "10.2", // the fee amount for the withdrawal, if applicable.
  "status": "PROCESSED", // the status of the request (e.g., processed).
  "createdAt": "2024-08-22T13:05:59.437Z", // date and time when the request was created.
  "updatedAt": "2024-08-22T13:05:59.437Z" // date and time when the request was last updated.
}

Step 4.3: Retrieving Withdrawal Details

To obtain detailed information about a specific withdrawal transaction, use the GET /wallet/withdraw/{uuid} endpoint.

Example request:

GET /wallet/withdraw/withdraw12345

Example response:

{
  "id": "withdraw12345", // unique identifier for the withdrawal request.
  "currency": "USD", // the currency code in which the withdrawal was made.
  "amount": "10.2", // the amount of funds that were withdrawn.
  "status": "PROCESSED", // the status of the withdrawal request (e.g., processed).
  "createdAt": "2024-08-22T13:05:59.437Z" // date and time when the request was created.
}

5. Managing Currency Exchange

Step 5.1: Currency Conversion

To convert one currency to another, use the POST /wallet/convert endpoint. This request allows you to exchange funds from one currency to another using the provided conversion rate.

Example request:

{
  "fromCurrency": "USD",  // the currency you want to exchange.
  "toCurrency": "EUR",    // the currency you want to convert to.
  "amount": "100.00",     // the amount you want to exchange.
  "rate": "1.12"          // the exchange rate between the currencies.
}

Example response:

{
  "conversionId": "abc123xyz",  // unique identifier for the conversion
  "fromCurrency": "USD",        // currency being exchanged
  "toCurrency": "EUR",          // currency being converted to
  "amount": "100.00",           // amount being exchanged
  "convertedAmount": "112.00",  // resulting amount after conversion
  "rate": "1.12",               // exchange rate between the currencies
  "status": "COMPLETED"         // status of the conversion
}

Step 5.2: Retrieving List of Direct Exchanges

To get a list of all available direct currency exchanges, use the GET /wallet/direct-exchange endpoint. This request will return all possible exchange combinations between currencies supported by the system.

Example request:

GET /wallet/direct-exchange?accountId=453363465346

Example response:

[
  {
    "fromCurrency": "USD",     // currency being exchanged
    "toCurrency": "EUR",       // currency being converted to
    "rate": "1.12"             // exchange rate between the currencies
  },
  {
    "fromCurrency": "BTC",     // currency being exchanged
    "toCurrency": "USD",       // currency being converted to
    "rate": "25000.00"         // exchange rate between the currencies
  }
]

Step 5.3: Creating a Direct Currency Exchange

To create a new direct currency exchange, send a request to the POST /wallet/direct-exchange endpoint. This request allows you to specify the exchange parameters and receive confirmation of the new operation.

Example request:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",  // unique identifier for the conversion
  "fromAccount": "3fa85f64-5717-4562-b3fc-2c963f66afa6",  // identifier of the account from which funds are converted
  "toAccount": "3fa85f64-5717-4562-b3fc-2c963f66afa6",  // identifier of the account to which funds are converted
  "fromCurrency": "USDT",  // currency being converted from
  "toCurrency": "EPI",     // currency being converted to
  "fromAmount": "10.2",    // amount of the currency being converted from
  "toAmount": "9.87",      // resulting amount after conversion
  "signedRate": {         // exchange rate information
    "rateRequest": {      // details of the rate request
      "fromCurrency": "string",  // currency being converted from
      "toCurrency": "string",    // currency being converted to
      "amount": "string",        // amount for conversion
      "account": "string",       // identifier of the account
      "partner": "string"        // partner providing the rate
    },
    "rate": "1.12",           // exchange rate used for conversion
    "validUntil": "string",   // date and time until the rate is valid
    "signature": "string"     // signature for rate verification
  }
}

Example response:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",  // unique identifier for the conversion
  "fromAccount": "3fa85f64-5717-4562-b3fc-2c963f66afa6",  // identifier of the account from which funds are converted
  "toAccount": "3fa85f64-5717-4562-b3fc-2c963f66afa6",  // identifier of the account to which funds are converted
  "fromCurrency": "USDT",  // currency being converted from
  "toCurrency": "EPI",     // currency being converted to
  "fromAmount": "10.2",    // amount of the currency being converted from
  "toAmount": "9.87",      // resulting amount after conversion
  "signedRate": {         // exchange rate information
    "rateRequest": {      // details of the rate request
      "fromCurrency": "string",  // currency being converted from
      "toCurrency": "string",    // currency being converted to
      "amount": "string",        // amount for conversion
      "account": "string",       // identifier of the account
      "partner": "string"        // partner providing the rate
    },
    "rate": "1.12",           // exchange rate used for conversion
    "validUntil": "string",   // date and time until the rate is valid
    "signature": "string"     // signature for rate verification
  },
  "feeAmount": "0.01",      // amount of the fee charged for the conversion
  "feeCurrency": "USDT",   // currency of the fee charged
  "status": "SUCCESS",     // status of the conversion
  "note": "string",        // additional notes or comments
  "createdAt": "2024-08-23T07:31:15.451Z", // date and time when the conversion was created
  "updatedAt": "2024-08-23T07:31:15.451Z"  // date and time when the conversion was last updated
}

Step 5.4: Retrieving a Direct Currency Exchange

To obtain information about a specific currency exchange operation, use the GET /wallet/direct-exchange/{uuid} endpoint. Provide the unique exchange identifier (uuid) to get detailed information about the operation.

Example request:

GET /wallet/direct-exchange/4534653

Example response:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",  // unique identifier for the conversion
  "fromAccount": "3fa85f64-5717-4562-b3fc-2c963f66afa6",  // identifier of the account from which funds are converted
  "toAccount": "3fa85f64-5717-4562-b3fc-2c963f66afa6",  // identifier of the account to which funds are converted
  "fromCurrency": "USDT",  // currency being converted from
  "toCurrency": "EPI",     // currency being converted to
  "fromAmount": "10.2",    // amount of the currency being converted from
  "toAmount": "9.87",      // resulting amount after conversion
  "signedRate": {         // exchange rate information
    "rateRequest": {      // details of the rate request
      "fromCurrency": "string",  // currency being converted from
      "toCurrency": "string",    // currency being converted to
      "amount": "string",        // amount for conversion
      "account": "string",       // identifier of the account
      "partner": "string"        // partner providing the rate
    },
    "rate": "1.12",           // exchange rate used for conversion
    "validUntil": "string",   // date and time until the rate is valid
    "signature": "string"     // signature for rate verification
  },
  "feeAmount": "0.01",      // amount of the fee charged for the conversion
  "feeCurrency": "USDT",   // currency of the fee charged
  "status": "SUCCESS",     // status of the conversion
  "note": "string",        // additional notes or comments
  "createdAt": "2024-08-23T07:31:15.451Z", // date and time when the conversion was created
  "updatedAt": "2024-08-23T07:31:15.451Z"  // date and time when the conversion was last updated
}