Orders

Crypto processing exchanges one currency for another with a given amount.

Order actions

The partner has 2 main methods - Estimate amount and Create a new order.

Estimate amount

POST https://api.swapple.org/api/v3/estimate-amount

Using this endpoint, the partner can assess the current terms of exchange.

Returns estimated exchange value with fees included. Note that fromAmount and toAmount are both optional, but one of them is required.

Headers

Name	Type	Description
public-key*	String	Your public key.Authorization
timestamp*	String	Current timestamp that was used to generate the signature in milliseconds.
signature*	String	HMAC SHA512 key/value signature.

Request Body

Name	Type	Description
from*	String	Currency to exchange from. Currencies
to*	String	Currency to exchange for. Currencies
fromAmount or toAmount*	String	The amount the partner wants to exchange. Transmitted in the from currency or to currency (the partner can transfer it in one currency or another (only one of them must be send to us)).
extraFromFee	String	The percentage that the partner wants to withdraw when processing the payment. Your's fromAmount percentage fee. 0.005 means 0.5%. These fees will be accumulated on a separate account of the partner, to which he will have access through the account manager.
extraToFee	String	The percentage that the partner wants to withdraw when processing the payment. Your's toAmount percentage fee 0.005 means 0.5% These fees will be accumulated on a separate account of the partner, to which he will have access through the account manager.
rateType	String	If you need to specify a rate type, then you can do this as follows. Only FLOATING or FIXED codes are supported (FLOATING by default). FLOATING rate - when estimating or creating an order, we do not guarantee that the exchange will take place at a specific exchange rate, instead, the exchange will take place at the exchange rate that will be at the time of arrival of the currency. FIXED rate - the rate is fixed in 2 stages: 1) the 1st fix is after the estimate - the partner makes an estimate, specifies the fixed rate and this rate is fixed for the agreed period. If the partner creates an order during this period, the rate at the estimate will be maintained. 2) the 2nd stage occurs when we expect the receipt of funds - if we receive funds during this period, we will also exchange at a fixed rate; if the rate expires, and the funds arrive after that time, the funds will be returned.
fromNetwork	String	Network to exchange from. If the currency from or the currency to is a cryptocurrency, then it is required to pass Network.Currencies
toNetwork	String	Network to exchange to. If the currency from or the currency to is a cryptocurrency, then it is required to pass Network.Currencies

200: OK Returns estimated exchange value.

An example of a request:
{
"from": "USDT", 
"to": "CARDUAH",
"fromNetwork": "TRX",
"rateType": "FLOATING", 
"fromAmount": 1, 
"toAmount": 40 
}


An example of a response:
{
  "from": "CARDUAH",
  "to": "USDTERC20",
  "fromNetwork": "TRX",
  "fromAmount": 1500,
  "toAmount": 42.678215,
  "fromRate": 27.93713,
  "toRate": 1,
  "fromFee": 3,
  "toFee": 10,
  "extraFromFee": 7.5,
  "extraToFee": 0.264715,
  "rateType": "FLOATING",
  "rateId": "5ZaBLA2CmBofWURVVmtajn"
}

401: Unauthorized The signature was incorrectly generated.

{
  "errorCode": "SECURITY_ERROR",
  "message": "Signature is invalid."
}

400: Bad Request We are currently unable to process this request.

{
  "errorCode": "PROVIDER_ERROR",
  "message": "Exchange is unavailable."
}

400: Bad Request The max limit on which the user has not passed. One of the parameters (fromRate or toRate) must be "1", and the other show the rate.

{
   "errorCode":"EXCEEDING_LIMITS",
   "message":"Amount 31000 is greater than max amount 29500 rate=36.73856",
   "maxAmount":"29500",
   "fromRate":"36.73856",
   "toRate":"1",
   "limit":"impossible"
}

400: Bad Request The min limit on which the user has not passed. One of the parameters (fromRate or toRate) must be "1", and the other show the rate.

{
   "errorCode":"EXCEEDING_LIMITS",
   "message":"Amount 1222.01 is lower than min amount 1400 rate=883920",
   "minAmount":"1400",
   "fromRate":"883920",
   "toRate":"1"
}

Create a new order

POST https://api.swapple.org/api/v3/create-order

The partner can directly create an exchange.

Generates a pay-in address or pay-in URL and returns Order object with an ID field to track a transaction status.

Headers

Name	Type	Description
public-key*	String	Your public.Authorization
timestamp*	String	Current timestamp that was used to generate the signature in millisecond.
signature*	String	HMAC SHA512 key/value signature.

Request Body

Name	Type	Description
from*	String	Currency to exchange from.Currencies
to*	String	Currency to exchange for.Currencies
fromNetwork	String	Network to exchange from.Currencies
toNetwork	String	Network to exchange for.Currencies
fromAmount or toAmount	String	The amount for which you need to calculate. Transmitted in the from currency or to currency.
userId*	String	Partner's client id.
partnerOrderId	String	Partner's custom order id.
redirectUrl*	String	For fiat deposits - where to redirect the user after payment.
toMemo	String	for XRP etc.
extraFromFee	String	The percentage that the partner wants to withdraw when processing the payment. Partner's fromAmount percentage fee. 0.005 means 0.5%. These fees will be accumulated on a separate account of the partner, to which he will have access through the account manager.
extraToFee	String	The percentage that the partner wants to withdraw when processing the payment. Partner's toAmount percentage fee 0.005 means 0.5% These fees will be accumulated on a separate account of the partner, to which he will have access through the account manager.
rateType	String	If you need to specify a rate type, then you can do this as follows. Only FLOATING or FIXED codes are supported (FLOATING by default). FLOATING rate - when estimating or creating an order, we do not guarantee that the exchange will take place at a specific exchange rate, instead, the exchange will take place at the exchange rate that will be at the time of arrival of the currency. FIXED rate - the rate is fixed in 2 stages: 1) the 1st fix is after the estimate - the partner makes an estimate, specifies the fixed rate and this rate is fixed for the agreed period. If the partner creates an order during this period, the rate at the estimate will be maintained. 2) the 2nd stage occurs when we expect the receipt of funds - if we receive funds during this period, we will also exchange at a fixed rate; if the rate expires, and the funds arrive after that time, the funds will be returned.
rateId*	String	Rate identifier obtained from the estimate method. Required only for fixed rate.
ipAddress	String	ip address of partner's user.
toPaymentDetails*	String	User's credit card or crypto address. This determines where the partner wants to receive the currency after the exchange (if it is UAH, then it will be a card address, if crypto - a crypto address etc.)
fromPaymentDetails	String	User's income credit card or crypto address. It shows from which card or address the user made the payment.
withdrawType	String	Withdrawal can be internal or external. All the documentation is described about the external withdrawal which is configured by default (that is, we received funds, exchanged and withdrew funds to toPaymentDetails). We can not withdraw funds, that is, save the result of the exchange on the partner's account in our system (internal withdrawal). The partner can withdraw these funds by contacting the contact manager.

200: OK See below.

An example of a request:
order_body = {
            "from": "CARDUAH",
            "to": "USDT",
            "toNetwork": "TRX",
            "ratetype": "FLOATING",
            "fromAmount": 1000,
            "toPaymentDetails": "TBia4uHnb3oSSZm5isP284cA7Np1v15Vhi,
            "redirectUrl": "https://google.ua",
            "userId": "1632076503",
            "partnerOrderId": "343455"
        }


An example of a response:
{
  "id": "69951ec1-6b7a-4eab-ab89-d7f3592788a1",
  "orderType": "USUAL",
  "status": "WAITING",
  "from": "CARDUAH",
  "to": "USDT",
  "toNetwork": "TRX",
  "payUrl": "https://cardgate.paymega.io/hpp/cgi_HxlZo2Gl94TOc5Zg",
  "payCryptoAddress": "",
  "payCryproMemo": "",
  "fromPaymentDetails": "",
  "toPaymentDetails": "0xB44a7dd90e28B10Fdf1283602175A0CdD09c13fB",
  "toMemo": "",
  "fromTxHash": "",
  "toTxHash": "",
  "fromAmount": 1500,
  "fromAmountReceived": 1497,
  "toAmount": 42.678215,
  "fromRate": 27.93713,
  "toRate": 1,
  "fromFee": 3,
  "toFee": 10,
  "extraFromFee": 7.5,
  "extraToFee": 0.264715,
  "redirectUrl": "https://swapple.org/",
  "userId": "4MkQ4RTk",
  "rateType": "FLOATING"
}

401: Unauthorized The signature was incorrectly generated.

{
  "errorCode": "SECURITY_ERROR",
  "message": "Signature is invalid."
}

400: Bad Request We are currently unable to process this request.

{
  "errorCode": "PROVIDER_ERROR",
  "message": "Exchange is unavailable."
}

400: Bad Request The max limit on which the user has not passed. One of the parameters (fromRate or toRate) must be "1", and the other show the rate.

{
   "errorCode":"EXCEEDING_LIMITS",
   "message":"Amount 31000 is greater than max amount 29500 rate=36.73856",
   "maxAmount":"29500",
   "fromRate":"36.73856",
   "toRate":"1",
   "limit":"impossible"
}

400: Bad Request The min limit on which the user has not passed. One of the parameters (fromRate or toRate) must be "1", and the other show the rate.

{
   "errorCode":"EXCEEDING_LIMITS",
   "message":"Amount 1222.01 is lower than min amount 1400 rate=883920",
   "minAmount":"1400",
   

400: Bad Request Invalid toPaymentDetails field.

{
  "errorCode": "VALIDATION_ERROR",
  "message": ""
}

400: Bad Request Rate for FIXED rate flow was expired.

{
    "errorCode": "EXPIRED_RATE",
    "message": "Rate for FIXED rate flow was expired.",
}

Order entity response

This is the response we send.

Field	Description
id	Order id.
status	The status of order. See Statuses
from	Currency to exchange from. Currencies
to	Currency to exchange for.Currencies
fromNetwork	Network to exchange from.Currencies
toNetwork	Network to exchange for.Currencies
payUrl	Deposit url in case of fiat from currency. URL for a partner if there is a need to redirect his client to the payment page. It can be an empty field, but then we pass payCryptoAddress (and vice versa for payCryptoAddress)
payCryptoAddress	Crypto address deposit in case of crypto from currency.
payCryptoMemo	In case the cryptocurrency requires a memo (XRP, etc.)
fromAmount	Amount to exchange from.
toAmount	Amount to exchange for.
userId	Partner's client id.
partnerOrderId	Partner's custom order id.
redirectUrl	For fiat deposits, where should the user be redirected after payment?
toPaymentDetails	User's credit card or crypto address.
fromPaymentDetails	This shows from which card or address the user made the payment
toMemo	In case the cryptocurrency requires a memo (XRP, etc.)
fromTxHash	Crypto deposit transaction hash in Blockchain.
toTxHash	Crypto withdraw transaction hash in Blockchain.
fromRate	Rate to exchange from.
toRate	Rate to exchange for.
fromFee	Swapple fromAmount fee.
toFee	Swapple toAmount fee.
extraFromFee	Partner's fromAmount calculated fee.
extraToFee	Partner's toAmount calculated fee.
rateType	If you need to specify a rate type, then you can do this as follows. Only FLOATING or FIXED codes are supported (FLOATING by default).
orderExpirationTimetamp	Order expiration time (utc)
fromAmountReceived	The amount we received after deducting Swapple fees
fromRate	It is set depending on whether it is a pair for deposit or withdrawal (if deposit, then fromRate=1)
toRate	It is set depending on whether it is a pair for deposit or withdrawal (if withdrawal, then toRate=1)

Сancel the order before the deposit is started.

POST https://api.swapple.org/api/v3/cancel-order

If the partner has created an order and we have not yet received the funds in the currency from (the deposit has not taken place), the partner can cancel this order by calling this endpoint. If the partner cancels this order, then even if the deposit goes in, we will not exchange it, the funds will be suspended and the partner needs to contact the account manager for their return.

Headers

Name	Type	Description
public-key*	String	Your public key.Authorization
timestamp*	String	Current timestamp that was used to generate the signature in millisecond.
signature*	String	HMAC SHA512 key/value signature

Request Body

Name	Type	Description
id*	String	The order id

200: OK

{
  "status": "SUCCESS"
}

400: Bad Request Missing fields.

{
  "errorCode": "INVALID_PARAMETERS",
  "message": "Missing parameters."
}

401: Unauthorized The signature was incorrectly generated.

{
  "errorCode": "SECURITY_ERROR",
  "message": "Signature is invalid."
}

404: Not Found Order not found.

{
  "errorCode": "NO_ORDER",
  "message": "There is no such order"
}

Get information about order

GET https://api.swapple.org/api/v3/check-order

This endpoint is used to check the status of the order.

Query Parameters

Name	Type	Description
id*	String	The order id.

Headers

Name	Type	Description
public-key*	String	Your public key.Authorization
timestamp*	String	Current timestamp that was used to generate the signature in millisecond.
signature*	String	HMAC SHA512 key/value signature.

200: OK Returns Order Entity.

An example of a request:
A parameter (id={order_id}) is indicated in the url

An example of a response:
{
"id":"639de231-01fe-4fce-9c5e-3f038e2b6be2",
"status":"WAITING",
"from":"USDT",
"to":"CARDUAH",
"fromNetwork": "TRX",
"payUrl":"https://invoice.swapple.org/order/639de231-01fe-4fce-9c5e-3f038e2b6be2",
"payCryptoAddress":"d4818dca-7c7c-42c0-9617-f7a1e5f43852",
"payCryptoMemo":"",
"fromPaymentDetails":"",
"toPaymentDetails":null,
"toMemo":"",
"fromTxHash":"",
"toTxHash":"",
"fromAmount":118.04562,
"fromAmountReceived":117.81,
"toAmount":5000.0,
"fromRate":1,
"toRate":42.44,
"fromFee":0.23562,
"toFee":0.0,
"side":"SELL",
"extraFromFee":0.0,
"extraToFee":0.0,
"redirectUrl":"https://test.com",
"userId":"111",
"partnerOrderId":null,
"fromRevenueShare":0.0,
"toRevenueShare":0.0,
"failedReason":"",
"created":"2024-02-07T10:55:29.487905+00:00",
"updated":"2024-02-07T10:55:29.545166+00:00"
}

400: Bad Request Missing fields.

{
  "errorCode": "INVALID_PARAMETERS",
  "message": "Missing parameters."
}

401: Unauthorized The signature was incorrectly generated.

{
  "errorCode": "SECURITY_ERROR",
  "message": "Signature is invalid."
}

404: Not Found Order not found.

{
  "errorCode": "NO_ORDER",
  "

Returns list of orders

GET https://api.swapple.org/api/v3/get-orders

This is the endpoint for getting order history.

Query Parameters

Name	Type	Description
limit	String	To limit max returned orders.
offset	String	To offset returned orders.
user_id	String	filter by userId.
status	String	filter by order status. Statuses

Headers

Name	Type	Description
public-key*	String	Your public key.Authorization
timestamp*	String	Current timestamp that was used to generate the signature in millisecond.
signature*	String	HMAC SHA512 key/value signature.

200: OK Returns a list of Order entities.

{
    // Response
}

401: Unauthorized The signature was incorrectly generated.

{
  "errorCode": "SECURITY_ERROR",
  "message": "Signature is invalid."
}

Get list of available exchange pairs

GET https://api.swapple.org/api/v3/get-pairs-info

This is the endpoint for getting a list of available pairs for exchange

Currencies

Headers

Name	Type	Description
public-key*	String	Your public key.Authorization
timestamp*	String	Current timestamp that was used to generate the signature in millisecond.
signature*	String	HMAC SHA512 key/value signature.

200: OK Returns a list of Pair Entity.

An example of an request:
https://swapple.org/api/v3/get-pairs-info

An example of an response:
[
    {
        "from": "USDT",
        "to": "USDT",
        "fromnetwork": "TRX",
        "tonetwork": "ETH",
        "in": "1",
        "out": "1",
        "ratetype": "FIXED",
        "amount": "215808.769064",
        "tofee": "1.0 USDT",
        "fromfee": "0 USDT",
        "minamount": "15 USDT",
        "maxamount": "215808.769064 USDT"
    },
    {
        "from": "USDT",
        "to": "ETH",
        "fromnetwork": "TRX",
        "tonetwork": null,
        "in": "2388.1652",
        "out": "1",
        "ratetype": "FLOATING",
        "amount": "20.09266151",
        "tofee": "0.0041447 ETH",
        "fromfee": "0.2 %",
        "minamount": "33.88121995 USDT",
        "maxamount": "47984.59499356 USDT"
    },
    {
        "from": "USDT",
        "to": "CARDKZT",
        "fromnetwork": "TRX",
        "tonetwork": null,
        "in": "1",
        "out": "463.67",
        "ratetype": "FLOATING",
        "amount": "20378.84",
        "tofee": "1.5 %",
        "fromfee": "0.2 %",
        "minamount": "26.54578917 USDT",
        "maxamount": "43.95715788 USDT"
    }]

401: Unauthorized The signature was incorrectly generated.

{
  "errorCode": "SECURITY_ERROR",
  "message": "Signature is invalid."
}

Get exchange pair info

GET https://api.swapple.org/api/v3/get-pair-info

The partner specifies a specific pair and if it is configured for them, we return the same parameters (rate, min-max amount etc) but for a specific pair.

Path Parameters

Name	Type	Description
currency_from*	String	Currencies
currency_to*	String	Currencies

Query Parameters

Name	Type	Description
rateType	String	If you need to specify a rate type, then you can do this as follows. Only FLOATING or FIXED codes are supported (FLOATING by default)
fromnetwork	String	Network to exchange from. Currencies
tonetwork	String	Network to exchange for.Currencies

Headers

Name	Type	Description
public-key	String	Your public key.Authorization
timestamp	String	Current timestamp that was used to generate the signature in millisecond.
signature	String	HMAC SHA512 key/value signature.

401: Unauthorized The signature was incorrectly generated.

{
  "errorCode": "SECURITY_ERROR",
  "message": "Signature is invalid."
}

200: OK Returns Pair Entity.

{
  "from": "ETH",
  "to": "BTC",
  "in": "1",
  "out": "0.063716762624722",
  "amount": "0.60302220",
  "tofee": "0.0005 BTC",
  "fromfee": "0.2 %",
  "minamount": "0.027909904946227501",
  "maxamount": "9.6173098756942792860",
  "ratetype": "FLOATING",
  "side": "SELL"
}

* Amount - Our current liquidity in currency from.
  Side - This informs the partner whether this pair is for deposit or for withdrawal.

Pair Entity

This is a description of the pair model. When a partner requests a pair, it is returned the fields shown in the table below.

Field	Description	Type
from	Currency to exchange from. Currencies	string
to	Currency to exchange for.Currencies	string
fromnetwork	Currencies	string
tonetwork	Currencies	string
in	Rate to exchange from.	string
out	Rate to exchange for.	string
fromfee	Swapple fromAmount fee. May be percentage or static.	string
tofee	Swapple toAmount fee. May be percentage or static.	string
maxamount	The maximum amount of from currency that can be exchanged.	string
minamount	The minimum amount of from currency that can be exchanged.	string
rateType	Only FLOATING or FIXED codes are supported (FLOATING by default).	string