API Endpoints

Ping

GET https://app.citrn.io/api/ping

Ping to the API

200 OK: Example of a successful response

{
  "message": "OK"
}

Receive the balances on a specific date

POST https://app.citrn.io/api/balances

The balance inquiry for the selected date and currency. Please note that the date is UTC-timezoned.

For previous dates, the balance amounts returned will be 23:59 UTC.

For today's inquiries, the balance amounts will be recent.

Headers

Name	Type	Description
X-Process-Key*	string	Header for request authorization The value is unique and provided during onboarding
X-Process-Signature*	string	Header for request authorization The value is unique and provided during onboarding

Request Body

Name	Type	Description
date	string	Date format YYYY-MM-DD, if date is not entered, the response will provide the balances for the current date
currencies	string	List of currencies in ISO format (example USDT, ETH, BTC) If empty, all currencies available will be returned

200 OK: Example of a successful response

{
    "data": {
        "ETH": "0.00507718",
        "USDT": "111.70888402"
    }
}

Receive crypto

POST https://app.citrn.io/api/addresses/take

Receiving cryptocurrency to the wallet

Headers

Name	Type	Description
X-Process-Key*	string	Header for request authorization The value is unique and provided during onboarding
X-Process-Signature*	string	Header for request authorization The value is unique and provided during onboarding

Request Body

Name	Type	Description
foreign_id*	string
currency*	string	Cryptocurrency full name (example: USDTE, USDTT)

200 OK: Example of a successful response

{
    "data": {
        "address": "TSUTBJ...Shqt"
    }
}

Withdraw crypto

POST https://app.citrn.io/api/withdrawal/crypto

Withdraw cryptocurrency from the wallet

Headers

Name	Type	Description
X-Process-Key*	string	Header for request authorization The value is unique and provided during onboarding
X-Process-Signature*	string	Header for request authorization The value is unique and provided during onboarding

Request Body

Name	Type	Description
address*	string	Address of the receiver
foreign_id*	string	ID of the transaction
amount*	string	Amount of the transaction
convert_to	string	The currency in which the payment is made. (example EUR, USDTE, USDTT)
currency*	string	The base currency of the merchant. Detailed info here.
key	string	Secret key
memo	string	Tag from currency cryptoprocessing. Required for transactions TON as a comment for the

200 OK: Example of a successful response

{
    "data": {
        "id": 116597,
        "status": "processing"
    }
}

Supported currencies

POST https://app.citrn.io/api/currencies/list

Get a list of all supported currencies

Headers

Name	Type	Description
X-Process-Key*	string	Header for request authorization The value is unique and provided during onboarding
X-Process-Signature*	string	Header for request authorization The value is unique and provided during onboarding

Request body

Name	Type	Description
type	string	Currency type: "crypto", "fiat"

200 OK: Example of a successful response

{
  "data": [
    {
      "id": 2,
      "name": "SANDBOX",
      "network_name": "sandbox",
      "type": "crypto",
      "currency": "SBX"
    },
    {
      "id": 1,
      "name": "TRX",
      "network_name": "tron",
      "type": "crypto",
      "currency": "TRX"
    },
    {
      "id": 3,
      "name": "USDTT",
      "network_name": "tron",
      "type": "crypto",
      "currency": "USDT"
    }
  ]
}

Get the list of currency exchange rates

GET https://app.citrn.io/api/rates

200 OK: Example of a successful response

{
  "id": 123,
  "base": "EUR",
  "rates": {
    "BTC": 56.725974352393116,
    "ETH": 1.832333664592147,
    "LTC": 1.4988272055399114,
    "USDT": 2.472145836787712
  },
  "date_created": "2023-10-26T19:40:40.865248",
  "date_modified": "2023-10-26T19:40:40.865248"
}

Exchangeable currencies

POST https://app.citrn.io/api/currencies/pairs

Get the list of exchangeable currencies

Headers

Name	Type	Description
X-Process-Key*	string	Header for request authorization The value is unique and provided during onboarding
X-Process-Signature*	string	Header for request authorization The value is unique and provided during onboarding

Request Body

Name	Type	Description
currency_from	string	Filter by currency ISO that exchanges from, example: BTC
currency_to	string	Filter by currency ISO that can be converted to, example: EUR

200 OK: Example of a successful response

{
  "data": [
    {
      "currency_from": {
        "currency": "ETH",
        "type": "crypto"
      },
      "currency_to": {
        "currency": "USDT",
        "type": "crypto"
      },
      "rate_from": "1",
      "rate_to": "1816.18"
    }
  ]
}

400 Bad Request: Example of an error response

{
    "errors": {
        "currency_from": "The selected currency from is invalid.",
        "currency_to": "The selected currency to is invalid."
    }
}

Most recent currency rates

POST https://app.citrn.io/api/currencies/rates

Get the list of most recent currency rates

Headers

Name	Type	Description
X-Process-Key*	string	Header for request authorization The value is unique and provided during onboarding
X-Process-Signature*	string	Header for request authorization The value is unique and provided during onboarding

Request Body

Name	Type	Description
currency_from	string	Currency from which to see the rates
currency_to	string	Currency to which to see the rates

200 OK: Example of a successful response

{
  "data": [
    {
      "currency_from": {
        "currency": "BTC",
        "type": "crypto"
      },
      "currency_to": {
        "currency": "EUR",
        "type": "fiat"
      },
      "rate_from": 1,
      "rate_to": 27550.445302827415
    }
  ]
} 

List of current balances

POST https://app.citrn.io/api/accounts/list

Get the list of current balances

Headers

Name	Type	Description
X-Process-Key*	string	Header for request authorization The value is unique and provided during onboarding
X-Process-Signature*	string	Header for request authorization The value is unique and provided during onboarding

200 OK: Example of a successful response

{
  "data": [
    {
      "currency": "BTC",
      "type": "crypto",
      "balance": "0.00000000"
    },
    {
      "currency": "USDC",
      "type": "crypto",
      "balance": "0.00000000"
    },
    {
      "currency": "USDTE",
      "type": "crypto",
      "balance": "0.00000000"
    },
    {
      "currency": "TRX",
      "type": "crypto",
      "balance": "0.00000000"
    },
    {
      "currency": "USDTT",
      "type": "crypto",
      "balance": "118.71888735"
    },
  ]
}

Create exchange quota

POST https://app.citrn.com/api/exchange/create-quota

Creating the exchange quota is required to make the currency exchange.

Request_coin parameter must be either equal to from_coin or to_coin.

If request_coin is equal to from_coin, the requested amount is set and the final amount depends (to_coin) on the exchange rate and fees.

If request_coin is equal to to_coin, the final amount is set and the amount that will be possibly charged from the customer (if the exchange is confirmed with the make-exchange request) depends on the exchange rate and fees.

The response will provide the quote_id that is required to confirm the transaction.

Headers

Name	Type	Description
X-Process-Key*	string	Header for request authorization The value is unique and provided during onboarding
X-Process-Signature*	string	Header for request authorization The value is unique and provided during onboarding

Request Body

Name	Type	Description
from_coin*	string	Cryptocurrency full name (example: USDTE, USDTT)
to_coin*	string	Cryptocurrency full name (example: USDTE, USDTT)
request_amount*	string	The requested amount for the transaction
request_coin*	string	Cryptocurrency full name (example: USDTE, USDTT). The parameter sets in which currency the request_amount is.

200 OK: Example of a successful response

{
  "quote_id": "2J3IwFIcaoYoyfRAEBib8Q",
  "expire_time": 60,
  "expire_timestamp": 1691411462,
  "from_coin": "TRX",
  "from_amount": "1.00000000",
  "request_amount": "1.00000000",
  "request_coin": "TRX",
  "to_coin": "USDTT",
  "to_amount": "0.06893257",
  "exchange_rate": "0.06893257",
  "reverse_exchange_rate": "14.50693209",
  "fee_amount": "0.00000000",
  "fee_coin": "TRX",
  "merchant_id": 1,
  "user_id": null
}

Perform the currency exchange

POST https://app.citrn.com/api/exchange/make-exchange

After the exchange quota is placed successfully, the response returns the quote_id which is used in this request to perform the currency exchange.

Headers

Name	Type	Description
X-Process-Key*	string	Header for request authorization The value is unique and provided during onboarding
X-Process-Signature*	string	Header for request authorization The value is unique and provided during onboarding

Request Body

Name	Type	Description
quote_id*	string	The quote_id is received on the stage of creating an exchange quote (if successful).

200 OK: Example of a successful response

{
  "success": true
}

Create a redirect payment

POST https://app.citrn.com/api/payments/create-payment

Initiates a redirect payment process by creating a session that directs the user to an external payment gateway, returning a unique session ID and redirect URL for the user to complete their transaction.

Headers

Name	Type	Description
X-Process-Key*	string	Header for request authorization The value is unique and provided during onboarding
X-Process-Signature*	string	Header for request authorization The value is unique and provided during onboarding

Request Body

Name	Type	Description
foreign_id*	string	The ID of the user who initiated the deposit
coin_name*	string	The name of of the currency selected. by the user
return_url*	string	Url to which the user is redirected after making the transaction

200 OK: Example of a successful response

{
  "id": "d1f6e3b4-6e7e-4d3d-9f9e-8b3f6e9d6c3f",
  "redirect_url": "https://example.com"
}

401 Unauthorized: Example of an unauthorized response

{
    "message": "Unauthorized"
}

403 Forbidden: Example of a forbidden response

{
    "message": "Forbidden"
}

422 Unprocessable Entity: Example of a validation error

{
    "loc": [
    "field_name"
  ],
  "msg": "value is not a valid integer",
  "type": "type_error.integer",
  "ctx": {
    "in": "body"
  }
}

Error handling

When a transaction is executed, the system may return a specific error_code indicating a validation issue or another reason why the operation cannot be completed.

If an error_code is returned, the transaction will not be executed, and all associated actions will be rolled back.

List of error codes and relevant status messages

Error Code	Description
coin_not_found	Specified coin does not exist
network_not_found	Specified network is not recognized
address_not_found	Wallet address is missing or invalid
invalid_address	Provided address is not valid
resource_not_found	Requested resource could not be located
coin_not_supported	Coin is not supported on this platform
balance_not_enough	Insufficient balance to complete the action
network_not_available	Network is temporarily inaccessible
withdraw_disabled	Withdrawals are currently disabled
duplication_request	Repeated request detected
amount_too_low	Amount is below the minimum allowed
invalid_amount	Provided amount is not valid
withdrawal_virtual_coin	Withdrawal for virtual/test coin not allowed
withdrawal_base_coin_mismatch	Coin and base coin do not match
commission_not_found	Commission details not found
create_quota_error	Failed to create quota record
process_exchange_quota_error	Error processing exchange quota
payment_not_found	Payment record not found
payment_expired	Payment request has expired

400 Bad Request: Example of an error response

{
    "message": "Amount exceeds available withdrawal limit",
    "error_code": "balance_not_enough"
}