Before you can use the client API, you need to submit an application to add a client to the system. After registration, the client is provided with the following private data:
Api key - the key to access the API of the system, without it API methods will not work. In the header of each request, you need to add the field {ApiKey: “your-api-key”}
Encryption key - the key needed to encrypt the private key for its subsequent submission to the system (one of the options for conducting the transfer)
To make a transfer the client should perform 2 actions (call 2 API methods):
Send a request to create a transfer (with simple or advanced option), and receive the data of the created transfer
Initialize the transfer you need to sign, and send the transaction on the side of the Web 3.0 wallet that you use
After successful execution of these methods, the transfer will be initiated, and after that, the amount will be sent to your address in the destination network (execution time depends on many factors, not all of them depend on our service).
After creating a transaction, a method of obtaining the status of the transaction will be available, which can be used to obtain the actual data of the execution of the transfer.
Additional methods are also available: method for obtaining a list of supported networks and tokens
Options for searching routes
There are several options for obtaining routes:
Simple option - get the recommended Chainspot router route. The best route is determined by a combination of many factors, such as transfer execution time, the amount received in the destination network, fees, etc. To obtain the route using this method, one API request is sufficient.
Advanced option - get a list of all available routes based on the given parameters, select the desired one according to your internal logic, and then retrieve the details of the selected route with a second request. To obtain the route using this method, you need to make 2 API requests—first, to get the list of available routes, and then to retrieve the details of the selected route.
Loyalty logic
Users of the Chainspot router can participate in a loyalty program, where by making transactions that meet certain conditions, they gain experience, level up, and receive bonuses. You can read more about this system here.
Users of the client using the Chainspot API also gain experience, allowing our clients to use this bonus as an additional motivator to stay in the system.
However, not all routes support the loyalty program. Those that do have a flag in the parameters: useLoyalty: true.
Transaction initiation call (simple option)
POST /2.0/client/create-recommended-transaction
Accepts the following parameters:
networkFrom (string, required) - departure network symbol
(for example, Ethereum - ETH, Polygon - POL etc.)
networkTo (string, required) - destination network symbol (similar to networkFrom)
cryptoFrom (string, required) - departure token symbol (for example, Ethereum - ETH, USDT - USDT etc.)
cryptoTo (string, required) - destination token symbol (similar to cryptoFrom)
addressFrom (string, required) - the address from which tokens are sent in the departure network, as well as the address to which the tokens arrive in the destination network
addressTo (string, not required) - the user's address in the destination network; the funds will be delivered to this address once the transfer is fully completed
amount (string, required) - the number of tokens to be sent from the departure network, accepts the amount in the minimum unit (for example, the decimal of Ethereum is 18, so in order to send 1 ETH, you should enter 1000000000000000000; the decimal of USDT is 6, so in order to send 100 USDT you should enter 100000000).
This call creates a new transaction in the system and returns the transfer data.
An example of a successful response (HTTP Code 200):
{"success":true,// request success flag"data": {"id":"feb1443b-83ab-4dcd-9725-400b84555b7c",//transaction ID in the system"service":"lifi",// service that handles the transaction"router":"lifi",// router that handles the transaction"bridge":"cbridge",// bridge that handles the transaction"status":"new",// transaction status in the system"useLoyalty":true,// loyalty program availability flag"transferDataFrom": { // transaction data on the departure network"network":"POL",// departure network symbol"crypto":"USDC",// departure token symbol"decimals":6,// departure token decimals"amount":"26773259",// transfer amount"amountInUsd":"26.77"// transfer amount in USD },"transferDataTo": { // transaction data on the destination network"network":"FTM",// destination network symbol"crypto":"USDC",// destination token symbol"decimals":6,// destination token decimals"amount":"26741575",// amount to be received"amountInUsd":"26.74"// amount to be received в USD },"transactionData": { // transfer data "approve": { // data to confirm token withdrawal (if tokens are sent); if native tokens - this block is empty
"data":"0x0",// transfer data, which must be signed with a private key "addressFrom": "0x4c33c110EA0873c549a6cC1F615bAB9fD7D21263d", // departure address from which the approval is sent
"addressTo": "0x5c59718F693b2FDbC7c3d8449581dC3a8435AA54", // address to which the approval is sent (the address of the token in the departure network)
"gasLimit":"0x11170",// the amount of gas the approval burns (in hex format)"gasPrice":"0xaa27ae7f5",// gas price in hex format"nonce":"0x1a",// serial number of the transaction at the address in hex format"coinValue":"0x0",// the number of native tokens sent upon confirmation"tokenValue":"0x198870b",// the number of tokens for approval (in hex format)"chainId":137// departure network ID },"transfer": { // data for transfer initialization"data":"0х0",// transfer data, which must be signed with the private key "addressFrom": "0x4c33c110EA0873c58a6cC1F615bAB9fD7D21263d", // address from which the transfer is initialized
"addressTo": "0x5c59718F693b9FDbC7c3d3149581dC3a8435AA54", // address to which the transfer is initialized (usually a bridge/router contract)
"gasLimit":"0xf6dfe",// the amount of gas the transfer burns (in hex format)"gasPrice":"0xa8d4dc606",// gas price in hex format"nonce":"0x1b",// the serial number of the transaction in hex format"coinValue":"0x0",// the number of native tokens sent upon transfer initialization"tokenValue":"0x198870b",// the number of tokens sent upon transfer initialization"chainId":137// departure network ID } },"fee": { // bridges and routers fee data"amount":"0.4",// amount of fee in cryptocurrency"symbol":"USDC",// fee currency symbol"decimals":6,// fee currency decimals"amountInUsd":"0.4"// amount of fee in USD } }}
Example of sent data validation error (HTTP code 400):
{"success":false,// request success flag"message":"Validation error",// error message"errors": [ // list of errors {"field":"networkFrom",// request field, the validation of which ended with an error"messages": [ // validation error messages"Field are required" ] } ]}
Example of a common request error (HTTP code 400):
{"success":false,// request success flag"message":"Internal Server Error"// error message}
Transaction routers list (advanced option, first step)
POST /2.0/client/create-transactions
Accepts the following parameters:
networkFrom (string, required) - departure network symbol
(for example, Ethereum - ETH, Polygon - POL etc.)
networkTo (string, required) - destination network symbol (similar to networkFrom)
cryptoFrom (string, required) - departure token symbol (for example, Ethereum - ETH, USDT - USDT etc.)
cryptoTo (string, required) - destination token symbol (similar to cryptoFrom)
addressFrom (string, required) - the address from which tokens are sent in the departure network, as well as the address to which the tokens arrive in the destination network
addressTo (string, not required) - the user's address in the destination network; the funds will be delivered to this address once the transfer is fully completed
amount (string, required) - the number of tokens to be sent from the departure network, accepts the amount in the minimum unit (for example, the decimal of Ethereum is 18, so in order to send 1 ETH, you should enter 1000000000000000000; the decimal of USDT is 6, so in order to send 100 USDT you should enter 100000000).
This call creates a new transactions in the system and returns the transfer data for all routers
An example of a successful response (HTTP Code 200):
{"success":true,// request success flag"data": [ {"id":"feb1443b-83ab-4dcd-9725-400b84555b7c",//transaction ID in the system"service":"lifi",// service that handles the transaction"router":"lifi",// router that handles the transaction"bridge":"cbridge",// bridge that handles the transaction"status":"new",// transaction status in the system"useLoyalty":true,// loyalty program availability flag"transferDataFrom": { // transaction data on the departure network"network":"POL",// departure network symbol"crypto":"USDC",// departure token symbol"decimals":6,// departure token decimals"amount":"26773259",// transfer amount"amountInUsd":"26.77"// transfer amount in USD },"transferDataTo": { // transaction data on the destination network"network":"FTM",// destination network symbol"crypto":"USDC",// destination token symbol"decimals":6,// destination token decimals"amount":"26741575",// amount to be received"amountInUsd":"26.74"// amount to be received в USD },"fee": { // bridges and routers fee data"amount":"0.4",// amount of fee in cryptocurrency"symbol":"USDC",// fee currency symbol"decimals":6,// fee currency decimals"amountInUsd":"0.4"// amount of fee in USD } } ]}
Example of sent data validation error (HTTP code 400):
{"success":false,// request success flag"message":"Validation error",// error message"errors": [ // list of errors {"field":"networkFrom",// request field, the validation of which ended with an error"messages": [ // validation error messages"Field are required" ] } ]}
Example of a common request error (HTTP code 400):
{"success":false,// request success flag"message":"Internal Server Error"// error message}
Transfer data request (advanced option, second step)
GET /2.0/client/transaction-data
Accepts the following parameters:
id (string, required) - transaction id (from transaction routers list request)
This call returns the data of the requested transaction for subsequent signing and sending to the network
An example of a successful response (HTTP Code 200):
{"success":true,// request success flag"data": {"approve": { // data to confirm token withdrawal (if tokens are sent); if native tokens - this block is empty"data":"0x0",// transfer data, which must be signed with a private key "addressFrom": "0x4c33c110EA0873c549a6cC1F615bAB9fD7D21263d", // departure address from which the approval is sent
"addressTo": "0x5c59718F693b2FDbC7c3d8449581dC3a8435AA54", // address to which the approval is sent (the address of the token in the departure network)
"gasLimit":"0x11170",// the amount of gas the approval burns (in hex format)"gasPrice":"0xaa27ae7f5",// gas price in hex format"nonce":"0x1a",// serial number of the transaction at the address in hex format"coinValue":"0x0",// the number of native tokens sent upon confirmation"tokenValue":"0x198870b",// the number of tokens for approval (in hex format)"chainId":137// departure network ID },"transfer": { // data for transfer initialization"data":"0х0",// transfer data, which must be signed with the private key "addressFrom": "0x4c33c110EA0873c58a6cC1F615bAB9fD7D21263d", // address from which the transfer is initialized
"addressTo": "0x5c59718F693b9FDbC7c3d3149581dC3a8435AA54", // address to which the transfer is initialized (usually a bridge/router contract)
"gasLimit":"0xf6dfe",// the amount of gas the transfer burns (in hex format)"gasPrice":"0xa8d4dc606",// gas price in hex format"nonce":"0x1b",// the serial number of the transaction in hex format"coinValue":"0x0",// the number of native tokens sent upon transfer initialization"tokenValue":"0x198870b",// the number of tokens sent upon transfer initialization"chainId":137// departure network ID } }}
Example of sent data validation error (HTTP code 400):
{"success":false,// request success flag"message":"Validation error",// error message"errors": [ // list of errors {"field":"networkFrom",// request field, the validation of which ended with an error"messages": [ // validation error messages"Field are required" ] } ]}
Example of a common request error (HTTP code 400):
{"success":false,// request success flag"message":"Internal Server Error"// error message}
Transaction status request
GET /2.0/client/transaction-status
Accepts the following parameters:
id (string, required) - transaction id
This request returns the status of the created transaction
The list of statuses:
new - new transaction
in_progress - the transfer was initialized
finished - the transfer has been successfully completed, and the tokens have been transferred to the destination network
rejected - an error occurred during the transfer
An example of a successful request (HTTP code 200):
{"success":true,// request success flag"data": { // transaction data"id":"33d728b1-dd7a-4e46-9bea-d8b0f7197286",// transaction ID"status":"finished",// transaction status "approveHash": "0xc58c570647c6130b26434908c82fd37d9f15cc44c2c6559541820c26cea8654a", // hash of token transaction confirmation (if a native token is sent - this field is empty)
"source": { // departure network data"network":"FTM",// departure network symbol"crypto":"USDC",// departure token symbol "hash": "0xb47d5618a0313f728a8357fd69a707b1eaf5784df334f4d976a976083ba9685a" // Transfer initialization hash on the departure network
},"destination": { // destination network data"network":"POL",// destination network symbol"crypto":"USDC",// destination token symbol "hash": "0xdca6fa7c6c4500a950faed1d8266059b786fe3d826e047bdff39b015c9d4e11d" // Token transfer hash on the destination network
} },}
Example of sent data validation error (HTTP code 400):
{"success":false,// request success flag"message":"Validation error",// error message"errors": [ // list of errors {"field":"id",// request field, the validation of which ended with an error"messages": [ // validation error messages"Field are required" ] } ]}
Example of a common request error (HTTP code 400):
