Raiden’s API Documentation¶
Introduction¶
Raiden has a Restful API with URL endpoints corresponding to user-facing interaction allowed by a Raiden node. The endpoints accept and return JSON encoded objects. The api url path always contains the api version in order to differentiate queries to
different API versions. All queries start with: /api/<version>/
JSON Object Encoding¶
The objects that are sent to and received from the API are JSON-encoded. Following are the common objects used in the API.
Channel Object¶
{
"channel_identifier": "21",
"token_network_address": "0x2a65Aca4D5fC5B5C859090a6c34d164135398226",
"partner_address": "0x61C808D82A3Ac53231750daDc13c777b59310bD9",
"token_address": "0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8",
"balance": "25000000",
"total_deposit": "35000000",
"state": "opened",
"settle_timeout": "500",
"reveal_timeout": "50"
}
A channel object consists of a
channel_identifier
should be aninteger
containing the identifier of the channel.partner_address
should be astring
containing the EIP55-encoded address of the partner with whom we have opened a channel.token_address
should be astring
containing the EIP55-encoded address of the token we are trading in the channel.token_network_address
should be astring
containing the EIP55-encoded address of the token network the channel is part of.balance
should be an integer of the amount of thetoken_address
token we have available for payments.total_deposit
should be an integer of the amount of thetoken_address
token we have deposited into the contract for this channel.state
should be the current state of the channel represented by a string. Possible value are: -'opened'
: The channel is open and tokens are tradeable -'closed'
: The channel has been closed by a participant -'settled'
: The channel has been closed by a participant and also settled.'settle_timeout'
: The number of blocks that are required to be mined from the time thatclose()
is called until the channel can be settled with a call tosettle()
.'reveal_timeout'
: The maximum number of blocks allowed between the setting of a hashlock and the revealing of the related secret.
Event Object¶
Channel events are encoded as json objects with the event arguments as attributes
of the dictionary, with one difference. The event_type
and the block_number
are also added for all events to easily distinguish between events.
Errors¶
For any non-successful http status code, e.g. 409 Conflict or 400 Bad Request there will be an accompanying errors
field in the response json which you can check for more information on what went wrong with your request.
However, when Raiden fails to process the incoming request and raises an exception, the returned http status code will be 500 Internal Server Error. The caveat of this is that the response body will be just a string message which says “Internal server error”.
This is because we rely on our underlying stack to handle this while we take care of shutting down the API server preventing further incoming requests caused the exception in the first place from tampering with a state that was corrupted.
In any way, we consider 500 Internal Server Error errors as bugs in the Raiden client. If you encounter such errors, please report the bug here.
Endpoints¶
Following are the available API endpoints with which you can interact with Raiden.
Querying Information About Your Raiden Node¶
-
GET
/api/
(version)/address
¶ Query your address. When raiden starts, you choose an ethereum address which will also be your raiden address.
Example Request:
GET /api/v1/address HTTP/1.1 Host: localhost:5001
curl -i http://localhost:5001/api/v1/address
wget -S -O- http://localhost:5001/api/v1/address
http http://localhost:5001/api/v1/address
requests.get('http://localhost:5001/api/v1/address')
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "our_address": "0x2a65Aca4D5fC5B5C859090a6c34d164135398226" }
-
GET
/api/
(version)/version
¶ Query the version of the Raiden instance
Example Request:
GET /api/v1/version HTTP/1.1 Host: localhost:5001
curl -i http://localhost:5001/api/v1/version
wget -S -O- http://localhost:5001/api/v1/version
http http://localhost:5001/api/v1/version
requests.get('http://localhost:5001/api/v1/version')
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "version": "0.100.5a1.dev157+geb2af878d" }
Deploying¶
Note
For the Raiden Red Eyes release, it will not be possible to register more than one token, due to security reasons in order to minimise possible loss of funds in the case of bugs. The one token that will be registered is W-ETH.
-
PUT
/api/
(version)/tokens/
(token_address)¶ Registers a token. If a token is not registered yet (i.e.: A token network for that token does not exist in the registry), we need to register it by deploying a token network contract for that token.
Example Request:
PUT /api/v1/tokens/0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8 HTTP/1.1 Host: localhost:5001
curl -i -X PUT http://localhost:5001/api/v1/tokens/0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8
wget -S -O- --method=PUT http://localhost:5001/api/v1/tokens/0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8
http PUT http://localhost:5001/api/v1/tokens/0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8
requests.put('http://localhost:5001/api/v1/tokens/0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8')
Example Response:
HTTP/1.1 201 CREATED Content-Type: application/json { "token_network_address": "0xC4F8393fb7971E8B299bC1b302F85BfFB3a1275a" }
Status Codes: - 201 Created – A token network for the token has been successfully created.
- 402 Payment Required – Insufficient ETH to pay for the gas of the register on-chain transaction
- 403 Forbidden – Maximum of allowed token networks reached. No new token networks can be registered.
- 404 Not Found – The given token address is invalid.
- 409 Conflict –
- The token was already registered before, or
- The registering transaction failed.
- 501 Not Implemented – Registering a token only works on testnet temporarily. On mainnet this error is returned.
- 503 Service Unavailable – The API is currently unavailable, e. g. because the Raiden node is still in the initial sync or shutting down.
Response JSON Object: - token_network_address (address) – The deployed token networks address.
Querying Information About Channels and Tokens¶
-
GET
/api/
(version)/channels
¶ Get a list of all unsettled channels.
Example Request:
GET /api/v1/channels HTTP/1.1 Host: localhost:5001
curl -i http://localhost:5001/api/v1/channels
wget -S -O- http://localhost:5001/api/v1/channels
http http://localhost:5001/api/v1/channels
requests.get('http://localhost:5001/api/v1/channels')
Example Response:
HTTP/1.1 200 OK Content-Type: application/json [ { "token_network_address": "0xE5637F0103794C7e05469A9964E4563089a5E6f2", "channel_identifier": "20", "partner_address": "0x61C808D82A3Ac53231750daDc13c777b59310bD9", "token_address": "0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8", "balance": "25000000", "total_deposit": "35000000", "total_withdraw": "5000000", "state": "opened", "settle_timeout": "500", "reveal_timeout": "50" } ]
Status Codes: - 200 OK – Successful query
- 500 Internal Server Error – Internal Raiden node error
- 503 Service Unavailable – The API is currently unavailable, e. g. because the Raiden node is still in the initial sync or shutting down.
-
GET
/api/
(version)/channels/
(token_address)¶ Get a list of all unsettled channels for the given token address.
Example Request:
GET /api/v1/channels/0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8 HTTP/1.1 Host: localhost:5001
curl -i http://localhost:5001/api/v1/channels/0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8
wget -S -O- http://localhost:5001/api/v1/channels/0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8
http http://localhost:5001/api/v1/channels/0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8
requests.get('http://localhost:5001/api/v1/channels/0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8')
Example Response:
HTTP/1.1 200 OK Content-Type: application/json [ { "token_network_address": "0xE5637F0103794C7e05469A9964E4563089a5E6f2", "channel_identifier": "20", "partner_address": "0x61C808D82A3Ac53231750daDc13c777b59310bD9", "token_address": "0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8", "balance": "25000000", "total_deposit": "35000000", "total_withdraw": "5000000", "state": "opened", "settle_timeout": "500", "reveal_timeout": "50" } ]
Status Codes: - 200 OK – Successful query
- 404 Not Found – The given token address is not a valid eip55-encoded Ethereum address
- 500 Internal Server Error – Internal Raiden node error
- 503 Service Unavailable – The API is currently unavailable, e. g. because the Raiden node is still in the initial sync or shutting down.
-
GET
/api/
(version)/channels/
(token_address)/
(partner_address)¶ Query information about one of your channels. The channel is specified by the address of the token and the partner’s address.
Example Request:
GET /api/v1/channels/0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8/0x61C808D82A3Ac53231750daDc13c777b59310bD9 HTTP/1.1 Host: localhost:5001
curl -i http://localhost:5001/api/v1/channels/0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8/0x61C808D82A3Ac53231750daDc13c777b59310bD9
wget -S -O- http://localhost:5001/api/v1/channels/0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8/0x61C808D82A3Ac53231750daDc13c777b59310bD9
http http://localhost:5001/api/v1/channels/0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8/0x61C808D82A3Ac53231750daDc13c777b59310bD9
requests.get('http://localhost:5001/api/v1/channels/0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8/0x61C808D82A3Ac53231750daDc13c777b59310bD9')
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "token_network_address": "0xE5637F0103794C7e05469A9964E4563089a5E6f2", "channel_identifier": "20", "partner_address": "0x61C808D82A3Ac53231750daDc13c777b59310bD9", "token_address": "0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8", "balance": "25000000", "total_deposit": "35000000", "total_withdraw": "5000000", "state": "opened", "settle_timeout": "500", "reveal_timeout": "50" }
Status Codes: - 200 OK – Successful query
- 404 Not Found –
- The given token and / or partner addresses are not valid eip55-encoded Ethereum addresses, or
- The channel does not exist
- 500 Internal Server Error – Internal Raiden node error
- 503 Service Unavailable – The API is currently unavailable, e. g. because the Raiden node is still in the initial sync or shutting down.
-
GET
/api/
(version)/tokens
¶ Returns a list of addresses of all registered tokens.
Example Request:
GET /api/v1/tokens HTTP/1.1 Host: localhost:5001
curl -i http://localhost:5001/api/v1/tokens
wget -S -O- http://localhost:5001/api/v1/tokens
http http://localhost:5001/api/v1/tokens
requests.get('http://localhost:5001/api/v1/tokens')
Example Response:
HTTP/1.1 200 OK Content-Type: application/json [ "0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8", "0x61bB630D3B2e8eda0FC1d50F9f958eC02e3969F6" ]
Status Codes: - 200 OK – Successful query
- 500 Internal Server Error – Internal Raiden node error
- 503 Service Unavailable – The API is currently unavailable, e. g. because the Raiden node is still in the initial sync or shutting down.
-
GET
/api/
(version)/tokens/
(token_address)¶ Returns the address of the corresponding token network for the given token, if the token is registered.
Example Request:
GET /api/v1/tokens/0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8 HTTP/1.1 Host: localhost:5001
curl -i http://localhost:5001/api/v1/tokens/0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8
wget -S -O- http://localhost:5001/api/v1/tokens/0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8
http http://localhost:5001/api/v1/tokens/0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8
requests.get('http://localhost:5001/api/v1/tokens/0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8')
Example Response:
HTTP/1.1 200 OK Content-Type: application/json "0x61bB630D3B2e8eda0FC1d50F9f958eC02e3969F6"
Status Codes: - 200 OK – Successful query
- 404 Not Found – No token network found for the provided token address
- 503 Service Unavailable – The API is currently unavailable, e. g. because the Raiden node is still in the initial sync or shutting down.
-
GET
/api/
(version)/tokens/
(token_address)/partners
¶ Returns a list of all partners with whom you have non-settled channels for a certain token.
Example Request:
GET /api/v1/tokens/0x61bB630D3B2e8eda0FC1d50F9f958eC02e3969F6/partners HTTP/1.1 Host: localhost:5001
curl -i http://localhost:5001/api/v1/tokens/0x61bB630D3B2e8eda0FC1d50F9f958eC02e3969F6/partners
wget -S -O- http://localhost:5001/api/v1/tokens/0x61bB630D3B2e8eda0FC1d50F9f958eC02e3969F6/partners
http http://localhost:5001/api/v1/tokens/0x61bB630D3B2e8eda0FC1d50F9f958eC02e3969F6/partners
requests.get('http://localhost:5001/api/v1/tokens/0x61bB630D3B2e8eda0FC1d50F9f958eC02e3969F6/partners')
Example Response:
HTTP/1.1 200 OK Content-Type: application/json [ { "partner_address": "0x2a65aca4d5fc5b5c859090a6c34d164135398226", "channel": "/api/<version>/channels/0x61C808D82A3Ac53231750daDc13c777b59310bD9/0x2a65aca4d5fc5b5c859090a6c34d164135398226" } ]
Status Codes: - 200 OK – Successful query
- 302 Found – If the user accesses the channel link endpoint
- 404 Not Found –
- The token does not exist
- The token address is not a valid eip55-encoded Ethereum address
- 500 Internal Server Error – Internal Raiden node error
- 503 Service Unavailable – The API is currently unavailable, e. g. because the Raiden node is still in the initial sync or shutting down.
Response JSON Array of Objects: - partner_address (address) – The partner we have a channel with
- channel (link) – A link to the channel resource
-
GET
/api/
(version)/pending_transfers
¶ Returns a list of all transfers that have not been completed yet.
Example Request:
GET /api/v1/pending_transfers HTTP/1.1 Host: localhost:5001
curl -i http://localhost:5001/api/v1/pending_transfers
wget -S -O- http://localhost:5001/api/v1/pending_transfers
http http://localhost:5001/api/v1/pending_transfers
requests.get('http://localhost:5001/api/v1/pending_transfers')
See below for an example response.
-
GET
/api/
(version)/pending_transfers/
(token_address)¶ Like above, but limited to pending transfers of the specified token.
Example Request:
GET /api/v1/pending_transfers/0xd0A1E359811322d97991E03f863a0C30C2cF029C HTTP/1.1 Host: localhost:5001
curl -i http://localhost:5001/api/v1/pending_transfers/0xd0A1E359811322d97991E03f863a0C30C2cF029C
wget -S -O- http://localhost:5001/api/v1/pending_transfers/0xd0A1E359811322d97991E03f863a0C30C2cF029C
http http://localhost:5001/api/v1/pending_transfers/0xd0A1E359811322d97991E03f863a0C30C2cF029C
requests.get('http://localhost:5001/api/v1/pending_transfers/0xd0A1E359811322d97991E03f863a0C30C2cF029C')
See below for an example response.
-
GET
/api/
(version)/pending_transfers/
(token_address)/
(partner_address)¶ Like above, but limited to the specified channel.
Example Request:
GET /api/v1/pending_transfers/0xd0A1E359811322d97991E03f863a0C30C2cF029C/0x2c4b0Bdac486d492E3cD701F4cA87e480AE4C685 HTTP/1.1 Host: localhost:5001
curl -i http://localhost:5001/api/v1/pending_transfers/0xd0A1E359811322d97991E03f863a0C30C2cF029C/0x2c4b0Bdac486d492E3cD701F4cA87e480AE4C685
wget -S -O- http://localhost:5001/api/v1/pending_transfers/0xd0A1E359811322d97991E03f863a0C30C2cF029C/0x2c4b0Bdac486d492E3cD701F4cA87e480AE4C685
http http://localhost:5001/api/v1/pending_transfers/0xd0A1E359811322d97991E03f863a0C30C2cF029C/0x2c4b0Bdac486d492E3cD701F4cA87e480AE4C685
requests.get('http://localhost:5001/api/v1/pending_transfers/0xd0A1E359811322d97991E03f863a0C30C2cF029C/0x2c4b0Bdac486d492E3cD701F4cA87e480AE4C685')
Example Response:
HTTP/1.1 200 OK Content-Type: application/json [ { "channel_identifier": "255", "initiator": "0x5E1a3601538f94c9e6D2B40F7589030ac5885FE7", "locked_amount": "119", "payment_identifier": "1", "role": "initiator", "target": "0x00AF5cBfc8dC76cd599aF623E60F763228906F3E", "token_address": "0xd0A1E359811322d97991E03f863a0C30C2cF029C", "token_network_address": "0x111157460c0F41EfD9107239B7864c062aA8B978", "transferred_amount": "331" } ]
Status Codes: - 200 OK – Successful query
- 404 Not Found – The queried channel or token was not found
- 500 Internal Server Error – Internal Raiden node error
- 503 Service Unavailable – The API is currently unavailable, e. g. because the Raiden node is still in the initial sync or shutting down.
Response JSON Array of Objects: - role (string) – One of “initiator”, “mediator” and “target”
Channel Management¶
-
PUT
/api/
(version)/channels
¶ Opens (i. e. creates) a channel.
Example Request:
PUT /api/v1/channels HTTP/1.1 Host: localhost:5001 Content-Type: application/json { "partner_address": "0x61C808D82A3Ac53231750daDc13c777b59310bD9", "token_address": "0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8", "total_deposit": "35000000", "settle_timeout": "500", "reveal_timeout": "50" }
curl -i -X PUT http://localhost:5001/api/v1/channels -H 'Content-Type: application/json' --data-raw '{"partner_address": "0x61C808D82A3Ac53231750daDc13c777b59310bD9", "reveal_timeout": "50", "settle_timeout": "500", "token_address": "0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8", "total_deposit": "35000000"}'
wget -S -O- --method=PUT http://localhost:5001/api/v1/channels --header='Content-Type: application/json' --body-data='{"partner_address": "0x61C808D82A3Ac53231750daDc13c777b59310bD9", "reveal_timeout": "50", "settle_timeout": "500", "token_address": "0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8", "total_deposit": "35000000"}'
echo '{ "partner_address": "0x61C808D82A3Ac53231750daDc13c777b59310bD9", "reveal_timeout": "50", "settle_timeout": "500", "token_address": "0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8", "total_deposit": "35000000" }' | http PUT http://localhost:5001/api/v1/channels Content-Type:application/json
requests.put('http://localhost:5001/api/v1/channels', headers={ 'Content-Type': 'application/json', }, json={ 'partner_address': '0x61C808D82A3Ac53231750daDc13c777b59310bD9', 'reveal_timeout': '50', 'settle_timeout': '500', 'token_address': '0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8', 'total_deposit': '35000000', })
Request JSON Object: - partner_address (address) – The partner we want to open a channel with.
- token_address (address) – The token we want to be used in the channel.
- total_deposit (int) – Total amount of tokens to be deposited to the channel
- settle_timeout (int) – The amount of blocks that the settle timeout should have.
- reveal_timeout (int) – The amount of blocks that the reveal timeout should have.
The request’s payload is a channel object; since it is a new channel, its
channel_address
andstatus
fields will be ignored and can be omitted.The request to the endpoint will later return the fully created channel object.
Note
For the Raiden Red Eyes release the maximum deposit per node in a channel is limited to 0.075 worth of W-ETH. This means that the maximum amount of tokens in a channel is limited to 0.15 worth of W-ETH. This is done to mitigate risk since the Red Eyes release is an alpha testing version on the mainnet.
Example Response:
HTTP/1.1 201 CREATED Content-Type: application/json { "token_network_address": "0xE5637F0103794C7e05469A9964E4563089a5E6f2", "channel_identifier": "20", "partner_address": "0x61C808D82A3Ac53231750daDc13c777b59310bD9", "token_address": "0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8", "balance": "25000000", "total_deposit": "35000000", "total_withdraw": "0", "state": "opened", "settle_timeout": "500", "reveal_timeout": "50" }
Status Codes: - 201 Created – Channel created successfully
- 400 Bad Request – Provided JSON is in some way malformed
- 402 Payment Required – Insufficient ETH to pay for the gas of the channel open on-chain transaction
- 408 Request Timeout – Deposit event was not read in time by the Ethereum node
- 409 Conflict – Invalid input, e. g. too low a settle timeout
- 500 Internal Server Error – Internal Raiden node error
- 503 Service Unavailable – The API is currently unavailable, e. g. because the Raiden node is still in the initial sync or shutting down.
-
PATCH
/api/
(version)/channels/
(token_address)/
(partner_address)¶ This request is used to close a channel or to increase the deposit in it.
Example Request (close channel):
PATCH /api/v1/channels/0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8/0x61C808D82A3Ac53231750daDc13c777b59310bD9 HTTP/1.1 Host: localhost:5001 Content-Type: application/json { "state": "closed" }
curl -i -X PATCH http://localhost:5001/api/v1/channels/0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8/0x61C808D82A3Ac53231750daDc13c777b59310bD9 -H 'Content-Type: application/json' --data-raw '{"state": "closed"}'
wget -S -O- --method=PATCH http://localhost:5001/api/v1/channels/0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8/0x61C808D82A3Ac53231750daDc13c777b59310bD9 --header='Content-Type: application/json' --body-data='{"state": "closed"}'
echo '{ "state": "closed" }' | http PATCH http://localhost:5001/api/v1/channels/0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8/0x61C808D82A3Ac53231750daDc13c777b59310bD9 Content-Type:application/json
requests.patch('http://localhost:5001/api/v1/channels/0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8/0x61C808D82A3Ac53231750daDc13c777b59310bD9', headers={ 'Content-Type': 'application/json', }, json={ 'state': 'closed', })
Example Request (increase deposit):
PATCH /api/v1/channels/0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8/0x61C808D82A3Ac53231750daDc13c777b59310bD9 HTTP/1.1 Host: localhost:5001 Content-Type: application/json { "total_deposit": "100" }
curl -i -X PATCH http://localhost:5001/api/v1/channels/0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8/0x61C808D82A3Ac53231750daDc13c777b59310bD9 -H 'Content-Type: application/json' --data-raw '{"total_deposit": "100"}'
wget -S -O- --method=PATCH http://localhost:5001/api/v1/channels/0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8/0x61C808D82A3Ac53231750daDc13c777b59310bD9 --header='Content-Type: application/json' --body-data='{"total_deposit": "100"}'
echo '{ "total_deposit": "100" }' | http PATCH http://localhost:5001/api/v1/channels/0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8/0x61C808D82A3Ac53231750daDc13c777b59310bD9 Content-Type:application/json
requests.patch('http://localhost:5001/api/v1/channels/0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8/0x61C808D82A3Ac53231750daDc13c777b59310bD9', headers={ 'Content-Type': 'application/json', }, json={ 'total_deposit': '100', })
Example Request (withdraw tokens):
PATCH /api/v1/channels/0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8/0x61C808D82A3Ac53231750daDc13c777b59310bD9 HTTP/1.1 Host: localhost:5001 Content-Type: application/json { "total_withdraw": "100" }
curl -i -X PATCH http://localhost:5001/api/v1/channels/0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8/0x61C808D82A3Ac53231750daDc13c777b59310bD9 -H 'Content-Type: application/json' --data-raw '{"total_withdraw": "100"}'
wget -S -O- --method=PATCH http://localhost:5001/api/v1/channels/0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8/0x61C808D82A3Ac53231750daDc13c777b59310bD9 --header='Content-Type: application/json' --body-data='{"total_withdraw": "100"}'
echo '{ "total_withdraw": "100" }' | http PATCH http://localhost:5001/api/v1/channels/0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8/0x61C808D82A3Ac53231750daDc13c777b59310bD9 Content-Type:application/json
requests.patch('http://localhost:5001/api/v1/channels/0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8/0x61C808D82A3Ac53231750daDc13c777b59310bD9', headers={ 'Content-Type': 'application/json', }, json={ 'total_withdraw': '100', })
Example Request (update channel reveal timeout):
PATCH /api/v1/channels/0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8/0x61C808D82A3Ac53231750daDc13c777b59310bD9 HTTP/1.1 Host: localhost:5001 Content-Type: application/json { "reveal_timeout": "50" }
curl -i -X PATCH http://localhost:5001/api/v1/channels/0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8/0x61C808D82A3Ac53231750daDc13c777b59310bD9 -H 'Content-Type: application/json' --data-raw '{"reveal_timeout": "50"}'
wget -S -O- --method=PATCH http://localhost:5001/api/v1/channels/0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8/0x61C808D82A3Ac53231750daDc13c777b59310bD9 --header='Content-Type: application/json' --body-data='{"reveal_timeout": "50"}'
echo '{ "reveal_timeout": "50" }' | http PATCH http://localhost:5001/api/v1/channels/0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8/0x61C808D82A3Ac53231750daDc13c777b59310bD9 Content-Type:application/json
requests.patch('http://localhost:5001/api/v1/channels/0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8/0x61C808D82A3Ac53231750daDc13c777b59310bD9', headers={ 'Content-Type': 'application/json', }, json={ 'reveal_timeout': '50', })
Request JSON Object: - state (string) – Desired new state; the only valid choice is
"closed"
- total_deposit (int) – The increased total deposit
- total_withdraw (int) – The increased total withdraw
- reveal_timeout (int) – The new reveal timeout value
Note
For the Raiden Red Eyes release the maximum deposit per node in a channel is limited to 0.075 worth of W-ETH. This means that the maximum amount of tokens in a channel is limited to 0.15 worth of W-ETH. This is done to mitigate risk since the Red Eyes release is an alpha testing version on the mainnet.
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "token_network_address": "0xE5637F0103794C7e05469A9964E4563089a5E6f2", "channel_identifier": "20", "partner_address": "0x61C808D82A3Ac53231750daDc13c777b59310bD9", "token_address": "0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8", "balance": "25000000", "total_deposit": "35000000", "total_withdraw": "5000000", "state": "closed", "settle_timeout": "500", "reveal_timeout": "50" }
Status Codes: - 200 OK – Success
- 400 Bad Request –
- The provided JSON is in some way malformed, or
- there is nothing to do since none of
state
,total_deposit
ortotal_withdraw
have been given, or - the value of
state
is not a valid channel state.
- 402 Payment Required – Insufficient balance to do a deposit, or insufficient ETH to pay for the gas of the on-chain transaction
- 404 Not Found – The given token and / or partner addresses are not valid eip55-encoded Ethereum addresses
- 408 Request Timeout – Deposit event was not read in time by the Ethereum node
- 409 Conflict –
- Provided channel does not exist or
state
,total_deposit
andtotal_withdraw
have been attempted to update in the same request or- attempt to deposit token amount lower than on-chain balance of the channel
- attempt to deposit more tokens than the testing limit
- 500 Internal Server Error – Internal Raiden node error
- 503 Service Unavailable – The API is currently unavailable, e. g. because the Raiden node is still in the initial sync or shutting down.
- state (string) – Desired new state; the only valid choice is
Connection Management¶
-
GET
/api/
(version)/connections
¶ Query details of all joined token networks.
The request will return a JSON object where each key is a token address for which you have open channels.
Example Request:
GET /api/v1/connections HTTP/1.1 Host: localhost:5001
curl -i http://localhost:5001/api/v1/connections
wget -S -O- http://localhost:5001/api/v1/connections
http http://localhost:5001/api/v1/connections
requests.get('http://localhost:5001/api/v1/connections')
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "0x2a65Aca4D5fC5B5C859090a6c34d164135398226": { "funds": "100", "sum_deposits": "67", "channels": "3" }, "0x0f114A1E9Db192502E7856309cc899952b3db1ED": { "funds": "49", "sum_deposits": "31", "channels": "1" } }
Status Codes: - 200 OK – For a successful query
- 500 Internal Server Error – Internal Raiden node error
- 503 Service Unavailable – The API is currently unavailable, e. g. because the Raiden node is still in the initial sync or shutting down.
Response JSON Array of Objects: - funds (int) – Funds from last connect request
- sum_deposits (int) – Sum of deposits of all currently open channels
- channels (int) – Number of channels currently open for that token
-
PUT
/api/
(version)/connections/
(token_address)¶ Automatically join a token network. The request will only return once all blockchain calls for opening and/or depositing to a channel have completed.
The request’s payload has
initial_channel_target
andjoinable_funds_target
as optional arguments. If not provided they default toinitial_channel_target = 3
andjoinable_funds_target = 0.4
.If the
initial_channel_target
is bigger than the current number of participants of the token network then the funds will still be split according to theinitial_channel_target
but the number of channels made will be equal to the number of participants in the network. So eventually you will end up with less channels, but each channel will have the expected number of funds allocated to it. The remaining channels will be opened once more peers become available.Example Request:
PUT /api/v1/connections/0x2a65Aca4D5fC5B5C859090a6c34d164135398226 HTTP/1.1 Host: localhost:5001 Content-Type: application/json { "funds": "1337" }
curl -i -X PUT http://localhost:5001/api/v1/connections/0x2a65Aca4D5fC5B5C859090a6c34d164135398226 -H 'Content-Type: application/json' --data-raw '{"funds": "1337"}'
wget -S -O- --method=PUT http://localhost:5001/api/v1/connections/0x2a65Aca4D5fC5B5C859090a6c34d164135398226 --header='Content-Type: application/json' --body-data='{"funds": "1337"}'
echo '{ "funds": "1337" }' | http PUT http://localhost:5001/api/v1/connections/0x2a65Aca4D5fC5B5C859090a6c34d164135398226 Content-Type:application/json
requests.put('http://localhost:5001/api/v1/connections/0x2a65Aca4D5fC5B5C859090a6c34d164135398226', headers={ 'Content-Type': 'application/json', }, json={ 'funds': '1337', })
Status Codes: - 204 No Content – For a successful connection creation.
- 402 Payment Required – If any of the channel deposits fail due to insufficient ETH balance to pay for the gas of the on-chain transactions.
- 404 Not Found – The given token address is not a valid eip55-encoded Ethereum address
- 408 Request Timeout – If a timeout happened during any of the transactions.
- 409 Conflict – If any of the provided input to the call is invalid.
- 500 Internal Server Error – Internal Raiden node error.
- 503 Service Unavailable – The API is currently unavailable, e. g. because the Raiden node is still in the initial sync or shutting down.
Request JSON Object: - funds (int) – Amount of funding you want to put into the network.
- initial_channel_target (int) – Number of channels to open proactively.
- joinable_funds_target (float) – Fraction of funds that will be used to join channels opened by other participants.
Note
Currently, the API calls are blocking. This means that in the case of long running calls like
join
, if other calls tojoin
are made concurrently, they will block too and wait for the first call to finish. If an API call is currently being processed by Raiden, all pending calls will be queued and processed with their passed API call argument.
-
DELETE
/api/
(version)/connections/
(token_address)¶ Leave a token network. The request will only return once all blockchain calls for closing/settling a channel have completed.
Example Request:
DELETE /api/v1/connections/0x2a65Aca4D5fC5B5C859090a6c34d164135398226 HTTP/1.1 Host: localhost:5001 Content-Type: application/json
curl -i -X DELETE http://localhost:5001/api/v1/connections/0x2a65Aca4D5fC5B5C859090a6c34d164135398226 -H 'Content-Type: application/json'
wget -S -O- --method=DELETE http://localhost:5001/api/v1/connections/0x2a65Aca4D5fC5B5C859090a6c34d164135398226 --header='Content-Type: application/json'
http DELETE http://localhost:5001/api/v1/connections/0x2a65Aca4D5fC5B5C859090a6c34d164135398226 Content-Type:application/json
requests.delete('http://localhost:5001/api/v1/connections/0x2a65Aca4D5fC5B5C859090a6c34d164135398226', headers={ 'Content-Type': 'application/json', })
Example Response:
HTTP/1.1 200 OK Content-Type: application/json [ "0x41BCBC2fD72a731bcc136Cf6F7442e9C19e9f313", "0x5A5f458F6c1a034930E45dC9a64B99d7def06D7E", "0x8942c06FaA74cEBFf7d55B79F9989AdfC85C6b85" ]
The response is a list with the addresses of all closed channels.
Status Codes: - 200 OK – For successfully leaving a token network
- 404 Not Found – The given token address is not a valid eip55-encoded Ethereum address
- 500 Internal Server Error – Internal Raiden node error
- 503 Service Unavailable – The API is currently unavailable, e. g. because the Raiden node is still in the initial sync or shutting down.
Note
Currently, the API calls are blocking. This means that in the case of long running calls like
leave
, if an API call is currently being processed by Raiden, all pending calls will be queued and processed with their passed API call argument.
Payments¶
-
POST
/api/
(version)/payments/
(token_address)/
(target_address)¶ Initiate a payment.
The request will only return once the payment either succeeded or failed. A payment can fail due to the expiration of a lock, the target being offline, channels on the path to the target not having enough
settle_timeout
andreveal_timeout
in order to allow the payment to be propagated safely, not enough funds etc.Example Request:
POST /api/v1/payments/0x2a65Aca4D5fC5B5C859090a6c34d164135398226/0x61C808D82A3Ac53231750daDc13c777b59310bD9 HTTP/1.1 Host: localhost:5001 Content-Type: application/json { "amount": "200", "identifier": "42" }
curl -i -X POST http://localhost:5001/api/v1/payments/0x2a65Aca4D5fC5B5C859090a6c34d164135398226/0x61C808D82A3Ac53231750daDc13c777b59310bD9 -H 'Content-Type: application/json' --data-raw '{"amount": "200", "identifier": "42"}'
wget -S -O- http://localhost:5001/api/v1/payments/0x2a65Aca4D5fC5B5C859090a6c34d164135398226/0x61C808D82A3Ac53231750daDc13c777b59310bD9 --header='Content-Type: application/json' --post-data='{"amount": "200", "identifier": "42"}'
echo '{ "amount": "200", "identifier": "42" }' | http POST http://localhost:5001/api/v1/payments/0x2a65Aca4D5fC5B5C859090a6c34d164135398226/0x61C808D82A3Ac53231750daDc13c777b59310bD9 Content-Type:application/json
requests.post('http://localhost:5001/api/v1/payments/0x2a65Aca4D5fC5B5C859090a6c34d164135398226/0x61C808D82A3Ac53231750daDc13c777b59310bD9', headers={ 'Content-Type': 'application/json', }, json={ 'amount': '200', 'identifier': '42', })
Request JSON Object: - amount (int) – Amount to be sent to the target
- identifier (int) – Identifier of the payment (optional)
- lock_timeout (int) – lock timeout, in blocks, to be used with the payment. Default is 2 * channel’s reveal_timeout, Value must be greater than channel’s reveal_timeout (optional)
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "initiator_address": "0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8", "target_address": "0x61C808D82A3Ac53231750daDc13c777b59310bD9", "token_address": "0x2a65Aca4D5fC5B5C859090a6c34d164135398226", "amount": "200", "identifier": "42", "secret": "0x4c7b2eae8bbed5bde529fda2dcb092fddee3cc89c89c8d4c747ec4e570b05f66", "secret_hash": "0x1f67db95d7bf4c8269f69d55831e627005a23bfc199744b7ab9abcb1c12353bd" }
Status Codes: - 200 OK – Successful payment
- 400 Bad Request – If the provided json is in some way malformed
- 402 Payment Required – If the payment can’t start due to insufficient balance
- 404 Not Found – The given token and / or target addresses are not valid eip55-encoded Ethereum addresses
- 408 Request Timeout – If a timeout happened during the payment
- 409 Conflict – If the address or the amount is invalid or if there is no path to the target, or if the identifier is already in use for a different payment.
- 500 Internal Server Error – Internal Raiden node error
- 503 Service Unavailable – The API is currently unavailable, e. g. because the Raiden node is still in the initial sync or shutting down.
Note
This endpoint will return as soon the initiator has unlocked the payment(i.e Unlock message is sent). However, this does not necessarily mean that querying the balance from the target node, immediately after the initiator returns, will return the new balance amount due to the fact that the target might not have received or processed the unlock.
To use Raiden for an atomic swap (see Token Swaps), the endpoint could be called to initiate a payment while providing values for
secret
andsecret_hash
.Example Request:
POST /api/v1/payments/0x2a65Aca4D5fC5B5C859090a6c34d164135398226/0x61C808D82A3Ac53231750daDc13c777b59310bD9 HTTP/1.1 Host: localhost:5001 Content-Type: application/json { "amount": "200", "identifier": "42", "secret": "0x4c7b2eae8bbed5bde529fda2dcb092fddee3cc89c89c8d4c747ec4e570b05f66", "secret_hash": "0x1f67db95d7bf4c8269f69d55831e627005a23bfc199744b7ab9abcb1c12353bd" }
curl -i -X POST http://localhost:5001/api/v1/payments/0x2a65Aca4D5fC5B5C859090a6c34d164135398226/0x61C808D82A3Ac53231750daDc13c777b59310bD9 -H 'Content-Type: application/json' --data-raw '{"amount": "200", "identifier": "42", "secret": "0x4c7b2eae8bbed5bde529fda2dcb092fddee3cc89c89c8d4c747ec4e570b05f66", "secret_hash": "0x1f67db95d7bf4c8269f69d55831e627005a23bfc199744b7ab9abcb1c12353bd"}'
wget -S -O- http://localhost:5001/api/v1/payments/0x2a65Aca4D5fC5B5C859090a6c34d164135398226/0x61C808D82A3Ac53231750daDc13c777b59310bD9 --header='Content-Type: application/json' --post-data='{"amount": "200", "identifier": "42", "secret": "0x4c7b2eae8bbed5bde529fda2dcb092fddee3cc89c89c8d4c747ec4e570b05f66", "secret_hash": "0x1f67db95d7bf4c8269f69d55831e627005a23bfc199744b7ab9abcb1c12353bd"}'
echo '{ "amount": "200", "identifier": "42", "secret": "0x4c7b2eae8bbed5bde529fda2dcb092fddee3cc89c89c8d4c747ec4e570b05f66", "secret_hash": "0x1f67db95d7bf4c8269f69d55831e627005a23bfc199744b7ab9abcb1c12353bd" }' | http POST http://localhost:5001/api/v1/payments/0x2a65Aca4D5fC5B5C859090a6c34d164135398226/0x61C808D82A3Ac53231750daDc13c777b59310bD9 Content-Type:application/json
requests.post('http://localhost:5001/api/v1/payments/0x2a65Aca4D5fC5B5C859090a6c34d164135398226/0x61C808D82A3Ac53231750daDc13c777b59310bD9', headers={ 'Content-Type': 'application/json', }, json={ 'amount': '200', 'identifier': '42', 'secret': '0x4c7b2eae8bbed5bde529fda2dcb092fddee3cc89c89c8d4c747ec4e570b05f66', 'secret_hash': '0x1f67db95d7bf4c8269f69d55831e627005a23bfc199744b7ab9abcb1c12353bd', })
Request JSON Object: - amount (int) – Amount to be sent to the target
- identifier (int) – Identifier of the payment (optional)
- secret (string) – The secret to be used for the payment
- secret_hash (string) – The secret hash (should be equal to SHA256 of the secret)
Querying Events¶
Events are kept by the node. A normal user should only care about the events exposed for payments. Those events show if a payment failed or if it was successful.
For raiden_events
you can provide a limit
and an offset
number which would define the limit of results to return and the offset from which to return results respectively.
raiden_events
contain a timestamp field, log_time
, indicating when they were written to the write-ahead log.
The format of log_time
is ISO8601 with milliseconds.
-
GET
/api/
(version)/payments/
(token_address)/
(target_address)¶ - Query the payment history. This includes successful (EventPaymentSentSuccess) and failed (EventPaymentSentFailed) sent payments as well as received payments (EventPaymentReceivedSuccess).
token_address
andtarget_address
are optional and will filter the list of events accordingly.Example Request:
GET /api/v1/payments/0x0f114A1E9Db192502E7856309cc899952b3db1ED/0x82641569b2062B545431cF6D7F0A418582865ba7 HTTP/1.1 Host: localhost:5001
curl -i http://localhost:5001/api/v1/payments/0x0f114A1E9Db192502E7856309cc899952b3db1ED/0x82641569b2062B545431cF6D7F0A418582865ba7
wget -S -O- http://localhost:5001/api/v1/payments/0x0f114A1E9Db192502E7856309cc899952b3db1ED/0x82641569b2062B545431cF6D7F0A418582865ba7
http http://localhost:5001/api/v1/payments/0x0f114A1E9Db192502E7856309cc899952b3db1ED/0x82641569b2062B545431cF6D7F0A418582865ba7
requests.get('http://localhost:5001/api/v1/payments/0x0f114A1E9Db192502E7856309cc899952b3db1ED/0x82641569b2062B545431cF6D7F0A418582865ba7')
Example Response:
HTTP/1.1 200 OK Content-Type: application/json [ { "event": "EventPaymentReceivedSuccess", "amount": "5", "initiator": "0x82641569b2062B545431cF6D7F0A418582865ba7", "identifier": "1", "log_time": "2018-10-30T07:03:52.193", "token_address" : "0x5a2d2b9b015b46b8eaff7bffdc5db0051db7439b" }, { "event": "EventPaymentSentSuccess", "amount": "35", "target": "0x82641569b2062B545431cF6D7F0A418582865ba7", "identifier": "2", "log_time": "2018-10-30T07:04:22.293", "token_address" : "0x5a2d2b9b015b46b8eaff7bffdc5db0051db7439b" }, { "event": "EventPaymentSentSuccess", "amount": "20", "target": "0x82641569b2062B545431cF6D7F0A418582865ba7", "identifier": "3", "log_time": "2018-10-30T07:10:13.122", "token_address" : "0x5a2d2b9b015b46b8eaff7bffdc5db0051db7439b" } ]
Status Codes: - 200 OK – For successful query
- 404 Not Found – The given token and / or partner addresses are not valid eip55-encoded Ethereum addresses
- 409 Conflict – If the given block number or token_address arguments are invalid
- 500 Internal Server Error – Internal Raiden node error
- 503 Service Unavailable – The API is currently unavailable, e. g. because the Raiden node is still in the initial sync or shutting down.
Querying node state¶
-
GET
/api/
(version)/status
¶ Query the node status. Possible answers are:
"ready"
: The node is listening on its API endpoints"syncing"
: The node is still in the initial sync. Number of blocks to sync will also be given."unavailable"
: The node is unavailable for some other reason
Example Request:
GET /api/v1/status HTTP/1.1 Host: localhost:5001
curl -i http://localhost:5001/api/v1/status
wget -S -O- http://localhost:5001/api/v1/status
http http://localhost:5001/api/v1/status
requests.get('http://localhost:5001/api/v1/status')
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "status": "syncing", "blocks_to_sync": "130452" }
Status Codes: - 200 OK – Successful query
- 500 Internal Server Error – Internal Raiden error
API endpoints for testing¶
-
POST
/api/
(version)/_testing/tokens/
(token_address)/mint
¶ Mint tokens. This requires the token at
token_address
to implement a minting method with one of the common interfaces:mint(address,uint256)
mintFor(uint256,address)
increaseSupply(uint256,address)
Depending on the token, it may also be necessary to have minter privilege.
Example Request:
POST /api/v1/_testing/tokens/0x782CfA3c74332B52c6f6F1758913815128828209/mint HTTP/1.1 Host: localhost:5001 Content-Type: application/json { "to": "0x2c4b0Bdac486d492E3cD701F4cA87e480AE4C685", "value": "1000" }
curl -i -X POST http://localhost:5001/api/v1/_testing/tokens/0x782CfA3c74332B52c6f6F1758913815128828209/mint -H 'Content-Type: application/json' --data-raw '{"to": "0x2c4b0Bdac486d492E3cD701F4cA87e480AE4C685", "value": "1000"}'
wget -S -O- http://localhost:5001/api/v1/_testing/tokens/0x782CfA3c74332B52c6f6F1758913815128828209/mint --header='Content-Type: application/json' --post-data='{"to": "0x2c4b0Bdac486d492E3cD701F4cA87e480AE4C685", "value": "1000"}'
echo '{ "to": "0x2c4b0Bdac486d492E3cD701F4cA87e480AE4C685", "value": "1000" }' | http POST http://localhost:5001/api/v1/_testing/tokens/0x782CfA3c74332B52c6f6F1758913815128828209/mint Content-Type:application/json
requests.post('http://localhost:5001/api/v1/_testing/tokens/0x782CfA3c74332B52c6f6F1758913815128828209/mint', headers={ 'Content-Type': 'application/json', }, json={ 'to': '0x2c4b0Bdac486d492E3cD701F4cA87e480AE4C685', 'value': '1000', })
Request JSON Object: - to (address) – The address to assign the minted tokens to.
- value (int) – The amount of tokens to be minted.
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "transaction_hash": "0x90896386c5b218d772c05586bde5c37c9dc90db5de660bba5bd897705c976edb" }
Status Codes: - 200 OK – The transaction was successful.
- 400 Bad Request – Something went wrong.
- 503 Service Unavailable – The API is currently unavailable, e. g. because the Raiden node is still in the initial sync or shutting down.
Response JSON Object: - transaction_hash (string) – The hash of the minting transaction.