Raiden’s API Documentation

Introduction

The Raiden API is organized around REST and has resource-oriented URL endpoints that accept and return JSON-encoded responses. The Raiden API uses standard HTTP response codes and verbs. The Raiden RESTful API endpoints correspond to the interactions allowed by a Raiden node. The URL path always contains the API version as an integer. All endpoints 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",
   "network_state": "unknown",
   "token_network_address": "0x2a65Aca4D5fC5B5C859090a6c34d164135398226",
   "partner_address": "0x61C808D82A3Ac53231750daDc13c777b59310bD9",
   "token_address": "0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8",
   "balance": "25000000",
   "total_deposit": "35000000",
   "total_withdraw": "15000000",
   "state": "opened",
   "settle_timeout": "500",
   "reveal_timeout": "50"
}

A channel object consists of a

  • channel_identifier: string containing the identifier of the channel.

  • partner_address: string containing the EIP55-encoded address of the partner with whom we have opened a channel.

  • token_address: string containing the EIP55-encoded address of the token we are trading in the channel.

  • token_network_address: string containing the EIP55-encoded address of the token network the channel is part of.

  • balance: string of the amount of the token_address token we have available for payments.

  • network_state: string representing the online/offline status of the partner node for the channel. Possibly values are:

    • "unknown": Network status is not known (currently this is the only value returned)

    • "reachable": The node is known to be online and ready to send and receive messages

    • "unreachable": The node is known to be offline and not ready to send and receive messages

  • total_deposit: string of the amount of the token_address token we have deposited into the contract for this channel.

  • total_withdraw: string of the amount of the token_address token we have withdrawn from the channel on-chain.

  • state: current state of the channel represented by a string. Possible values 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 that close() is called until the channel can be settled with a call to settle().

  • reveal_timeout: The maximum number of blocks allowed between the setting of a hashlock and the revealing of the related secret.

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.

Resources

All objects that are sent and received from the Raiden API are JSON encoded. The following outlines each of the Raiden API endpoints.

Address

GET /api/(version)/address

Queries the Ethereum address you choose when starting Raiden. A Raiden node is up and running correctly if the response returns that same address.

Example Request:

http

GET /api/v1/address HTTP/1.1
Host: localhost:5001

curl

curl -i -X GET http://localhost:5001/api/v1/address

wget

wget -S -O- http://localhost:5001/api/v1/address

httpie

http http://localhost:5001/api/v1/address

python-requests

requests.get('http://localhost:5001/api/v1/address')

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "our_address": "0x2a65Aca4D5fC5B5C859090a6c34d164135398226"
}

Version

GET /api/(version)/version

You can query the version endpoint to see which version of Raiden you’re currently running.

Example Request:

http

GET /api/v1/version HTTP/1.1
Host: localhost:5001

curl

curl -i -X GET http://localhost:5001/api/v1/version

wget

wget -S -O- http://localhost:5001/api/v1/version

httpie

http http://localhost:5001/api/v1/version

python-requests

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"
}

Status

GET /api/(version)/status

Query the node status. The responses status attribute can be one of:

  • "ready": The node is listening on its API endpoints.

  • "syncing": The node is still in the initial sync. Number of remaining blocks to sync will also be given.

  • "unavailable": The node is unavailable for some other reason.

Example Request:

http

GET /api/v1/status HTTP/1.1
Host: localhost:5001

curl

curl -i -X GET http://localhost:5001/api/v1/status

wget

wget -S -O- http://localhost:5001/api/v1/status

httpie

http http://localhost:5001/api/v1/status

python-requests

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

Settings

GET /api/(version)/settings

Queries the settings of your Raiden node. At the moment only the URL of the pathfinding service is returned. The endpoint will provide more settings in the future.

Example Request:

http

GET /api/v1/settings HTTP/1.1
Host: localhost:5001

curl

curl -i -X GET http://localhost:5001/api/v1/settings

wget

wget -S -O- http://localhost:5001/api/v1/settings

httpie

http http://localhost:5001/api/v1/settings

python-requests

requests.get('http://localhost:5001/api/v1/settings')

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "pathfinding_service_address": "https://pfs.transport04.raiden.network"
}

Contracts

GET /api/(version)/contracts

By querying the contracts endpoint you can check which on-chain smart contracts are used. Returns the addresses of the smart contracts in use.

Example Request:

http

GET /api/v1/contracts HTTP/1.1
Host: localhost:5001

curl

curl -i -X GET http://localhost:5001/api/v1/contracts

wget

wget -S -O- http://localhost:5001/api/v1/contracts

httpie

http http://localhost:5001/api/v1/contracts

python-requests

requests.get('http://localhost:5001/api/v1/contracts')

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
   "contracts_version": "0.37.1",
   "monitoring_service_address": "0x20e8e5181000e60799A523a2023d630868f378Fd",
   "one_to_n_address": "0xA514Da2418576CeC4070C82996f30532dDa99706",
   "secret_registry_address": "0x9fC80eb1939d8147aB90BAC01AD585f3a71BeE7e",
   "service_registry_address": "0x3bc9C8d34f5714327095358668fD436D7c457C6C",
   "token_network_registry_address": "0x5a5CF4A63022F61F1506D1A2398490c2e8dfbb98",
   "user_deposit_address": "0x0794F09913AA8C77C8c5bdd1Ec4Bb51759Ee0cC5"
}

Tokens

The tokens endpoints are used for registering new tokens and querying information about already registered tokens.

Note

For the Coruscant release two tokens are registered, DAI and WETH.

Information about Tokens

GET /api/(version)/tokens

Returns a list of addresses of all registered tokens.

Example Request:

http

GET /api/v1/tokens HTTP/1.1
Host: localhost:5001

curl

curl -i -X GET http://localhost:5001/api/v1/tokens

wget

wget -S -O- http://localhost:5001/api/v1/tokens

httpie

http http://localhost:5001/api/v1/tokens

python-requests

requests.get('http://localhost:5001/api/v1/tokens')

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

[
      "0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8",
      "0x61bB630D3B2e8eda0FC1d50F9f958eC02e3969F6"
]
Status Codes
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:

http

GET /api/v1/tokens/0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8 HTTP/1.1
Host: localhost:5001

curl

curl -i -X GET http://localhost:5001/api/v1/tokens/0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8

wget

wget -S -O- http://localhost:5001/api/v1/tokens/0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8

httpie

http http://localhost:5001/api/v1/tokens/0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8

python-requests

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 partner nodes with unsettled channels for a specific token.

Example Request:

http

GET /api/v1/tokens/0x61bB630D3B2e8eda0FC1d50F9f958eC02e3969F6/partners HTTP/1.1
Host: localhost:5001

curl

curl -i -X GET http://localhost:5001/api/v1/tokens/0x61bB630D3B2e8eda0FC1d50F9f958eC02e3969F6/partners

wget

wget -S -O- http://localhost:5001/api/v1/tokens/0x61bB630D3B2e8eda0FC1d50F9f958eC02e3969F6/partners

httpie

http http://localhost:5001/api/v1/tokens/0x61bB630D3B2e8eda0FC1d50F9f958eC02e3969F6/partners

python-requests

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

Register a Token

Warning

For the Coruscant release it is not be possible to register more than two tokens, due to security reasons in order to minimise possible loss of funds in the case of bugs. The two token that are registered are DAI and WETH.

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:

http

PUT /api/v1/tokens/0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8 HTTP/1.1
Host: localhost:5001

curl

curl -i -X PUT http://localhost:5001/api/v1/tokens/0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8

wget

wget -S -O- --method=PUT http://localhost:5001/api/v1/tokens/0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8

httpie

http PUT http://localhost:5001/api/v1/tokens/0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8

python-requests

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.

Channels

The channels endpoints allow you to open channels with other Raiden nodes as well as closing channels, querying them for information and making deposits or withdrawals.

Warning

The maximum deposits per token and node for the Coruscant release are:

DAI: The deposit limit is 5000 worth of DAI per channel participant making the maximum amount of DAI 10000 per channel.

WETH: The deposit limit is around 1.1905 worth of WETH per channel participant making the maximum amount of around WETH 2.3810 per channel.

Information about Channels

GET /api/(version)/channels

Get a list of all unsettled channels.

Example Request:

http

GET /api/v1/channels HTTP/1.1
Host: localhost:5001

curl

curl -i -X GET http://localhost:5001/api/v1/channels

wget

wget -S -O- http://localhost:5001/api/v1/channels

httpie

http http://localhost:5001/api/v1/channels

python-requests

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",
        "network_state": "unknown",
        "partner_address": "0x61C808D82A3Ac53231750daDc13c777b59310bD9",
        "token_address": "0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8",
        "balance": "25000000",
        "total_deposit": "35000000",
        "total_withdraw": "5000000",
        "state": "opened",
        "settle_timeout": "500",
        "reveal_timeout": "50"
    }
]
Status Codes
GET /api/(version)/channels/(token_address)

Get a list of all unsettled channels for the given token address.

Example Request:

http

GET /api/v1/channels/0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8 HTTP/1.1
Host: localhost:5001

curl

curl -i -X GET http://localhost:5001/api/v1/channels/0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8

wget

wget -S -O- http://localhost:5001/api/v1/channels/0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8

httpie

http http://localhost:5001/api/v1/channels/0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8

python-requests

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",
        "network_state": "unknown",
        "partner_address": "0x61C808D82A3Ac53231750daDc13c777b59310bD9",
        "token_address": "0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8",
        "balance": "25000000",
        "total_deposit": "35000000",
        "total_withdraw": "5000000",
        "state": "opened",
        "settle_timeout": "500",
        "reveal_timeout": "50"
    }
]
Status Codes
GET /api/(version)/channels/(token_address)/(partner_address)

Query information about one of your channels. The channel is specified by the address of a token and the address of the partner node which the channel is opened with.

Example Request:

http

GET /api/v1/channels/0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8/0x61C808D82A3Ac53231750daDc13c777b59310bD9 HTTP/1.1
Host: localhost:5001

curl

curl -i -X GET http://localhost:5001/api/v1/channels/0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8/0x61C808D82A3Ac53231750daDc13c777b59310bD9

wget

wget -S -O- http://localhost:5001/api/v1/channels/0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8/0x61C808D82A3Ac53231750daDc13c777b59310bD9

httpie

http http://localhost:5001/api/v1/channels/0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8/0x61C808D82A3Ac53231750daDc13c777b59310bD9

python-requests

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",
    "network_state": "unknown",
    "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.

Create a Channel

PUT /api/(version)/channels

The request will open a channel and return the newly created channel object.

Example Request:

http

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

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

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"}'

httpie

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

python-requests

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) – Address of the partner node with whom we’re opening the channel.

  • token_address (address) – Address of the token to be used in the channel.

  • total_deposit (string) – Amount of tokens to be deposited into the channel.

  • settle_timeout (string) – The number of blocks after which a channel can be settled.

  • reveal_timeout (string) – The number of blocks that are allowed between setting a hashlock and the revealing of the related secret.

Example Response:

HTTP/1.1 201 CREATED
Content-Type: application/json

{
    "token_network_address": "0xE5637F0103794C7e05469A9964E4563089a5E6f2",
    "channel_identifier": "20",
    "network_state": "unknown",
    "partner_address": "0x61C808D82A3Ac53231750daDc13c777b59310bD9",
    "token_address": "0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8",
    "balance": "25000000",
    "total_deposit": "35000000",
    "total_withdraw": "0",
    "state": "opened",
    "settle_timeout": "500",
    "reveal_timeout": "50"
}
Status Codes

Modify a Channel

PATCH /api/(version)/channels/(token_address)/(partner_address)

This request is used to close a channel, to increase the deposit in it, to withdraw tokens from it or to update its reveal timeout. The channel is specified by the address of a token and the address of the partner node which the channel is opened with.

Close Channel Example Request:

http

PATCH /api/v1/channels/0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8/0x61C808D82A3Ac53231750daDc13c777b59310bD9 HTTP/1.1
Host: localhost:5001
Content-Type: application/json

{
    "state": "closed"
}

curl

curl -i -X PATCH http://localhost:5001/api/v1/channels/0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8/0x61C808D82A3Ac53231750daDc13c777b59310bD9 -H "Content-Type: application/json" --data-raw '{"state": "closed"}'

wget

wget -S -O- --method=PATCH http://localhost:5001/api/v1/channels/0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8/0x61C808D82A3Ac53231750daDc13c777b59310bD9 --header="Content-Type: application/json" --body-data='{"state": "closed"}'

httpie

echo '{
  "state": "closed"
}' | http PATCH http://localhost:5001/api/v1/channels/0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8/0x61C808D82A3Ac53231750daDc13c777b59310bD9 Content-Type:application/json

python-requests

requests.patch('http://localhost:5001/api/v1/channels/0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8/0x61C808D82A3Ac53231750daDc13c777b59310bD9', headers={
    'Content-Type': 'application/json',
}, json={
    'state': 'closed',
})
Request JSON Object

  • state (string) – Can only be set to "closed"

Increase Deposit Example Request:

http

PATCH /api/v1/channels/0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8/0x61C808D82A3Ac53231750daDc13c777b59310bD9 HTTP/1.1
Host: localhost:5001
Content-Type: application/json

{
    "total_deposit": "100"
}

curl

curl -i -X PATCH http://localhost:5001/api/v1/channels/0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8/0x61C808D82A3Ac53231750daDc13c777b59310bD9 -H "Content-Type: application/json" --data-raw '{"total_deposit": "100"}'

wget

wget -S -O- --method=PATCH http://localhost:5001/api/v1/channels/0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8/0x61C808D82A3Ac53231750daDc13c777b59310bD9 --header="Content-Type: application/json" --body-data='{"total_deposit": "100"}'

httpie

echo '{
  "total_deposit": "100"
}' | http PATCH http://localhost:5001/api/v1/channels/0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8/0x61C808D82A3Ac53231750daDc13c777b59310bD9 Content-Type:application/json

python-requests

requests.patch('http://localhost:5001/api/v1/channels/0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8/0x61C808D82A3Ac53231750daDc13c777b59310bD9', headers={
    'Content-Type': 'application/json',
}, json={
    'total_deposit': '100',
})
Request JSON Object

  • total_deposit (string) – The increased total deposit

Withdraw Tokens Example Request:

http

PATCH /api/v1/channels/0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8/0x61C808D82A3Ac53231750daDc13c777b59310bD9 HTTP/1.1
Host: localhost:5001
Content-Type: application/json

{
    "total_withdraw": "100"
}

curl

curl -i -X PATCH http://localhost:5001/api/v1/channels/0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8/0x61C808D82A3Ac53231750daDc13c777b59310bD9 -H "Content-Type: application/json" --data-raw '{"total_withdraw": "100"}'

wget

wget -S -O- --method=PATCH http://localhost:5001/api/v1/channels/0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8/0x61C808D82A3Ac53231750daDc13c777b59310bD9 --header="Content-Type: application/json" --body-data='{"total_withdraw": "100"}'

httpie

echo '{
  "total_withdraw": "100"
}' | http PATCH http://localhost:5001/api/v1/channels/0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8/0x61C808D82A3Ac53231750daDc13c777b59310bD9 Content-Type:application/json

python-requests

requests.patch('http://localhost:5001/api/v1/channels/0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8/0x61C808D82A3Ac53231750daDc13c777b59310bD9', headers={
    'Content-Type': 'application/json',
}, json={
    'total_withdraw': '100',
})
Request JSON Object

  • total_withdraw (string) – The increased total withdraw

Update Reveal Timeout Example Request:

http

PATCH /api/v1/channels/0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8/0x61C808D82A3Ac53231750daDc13c777b59310bD9 HTTP/1.1
Host: localhost:5001
Content-Type: application/json

{
    "reveal_timeout": "50"
}

curl

curl -i -X PATCH http://localhost:5001/api/v1/channels/0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8/0x61C808D82A3Ac53231750daDc13c777b59310bD9 -H "Content-Type: application/json" --data-raw '{"reveal_timeout": "50"}'

wget

wget -S -O- --method=PATCH http://localhost:5001/api/v1/channels/0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8/0x61C808D82A3Ac53231750daDc13c777b59310bD9 --header="Content-Type: application/json" --body-data='{"reveal_timeout": "50"}'

httpie

echo '{
  "reveal_timeout": "50"
}' | http PATCH http://localhost:5001/api/v1/channels/0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8/0x61C808D82A3Ac53231750daDc13c777b59310bD9 Content-Type:application/json

python-requests

requests.patch('http://localhost:5001/api/v1/channels/0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8/0x61C808D82A3Ac53231750daDc13c777b59310bD9', headers={
    'Content-Type': 'application/json',
}, json={
    'reveal_timeout': '50',
})
Request JSON Object

  • reveal_timeout (string) – The new reveal timeout value

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "token_network_address": "0xE5637F0103794C7e05469A9964E4563089a5E6f2",
    "channel_identifier": "20",
    "network_state": "unknown",
    "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 or total_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

  • 409 Conflict –

    • Provided channel does not exist or

    • state, total_deposit and total_withdraw have been attempted to update in the same request or

    • attempt to deposit token amount lower than on-chain balance of the channel or

    • 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.

Payments

The payment endpoint is used for transferring tokens to another node. You can send the desired amount of tokens by providing the address of the token and the address of the receiving node. Besides you can query all payments that you sent or received.

Query the Payment History

GET /api/(version)/payments/(token_address)/(partner_address)

When querying the payment history the response will include:

  • “EventPaymentSentSuccess” for successful payments

  • “EventPaymentSentFailed” for failed payments

  • “EventPaymentReceivedSuccess” for received payments

token_address and partner_address are optional and will filter the list of events accordingly.

Example Request:

http

GET /api/v1/payments/0x0f114A1E9Db192502E7856309cc899952b3db1ED/0x82641569b2062B545431cF6D7F0A418582865ba7 HTTP/1.1
Host: localhost:5001

curl

curl -i -X GET http://localhost:5001/api/v1/payments/0x0f114A1E9Db192502E7856309cc899952b3db1ED/0x82641569b2062B545431cF6D7F0A418582865ba7

wget

wget -S -O- http://localhost:5001/api/v1/payments/0x0f114A1E9Db192502E7856309cc899952b3db1ED/0x82641569b2062B545431cF6D7F0A418582865ba7

httpie

http http://localhost:5001/api/v1/payments/0x0f114A1E9Db192502E7856309cc899952b3db1ED/0x82641569b2062B545431cF6D7F0A418582865ba7

python-requests

requests.get('http://localhost:5001/api/v1/payments/0x0f114A1E9Db192502E7856309cc899952b3db1ED/0x82641569b2062B545431cF6D7F0A418582865ba7')
Query Parameters

  • limit (int) – Limits the payment history result to the specified amount

  • offset (int) – Offsets the payment history result by the specified amount

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

[
   {
      "event": "EventPaymentSentSuccess",
      "amount": "20",
      "target": "0x82641569b2062B545431cF6D7F0A418582865ba7",
      "identifier": "3",
      "log_time": "2018-10-30T07:10:13.122",
      "token_address": "0x62083c80353Df771426D209eF578619EE68D5C7A"
   },
   {
      "target": "0x82641569b2062B545431cF6D7F0A418582865ba7",
      "event": "EventPaymentSentFailed",
      "log_time": "2018-10-30T07:04:22.293",
      "reason": "there is no route available",
      "token_address": "0x62083c80353Df771426D209eF578619EE68D5C7A"
   },
   {
      "event": "EventPaymentReceivedSuccess",
      "amount": "5",
      "initiator": "0x82641569b2062B545431cF6D7F0A418582865ba7",
      "identifier": "1",
      "log_time": "2018-10-30T07:03:52.193",
      "token_address": "0x62083c80353Df771426D209eF578619EE68D5C7A"
   }
]
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.

Response JSON Array of Objects

  • event (string) – One of “EventPaymentSentSuccess”, “EventPaymentSentFailed” and “EventPaymentReceivedSuccess”.

  • amount (string) – Token amount of the payment.

  • target (string) – Address of the node which received the payment.

  • initiator (string) – Address of the node which initiated the payment.

  • identifier (string) – Identifier of the payment.

  • log_time (string) – Time when the payment event was written to the write-ahead log. The format of log_time is ISO8601 with milliseconds.

  • token_address (string) – Address of token that was transferred.

  • reason (string) – Gives an explanation why a payment failed.

Initiate a Payment

POST /api/(version)/payments/(token_address)/(target_address)

The request will only return once the payment either succeeds or fails.

Note

A payment can fail due to:

  • The secret for opening the hashlock not being revealed in time and the lock expires

  • The target node being offline

  • The channels leading to the target node not having enough settle_timeout and reveal_timeout

  • The funds not being enough

Example Request:

http

POST /api/v1/payments/0x2a65Aca4D5fC5B5C859090a6c34d164135398226/0x61C808D82A3Ac53231750daDc13c777b59310bD9 HTTP/1.1
Host: localhost:5001
Content-Type: application/json

{
    "amount": "200",
    "identifier": "42",
    "paths": [
        {
            "route": ["0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8", "0x61C808D82A3Ac53231750daDc13c777b59310bD9"],
            "address_metadata": {
                "0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8": {
                    "user_id": "@0xea674fdde714fd979de3edf0f56aa9716b898ec8:localhost:8502",
                    "capabilities": "mxc://raiden.network/cap?Receive=1&Mediate=1&Delivery=1&webRTC=1&toDevice=1&immutableMetadata=1",
                    "displayname": "0xdf714485248a7d83f29e059622004acbb8a6b8a09c1506c304c2748e4e941cf769e864764ef028b31da525280d35d5ab87ee196dc738bc0f8de81ca3355a0c111b"
                },
                "0x61C808D82A3Ac53231750daDc13c777b59310bD9": {
                    "user_id": "@0x61c808d82a3ac53231750dadc13c777b59310bd9:localhost:8502",
                    "capabilities": "mxc://raiden.network/cap?Receive=1&Mediate=1&Delivery=1&webRTC=1&toDevice=1&immutableMetadata=1",
                    "displayname": "0x56682a1fecb4df0ce8e0e3aa9a0eaae4a6bc1a6265284f3fffbb1423e018122838353e6930c6000892e94f305b97c726a8e74c27dcce98adda9340f93555f5bb1c"
                }
            }
        }
    ]
}

curl

curl -i -X POST http://localhost:5001/api/v1/payments/0x2a65Aca4D5fC5B5C859090a6c34d164135398226/0x61C808D82A3Ac53231750daDc13c777b59310bD9 -H "Content-Type: application/json" --data-raw '{"amount": "200", "identifier": "42", "paths": [{"route": ["0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8", "0x61C808D82A3Ac53231750daDc13c777b59310bD9"], "address_metadata": {"0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8": {"user_id": "@0xea674fdde714fd979de3edf0f56aa9716b898ec8:localhost:8502", "capabilities": "mxc://raiden.network/cap?Receive=1&Mediate=1&Delivery=1&webRTC=1&toDevice=1&immutableMetadata=1", "displayname": "0xdf714485248a7d83f29e059622004acbb8a6b8a09c1506c304c2748e4e941cf769e864764ef028b31da525280d35d5ab87ee196dc738bc0f8de81ca3355a0c111b"}, "0x61C808D82A3Ac53231750daDc13c777b59310bD9": {"user_id": "@0x61c808d82a3ac53231750dadc13c777b59310bd9:localhost:8502", "capabilities": "mxc://raiden.network/cap?Receive=1&Mediate=1&Delivery=1&webRTC=1&toDevice=1&immutableMetadata=1", "displayname": "0x56682a1fecb4df0ce8e0e3aa9a0eaae4a6bc1a6265284f3fffbb1423e018122838353e6930c6000892e94f305b97c726a8e74c27dcce98adda9340f93555f5bb1c"}}}]}'

wget

wget -S -O- http://localhost:5001/api/v1/payments/0x2a65Aca4D5fC5B5C859090a6c34d164135398226/0x61C808D82A3Ac53231750daDc13c777b59310bD9 --header="Content-Type: application/json" --post-data='{"amount": "200", "identifier": "42", "paths": [{"route": ["0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8", "0x61C808D82A3Ac53231750daDc13c777b59310bD9"], "address_metadata": {"0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8": {"user_id": "@0xea674fdde714fd979de3edf0f56aa9716b898ec8:localhost:8502", "capabilities": "mxc://raiden.network/cap?Receive=1&Mediate=1&Delivery=1&webRTC=1&toDevice=1&immutableMetadata=1", "displayname": "0xdf714485248a7d83f29e059622004acbb8a6b8a09c1506c304c2748e4e941cf769e864764ef028b31da525280d35d5ab87ee196dc738bc0f8de81ca3355a0c111b"}, "0x61C808D82A3Ac53231750daDc13c777b59310bD9": {"user_id": "@0x61c808d82a3ac53231750dadc13c777b59310bd9:localhost:8502", "capabilities": "mxc://raiden.network/cap?Receive=1&Mediate=1&Delivery=1&webRTC=1&toDevice=1&immutableMetadata=1", "displayname": "0x56682a1fecb4df0ce8e0e3aa9a0eaae4a6bc1a6265284f3fffbb1423e018122838353e6930c6000892e94f305b97c726a8e74c27dcce98adda9340f93555f5bb1c"}}}]}'

httpie

echo '{
  "amount": "200",
  "identifier": "42",
  "paths": [
    {
      "address_metadata": {
        "0x61C808D82A3Ac53231750daDc13c777b59310bD9": {
          "capabilities": "mxc://raiden.network/cap?Receive=1&Mediate=1&Delivery=1&webRTC=1&toDevice=1&immutableMetadata=1",
          "displayname": "0x56682a1fecb4df0ce8e0e3aa9a0eaae4a6bc1a6265284f3fffbb1423e018122838353e6930c6000892e94f305b97c726a8e74c27dcce98adda9340f93555f5bb1c",
          "user_id": "@0x61c808d82a3ac53231750dadc13c777b59310bd9:localhost:8502"
        },
        "0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8": {
          "capabilities": "mxc://raiden.network/cap?Receive=1&Mediate=1&Delivery=1&webRTC=1&toDevice=1&immutableMetadata=1",
          "displayname": "0xdf714485248a7d83f29e059622004acbb8a6b8a09c1506c304c2748e4e941cf769e864764ef028b31da525280d35d5ab87ee196dc738bc0f8de81ca3355a0c111b",
          "user_id": "@0xea674fdde714fd979de3edf0f56aa9716b898ec8:localhost:8502"
        }
      },
      "route": [
        "0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8",
        "0x61C808D82A3Ac53231750daDc13c777b59310bD9"
      ]
    }
  ]
}' | http POST http://localhost:5001/api/v1/payments/0x2a65Aca4D5fC5B5C859090a6c34d164135398226/0x61C808D82A3Ac53231750daDc13c777b59310bD9 Content-Type:application/json

python-requests

requests.post('http://localhost:5001/api/v1/payments/0x2a65Aca4D5fC5B5C859090a6c34d164135398226/0x61C808D82A3Ac53231750daDc13c777b59310bD9', headers={
    'Content-Type': 'application/json',
}, json={
    'amount': '200',
    'identifier': '42',
    'paths': [{
        'route': ['0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8', '0x61C808D82A3Ac53231750daDc13c777b59310bD9'],
        'address_metadata': {
            '0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8': {
                'user_id': '@0xea674fdde714fd979de3edf0f56aa9716b898ec8:localhost:8502',
                'capabilities': 'mxc://raiden.network/cap?Receive=1&Mediate=1&Delivery=1&webRTC=1&toDevice=1&immutableMetadata=1',
                'displayname': '0xdf714485248a7d83f29e059622004acbb8a6b8a09c1506c304c2748e4e941cf769e864764ef028b31da525280d35d5ab87ee196dc738bc0f8de81ca3355a0c111b',
            },
            '0x61C808D82A3Ac53231750daDc13c777b59310bD9': {
                'user_id': '@0x61c808d82a3ac53231750dadc13c777b59310bd9:localhost:8502',
                'capabilities': 'mxc://raiden.network/cap?Receive=1&Mediate=1&Delivery=1&webRTC=1&toDevice=1&immutableMetadata=1',
                'displayname': '0x56682a1fecb4df0ce8e0e3aa9a0eaae4a6bc1a6265284f3fffbb1423e018122838353e6930c6000892e94f305b97c726a8e74c27dcce98adda9340f93555f5bb1c',
            },
        },
    }],
})
Request JSON Object

  • amount (string) – Amount to be sent to the target

  • identifier (string) – Identifier of the payment (optional)

  • lock_timeout (string) – 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)

  • secret (string) – secret for the HTL, if this should not be randomly generated (optional)

  • secret_hash (string) – The hash of the provided secret (sha256(secret)) this feature currently only works if secret is provided. If secret is provided, but secret_hash is omitted the hash will be calculated by the client automatically (optional)

  • path (string) – static route to the target node (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 – The provided json is in some way malformed

  • 402 Payment Required – 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

  • 409 Conflict – The address or the amount is invalid, or there is no path to the target, or the identifier is already in use for a different payment, or the static path sent is not usable.

  • 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.

User Deposit

For paying the Raiden Services it is necessary to have RDN (Raiden Network Tokens) in the User Deposit Contract (UDC). This endpoint can be used to deposit to and withdraw from the UDC.

Deposit

POST /api/(version)/user_deposit

Deposit RDN tokens to the UDC.

Example Request:

http

POST /api/v1/user_deposit HTTP/1.1
Host: localhost:5001
Content-Type: application/json

{
    "total_deposit": "200000"
}

curl

curl -i -X POST http://localhost:5001/api/v1/user_deposit -H "Content-Type: application/json" --data-raw '{"total_deposit": "200000"}'

wget

wget -S -O- http://localhost:5001/api/v1/user_deposit --header="Content-Type: application/json" --post-data='{"total_deposit": "200000"}'

httpie

echo '{
  "total_deposit": "200000"
}' | http POST http://localhost:5001/api/v1/user_deposit Content-Type:application/json

python-requests

requests.post('http://localhost:5001/api/v1/user_deposit', headers={
    'Content-Type': 'application/json',
}, json={
    'total_deposit': '200000',
})
Request JSON Object

  • total_deposit (string) – The total deposit token amount. Should be the sum of the current total value and the desired (relative) deposit.

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
   "transaction_hash": "0xc5988c93c07cf1579e73d39ee2a3d6e948d959d11015465a77817e5239165170"
}
Status Codes

  • 200 OK – Deposit was successful

  • 400 Bad Request – The provided JSON is in some way malformed

  • 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 – No UDC is configured on the Raiden node

  • 409 Conflict – The provided total_deposit is not higher than the previous total_deposit or attempted to deposit more RDN than the UDC limit would allow

  • 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.

Plan a withdraw

POST /api/(version)/user_deposit

Before RDN can be withdrawn from the UDC the withdraw must be planned.

Example Request:

http

POST /api/v1/user_deposit HTTP/1.1
Host: localhost:5001
Content-Type: application/json

{
    "planned_withdraw_amount": "1500"
}

curl

curl -i -X POST http://localhost:5001/api/v1/user_deposit -H "Content-Type: application/json" --data-raw '{"planned_withdraw_amount": "1500"}'

wget

wget -S -O- http://localhost:5001/api/v1/user_deposit --header="Content-Type: application/json" --post-data='{"planned_withdraw_amount": "1500"}'

httpie

echo '{
  "planned_withdraw_amount": "1500"
}' | http POST http://localhost:5001/api/v1/user_deposit Content-Type:application/json

python-requests

requests.post('http://localhost:5001/api/v1/user_deposit', headers={
    'Content-Type': 'application/json',
}, json={
    'planned_withdraw_amount': '1500',
})
Request JSON Object

  • planned_withdraw_amount (string) – The amount of tokens for which a withdrawal should get planned.

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
   "planned_withdraw_block_number": 4269933,
   "transaction_hash": "0xec6a0d010d740df20ca8b3b6456e9deaab8abf3787cb676ee244bef7d28aa4fc"
}
Status Codes

Withdraw

POST /api/(version)/user_deposit

Withdraw RDN from the UDC. Can only be done 100 blocks after the withdraw was planned.

Example Request:

http

POST /api/v1/user_deposit HTTP/1.1
Host: localhost:5001
Content-Type: application/json

{
    "withdraw_amount": "1500"
}

curl

curl -i -X POST http://localhost:5001/api/v1/user_deposit -H "Content-Type: application/json" --data-raw '{"withdraw_amount": "1500"}'

wget

wget -S -O- http://localhost:5001/api/v1/user_deposit --header="Content-Type: application/json" --post-data='{"withdraw_amount": "1500"}'

httpie

echo '{
  "withdraw_amount": "1500"
}' | http POST http://localhost:5001/api/v1/user_deposit Content-Type:application/json

python-requests

requests.post('http://localhost:5001/api/v1/user_deposit', headers={
    'Content-Type': 'application/json',
}, json={
    'withdraw_amount': '1500',
})
Request JSON Object

  • withdraw_amount (string) – The amount of tokens which should get withdrawn.

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
   "transaction_hash": "0xfc7edd195c6cc0c9391d84dd83b7aa9dbfffbcfc107e5c33a5ab912c0d92416c"
}
Status Codes

  • 200 OK – Withdraw was successful

  • 400 Bad Request – The provided JSON is in some way malformed

  • 402 Payment Required – Insufficient ETH to pay for the gas of the on-chain transaction

  • 404 Not Found – No UDC is configured on the Raiden node

  • 409 Conflict – The provided withdraw_amount is higher than the planned amount or not greater than zero or the withdraw is too early

  • 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.

Connections

The connections endpoints allow you to query details about all joined token networks as well as leave a token network by closing and settling all open channels.

Details of All Joined Token Networks

GET /api/(version)/connections

The request will return a JSON object where each key is a token address for which you have open channels.

Example Request:

http

GET /api/v1/connections HTTP/1.1
Host: localhost:5001

curl

curl -i -X GET http://localhost:5001/api/v1/connections

wget

wget -S -O- http://localhost:5001/api/v1/connections

httpie

http http://localhost:5001/api/v1/connections

python-requests

requests.get('http://localhost:5001/api/v1/connections')

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
   "0x2a65Aca4D5fC5B5C859090a6c34d164135398226": {
         "sum_deposits": "67",
         "channels": "3"
   },
   "0x0f114A1E9Db192502E7856309cc899952b3db1ED": {
         "sum_deposits": "31",
         "channels": "1"
   }
}
Status Codes
Response JSON Array of Objects

  • sum_deposits (string) – Sum of deposits in all currently open channels

  • channels (string) – Number of channels currently open for the specific token

Leave a Token Network

DELETE /api/(version)/connections/(token_address)

The request might take some time because it will only return once all blockchain calls for closing and settling a channel have been completed.

The response is a list of all the channel state objects of the channels that have been closed.

Example Request:

http

DELETE /api/v1/connections/0x2a65Aca4D5fC5B5C859090a6c34d164135398226 HTTP/1.1
Host: localhost:5001
Content-Type: application/json

curl

curl -i -X DELETE http://localhost:5001/api/v1/connections/0x2a65Aca4D5fC5B5C859090a6c34d164135398226 -H "Content-Type: application/json"

wget

wget -S -O- --method=DELETE http://localhost:5001/api/v1/connections/0x2a65Aca4D5fC5B5C859090a6c34d164135398226 --header="Content-Type: application/json"

httpie

http DELETE http://localhost:5001/api/v1/connections/0x2a65Aca4D5fC5B5C859090a6c34d164135398226 Content-Type:application/json

python-requests

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

~
  [
      {
          "balance": "0",
          "channel_identifier": "8854",
          "network_state": "unknown",
          "partner_address": "0x4D156A78Ed6dFDfBbF3E569558eAF895b40217D6",
          "reveal_timeout": "50",
          "settle_timeout": "500",
          "state": "closed",
          "token_address": "0x59105441977ecD9d805A4f5b060E34676F50F806",
          "token_network_address": "0x625F82D937ccA0f1fF0097864895ba91635309A3",
          "total_deposit": "100000000000000000",
          "total_withdraw": "100000000000000000"
      },
      {
          "balance": "0",
          "channel_identifier": "81",
          "network_state": "unknown",
          "partner_address": "0xbea332584a468b462100f8bfe5b38b0573ef1e36",
          "reveal_timeout": "50",
          "settle_timeout": "500",
          "state": "closed",
          "token_address": "0x59105441977ecD9d805A4f5b060E34676F50F806",
          "token_network_address": "0x625F82D937ccA0f1fF0097864895ba91635309A3",
          "total_deposit": "2000000000000",
          "total_withdraw": "2000000000000"
      }
  ]
Status Codes

Note

Currently, the API calls are blocking. This means that in the case of long running calls like leave a token network, if an API call is currently being processed by Raiden, all pending calls will be queued and processed with their passed API call argument.

Pending Transfers

The pending transfers endpoints let you query information about transfers that have not been completed yet.

GET /api/(version)/pending_transfers

Returns a list of all transfers that have not been completed yet.

Example Request:

http

GET /api/v1/pending_transfers HTTP/1.1
Host: localhost:5001

curl

curl -i -X GET http://localhost:5001/api/v1/pending_transfers

wget

wget -S -O- http://localhost:5001/api/v1/pending_transfers

httpie

http http://localhost:5001/api/v1/pending_transfers

python-requests

requests.get('http://localhost:5001/api/v1/pending_transfers')

See below for an example response.

GET /api/(version)/pending_transfers/(token_address)

Limits the response to pending transfers of the specified token.

Example Request:

http

GET /api/v1/pending_transfers/0xd0A1E359811322d97991E03f863a0C30C2cF029C HTTP/1.1
Host: localhost:5001

curl

curl -i -X GET http://localhost:5001/api/v1/pending_transfers/0xd0A1E359811322d97991E03f863a0C30C2cF029C

wget

wget -S -O- http://localhost:5001/api/v1/pending_transfers/0xd0A1E359811322d97991E03f863a0C30C2cF029C

httpie

http http://localhost:5001/api/v1/pending_transfers/0xd0A1E359811322d97991E03f863a0C30C2cF029C

python-requests

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)

Limits the response to pending transfers of the specified token and channel.

Example Request:

http

GET /api/v1/pending_transfers/0xd0A1E359811322d97991E03f863a0C30C2cF029C/0x2c4b0Bdac486d492E3cD701F4cA87e480AE4C685 HTTP/1.1
Host: localhost:5001

curl

curl -i -X GET http://localhost:5001/api/v1/pending_transfers/0xd0A1E359811322d97991E03f863a0C30C2cF029C/0x2c4b0Bdac486d492E3cD701F4cA87e480AE4C685

wget

wget -S -O- http://localhost:5001/api/v1/pending_transfers/0xd0A1E359811322d97991E03f863a0C30C2cF029C/0x2c4b0Bdac486d492E3cD701F4cA87e480AE4C685

httpie

http http://localhost:5001/api/v1/pending_transfers/0xd0A1E359811322d97991E03f863a0C30C2cF029C/0x2c4b0Bdac486d492E3cD701F4cA87e480AE4C685

python-requests

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
Response JSON Array of Objects

  • role (string) – One of “initiator”, “mediator” and “target”

Notifications

GET /api/(version)/notifications

Raiden can inform the user about conditions that may require an action by the user or their attention. These are the types of notifications that currently can be returned, listed by id:

  • low_rdn: RDN tokens deposited in the UDC are below a threshold.

  • version_outdated: Running an outdated version of Raiden.

  • missing_gas_reserve: ETH balance is below a threshold and you may not be able to perform on-chain transactions.

  • version_security_warning: There is an important security update.

Example Request:

http

GET /api/v1/notifications HTTP/1.1
Host: localhost:5001

curl

curl -i -X GET http://localhost:5001/api/v1/notifications

wget

wget -S -O- http://localhost:5001/api/v1/notifications

httpie

http http://localhost:5001/api/v1/notifications

python-requests

requests.get('http://localhost:5001/api/v1/notifications')

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

[
   {
      "body": "WARNING\nYour account's RDN balance deposited in the UserDepositContract of 0.0 is below the minimum threshold 5.5. Provided that you have either a monitoring service or a path finding service activated, your node is not going to be able to pay those services which may lead to denial of service or loss of funds.",
      "id": "low_rdn",
      "summary": "RDN balance too low",
      "urgency": "normal"
   },
   {
      "body": "You're running version 1.1.1.dev630+g43ae6e32b. The latest version is 1.2.0It's time to update! Releases: https://github.com/raiden-network/raiden/releases",
      "id": "version_outdated",
      "summary": "Your version is outdated",
      "urgency": "normal"
   }
]

Shutdown

POST /api/(version)/shutdown

You can call the shutdown endpoint to stop a running Rainde node.

Example Request:

http

POST /api/v1/shutdown HTTP/1.1
Host: localhost:5001

curl

curl -i -X POST http://localhost:5001/api/v1/shutdown

wget

wget -S -O- http://localhost:5001/api/v1/shutdown

httpie

http POST http://localhost:5001/api/v1/shutdown

python-requests

requests.post('http://localhost:5001/api/v1/shutdown')

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
   "status": "shutdown"
}

Testing

You can mint tokens for testing purposes by making a request to the _testing endpoint. This is only possible on testnets.

Mint Tokens

POST /api/(version)/_testing/tokens/(token_address)/mint

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 privileges.

Example Request:

http

POST /api/v1/_testing/tokens/0x782CfA3c74332B52c6f6F1758913815128828209/mint HTTP/1.1
Host: localhost:5001
Content-Type: application/json

{
   "to": "0x2c4b0Bdac486d492E3cD701F4cA87e480AE4C685",
   "value": "1000"
}

curl

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

wget -S -O- http://localhost:5001/api/v1/_testing/tokens/0x782CfA3c74332B52c6f6F1758913815128828209/mint --header="Content-Type: application/json" --post-data='{"to": "0x2c4b0Bdac486d492E3cD701F4cA87e480AE4C685", "value": "1000"}'

httpie

echo '{
  "to": "0x2c4b0Bdac486d492E3cD701F4cA87e480AE4C685",
  "value": "1000"
}' | http POST http://localhost:5001/api/v1/_testing/tokens/0x782CfA3c74332B52c6f6F1758913815128828209/mint Content-Type:application/json

python-requests

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 (string) – 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.