Ethereum Documentation

Postman

Postman is a great software to test APIs, it helped us a lot when developing this API. If you haven't installed it yet, you can download it here.

We have created a Postman collection that allows to import all functions and their settings, including descriptions in Postman. This way you can test all functions with the click of a button (just change the parameters before).

You can import the collection by clicking the button below:

---

Postman Documentation

While we worked a lot with Postman, we found this beautiful feature to generate a whole documentation out of a collection. It includes examples of using all Chaingateway.io functions in all popular programming languages, which is great for beginners but also advanced developers. It is really recommended to check it out!

Open Postman Documentation

---

Tutorials

We wrote a few step-by-step tutorials with example code in PHP that might help you to work with our solution. Currently there is one tutorial for every request type.
Address Requests: Create Ethereum addresses
Transaction Requests: Send ERC20 token transactions
Info Requests: Get ERC20 token balances
IPN/Subscription Requests: Subscribe to ERC20 token deposits

---

API Requests

All Requests to our API are made in JSON format using HTTP POST. We will also return everything in JSON format. The Europe API endpoint is located at https://eu.eth.chaingateway.io/v1/{function}. We are currently working on providing an US based endpoint.

---

API Key

You can get your personal API Key from your account dashboard. It is used by us to determine who is accessing the API and to count the requests by that account. There are 2 possibilities to use it in your requests:

1. Add it to the JSON body in your request, like
   "apikey": "q9PdaWuD4j6DK6vsUgehhL8pgarSrS9m". This is not recommended!
2. Add it in the HTTP header as
   'Authorization: q9PdaWuD4j6DK6vsUgehhL8pgarSrS9m'. This is way more secure and may be the only option in future versions.

Please do not share your api key! If you did so by mistake, immediately regenerate it in your account panel!

---

Parameters

Ethereum Address

This is an ethereum address, which has 0x in front and 40 hexadecimal characters after it. CAUTION: If you send tokens, the receiving address must be ERC20 compatible. So please don't use an exchange address.

Contract Address

The contract address is the ethereum smart contract address of the ERC20 token you want to use. It has the same format as normal Ethereum addresses.

Amount

We want amounts to be in normal decimal format. If you want to send 2.5 ETH, use 2.5. If you want to send 1 million tokens, use 1000000. If you are not sure how many decimals a token has, you can use the getToken function.

Password

Whenever you create a new ethereum address, you need to specify a password for it. This password is used for all transactions you are doing with this address. We don't save this password, so please don't lose it.

Identifier

The identifier parameter allows to attach an unique string (Up to 32 characters) to a transaction. If the identifier has been used for a transaction in the last 30 days already, our API won't process the transaction. This prevents double sending of the same transaction in case you don't get a response from our API.

---

Security

Our API is very secure. The Nodes are not hosted on the same machine as the API endpoint. Also, they are not using the standard port and have a few proxies running in front. They are protected with a few firewalls, ddos protection and breach detection, too. We also have protected our endpoint and nodes against bruteforce. Sensitive data, especially keystores are being saved only with really strong and military proof encryption. But even if someone would get control over our systems, your funds would still be save. Like you can see above, every ethereum address needs a password for transactions. Without it, the funds can't be accessed. This means our system is as secure as your application. If you don't secure your system and don't store the passwords in a safe way, attackers may be able to steal funds from your addresses. (They still need your API Key however)

---

Fees

We are charging on a monthly plan basis if you use our API. You can see the exact pricing and request amounts here. There are also transaction fees, which go to the ethereum miners to include your transaction in a block. So please make sure there is always enough ethereum on the address you are sending tokens or ethereum from. The exact fee which is used is determined by the average gas fee at that time (If not specified otherwise).

---

Receiving Subscriptions/IPNs

Once we detect a balance update in one of your subscriptions, we will delay a JSON formatted call to the URL you provided. You will need to return {"ok": true} in JSON format after receiving so our system knows you received the call successfully. If you don't return ok, we will try to send the call again 10 times within 10 minutes.

Here is an explanation of the parameters we send you:


An example of a call would look like this:

{"id": 141854, "action": "deposit", "type": "ERC20", "ethereumaddress": "0xa1f36016221d48ce7f15cde7b826a4fbe09bacce", "contractaddress": "0x5b86a33f0c232fe909eb4602a9d039072869d915", "amount": 0.0464537, "timestamp": "2021-08-30 15:15:39"}

---

getEthereumBalance

Endpoint:
https://eu.eth.chaingateway.io/v1/getEthereumBalance

HTTP Method: POST



Example Request JSON:
{"ethereumaddress": "0xa1f36016221d48ce7f15cde7b826a4fbe09bacce", "apikey": "q9PdaWuD4j6DK6vsUgehhL8pgarSrS9m"}

Example Response JSON:
{"ok": true, "ethereumaddress": "0xa1f36016221d48ce7f15cde7b826a4fbe09bacce", "balance": 0.456}

---

getTokenBalance

Endpoint:
https://eu.eth.chaingateway.io/v1/getTokenBalance

HTTP Method: POST



Example Request JSON:
{"contractaddress": "0x5b86a33f0c232fe909eb4602a9d039072869d915", "ethereumaddress": "0xa1f36016221d48ce7f15cde7b826a4fbe09bacce", "apikey": "q9PdaWuD4j6DK6vsUgehhL8pgarSrS9m"}

Example Response JSON:
{"ok": true, "ethereumaddress": "0xa1f36016221d48ce7f15cde7b826a4fbe09bacce", "contractaddress": "0x5b86a33f0c232fe909eb4602a9d039072869d915", "balance": 0.456}

---

listAddresses

Endpoint:
https://eu.eth.chaingateway.io/v1/listAddresses

HTTP Method: POST



Example Request JSON:
{"apikey": "q9PdaWuD4j6DK6vsUgehhL8pgarSrS9m"}

Example Response JSON:
{"ok":true,"addresses":[{"ethaddress":"0xa1f36016221d48ce7f15cde7b826a4fbe09bacce"}]}

---

importAddress

Endpoint:
https://eu.eth.chaingateway.io/v1/importAddress

HTTP Method: POST



Example Request JSON:
{"apikey": "q9PdaWuD4j6DK6vsUgehhL8pgarSrS9m", "filename": "UTC--2020-05-01T12-30-12.020Z--4fb45889cd2d3348348e39c613c41bf1dc43760a", "content": {"version":3,"id":"f0449f3f-1ef2-5fb9-bf09-20bb72c47167","address":"4fb45889cd2d3348348e39c613c41bf1dc43760a","crypto":{"ciphertext":"027fbbe9d7b91b1a4a3afddcb27a07ac5e7fff550fd167452a6345a961f21a4d","cipherparams":{"iv":"a2b3022a9d7d76ade60dd70e5405cc09"},"cipher":"aes-128-ctr","kdf":"scrypt","kdfparams":{"dklen":32,"salt":"fd84f455da4ad1325cf5bc7beb06bf3052919278c76373a67507aaa68bcebab3","n":131056,"r":6,"p":1},"mac":"d46d36b6facd1f3f5549f01cb5c87de0c01b68b6445410259128c52d515a7b6d"}}, "password": "padN39QkRA2hJ"}

Example Response JSON:
{"ok":true,"ethaddress": "0x4fb45889cd2d3348348e39c613c41bf1dc43760a", "filename": "UTC--2020-05-01T12-30-12.020Z--4fb45889cd2d3348348e39c613c41bf1dc43760a"}

---

exportAddress

Endpoint:
https://eu.eth.chaingateway.io/v1/exportAddress

HTTP Method: POST



Example Request JSON:
{"apikey": "q9PdaWuD4j6DK6vsUgehhL8pgarSrS9m", "ethaddress": "0x4fb45889cd2d3348348e39c613c41bf1dc43760a", "password": "padN39QkRA2hJ"}

Example Response JSON:
{"ok":true, "filename": "UTC--2020-05-01T12-30-12.020Z--4fb45889cd2d3348348e39c613c41bf1dc43760a", "content": {"version":3,"id":"f0449f3f-1ef2-5fb9-bf09-20bb72c47167","address":"4fb45889cd2d3348348e39c613c41bf1dc43760a","crypto":{"ciphertext":"027fbbe9d7b91b1a4a3afddcb27a07ac5e7fff550fd167452a6345a961f21a4d","cipherparams":{"iv":"a2b3022a9d7d76ade60dd70e5405cc09"},"cipher":"aes-128-ctr","kdf":"scrypt","kdfparams":{"dklen":32,"salt":"fd84f455da4ad1325cf5bc7beb06bf3052919278c76373a67507aaa68bcebab3","n":131056,"r":6,"p":1},"mac":"d46d36b6facd1f3f5549f01cb5c87de0c01b68b6445410259128c52d515a7b6d"}}}

---

subscribeAddress

Endpoint:
https://eu.eth.chaingateway.io/v1/subscribeAddress

HTTP Method: POST



Example Request JSON:
{"apikey": "q9PdaWuD4j6DK6vsUgehhL8pgarSrS9m","ethereumaddress": "0xa1f36016221d48ce7f15cde7b826a4fbe09bacce", "contractaddress": "0x5b86a33f0c232fe909eb4602a9d039072869d915", "url": "https://yoururl.com/ipnreceiver.php"}

Example Response JSON:
{"ok":true, "ethereumaddress": "0xa1f36016221d48ce7f15cde7b826a4fbe09bacce", "contractaddress": "0x5b86a33f0c232fe909eb4602a9d039072869d915", "url": "https://yoururl.com/ipnreceiver.php"}

---

UnsubscribeAddress

Endpoint:
https://eu.eth.chaingateway.io/v1/unsubscribeAddress

HTTP Method: POST



Example Request JSON:
{"apikey": "q9PdaWuD4j6DK6vsUgehhL8pgarSrS9m","ethereumaddress": "0xa1f36016221d48ce7f15cde7b826a4fbe09bacce", "contractaddress": "0x5b86a33f0c232fe909eb4602a9d039072869d915", "url": "https://yoururl.com/ipnreceiver.php"}

Example Response JSON:
{"ok":true, "ethereumaddress": "0xa1f36016221d48ce7f15cde7b826a4fbe09bacce", "contractaddress": "0x5b86a33f0c232fe909eb4602a9d039072869d915", "url": "https://yoururl.com/ipnreceiver.php", "deleted": true}

---

listSubscribedAddresses

Endpoint:
https://eu.eth.chaingateway.io/v1/listSubscribedAddresses

HTTP Method: POST



Example Request JSON:
{"apikey": "q9PdaWuD4j6DK6vsUgehhL8pgarSrS9m"}

Example Response JSON:
{"ok":true,"ipns":[{"ethereumaddress": "0xa1f36016221d48ce7f15cde7b826a4fbe09bacce", "contractaddress": "0x5b86a33f0c232fe909eb4602a9d039072869d915", "url": "https://yoururl.com/ipnreceiver.php"}]}

---

listFailedIPNs

Endpoint:
https://eu.eth.chaingateway.io/v1/listFailedIPNs

HTTP Method: POST



Example Request JSON:
{"apikey": "q9PdaWuD4j6DK6vsUgehhL8pgarSrS9m"}

Example Response JSON:
{"ok":true,"failed_ipns":[{"id":"182659","timestamp":"2019-12-18 17:14:36","ethereumaddress":"0xa1f36016221d48ce7f15cde7b826a4fbe09bacce", "contractaddress":null,"amount":"0.0277", "url":"https:\/\/yoururl.com/ipnreceiver.php","action":"withdraw"}]}

---

resendFailedIPN

Endpoint:
https://eu.eth.chaingateway.io/v1/resendFailedIPN

HTTP Method: POST



Example Request JSON:
{"apikey": "q9PdaWuD4j6DK6vsUgehhL8pgarSrS9m", "id": 182659}

Example Response JSON:
{"ok":true, "id": 182659}

---

newAddress

Endpoint:
https://eu.eth.chaingateway.io/v1/newAddress

HTTP Method: POST



Example Request JSON:
{"password": "padN39QkRA2hJ", "apikey": "q9PdaWuD4j6DK6vsUgehhL8pgarSrS9m"}

Example Response JSON:
{"ok": true, "ethereumaddress": "0xa1f36016221d48ce7f15cde7b826a4fbe09bacce", "password": "padN39QkRA2hJ"}

---

deleteAddress

Endpoint:
https://eu.eth.chaingateway.io/v1/deleteAddress

HTTP Method: POST



Example Request JSON:
{"ethereumaddress": "0xa1f36016221d48ce7f15cde7b826a4fbe09bacce", "apikey": "q9PdaWuD4j6DK6vsUgehhL8pgarSrS9m", "password": "padN39QkRA2hJ"}

Example Response JSON:
{"ok": true, "ethereumaddress": "0xa1f36016221d48ce7f15cde7b826a4fbe09bacce", "deleted": true}

---

sendEthereum

Endpoint:
https://eu.eth.chaingateway.io/v1/sendEthereum

HTTP Method: POST



Example Request JSON:
{"from": "0xa1f36016221d48ce7f15cde7b826a4fbe09bacce", "to": "0xef4943d727e34280a2efa0b3352dfd61f508ee48", "password": "padN39QkRA2hJ", "amount": 0.05, "apikey": "q9PdaWuD4j6DK6vsUgehhL8pgarSrS9m", "gas": 21000}

Example Response JSON:
{"ok": true, "txid": "0xcff06775098019d18f7bab6a350c18e86f89399d b63cbce5269104e6c9a79499", "from": "0xa1f36016221d48ce7f15cde7b826a4fbe09bacce", "to": "0xef4943d727e34280a2efa0b3352dfd61f508ee48", "amount": 0.05}

---

clearAddress

Endpoint:
https://eu.eth.chaingateway.io/v1/clearAddress

HTTP Method: POST



Example Request JSON:
{"ethereumaddress": "0xa1f36016221d48ce7f15cde7b826a4fbe09bacce", "newaddress": "0xef4943d727e34280a2efa0b3352dfd61f508ee48", "password": "padN39QkRA2hJ", "apikey": "q9PdaWuD4j6DK6vsUgehhL8pgarSrS9m"}

Example Response JSON:
{"ok": true, "txid": "0xcff06775098019d18f7bab6a350c18e86f89399d b63cbce5269104e6c9a79499", "ethereumaddress": "0xa1f36016221d48ce7f15cde7b826a4fbe09bacce", "newaddress": "0xef4943d727e34280a2efa0b3352dfd61f508ee48", "amount: 0.00980226, "gas": 0.000063, "total": 0.00986526}

---

sendToken

Endpoint:
https://eu.eth.chaingateway.io/v1/sendToken

HTTP Method: POST


Example Request JSON:
{"contractaddress": "0x5b86a33f0c232fe909eb4602a9d039072869d915", "from": "0xa1f36016221d48ce7f15cde7b826a4fbe09bacce", "to": "0xef4943d727e34280a2efa0b3352dfd61f508ee48", "password": "padN39QkRA2hJ", "amount": 0.05, "gasprice": 5, "gas": 90000, "apikey": "q9PdaWuD4j6DK6vsUgehhL8pgarSrS9m"}

Example Response JSON:
{"ok": true, "txid": "0xcff06775098019d18f7bab6a350c18e86f89399d b63cbce5269104e6c9a79499", "contractaddress": "0x5b86a33f0c232fe909eb4602a9d039072869d915", "from": "0xa1f36016221d48ce7f15cde7b826a4fbe09bacce", "to": "0xef4943d727e34280a2efa0b3352dfd61f508ee48", "amount": 0.05}

---