API Tutorial

This tutorial will show you how to use Raiden via the API by walking you through a few API calls. The steps are similar to the WebUI tutorial, but directly use the API endpoints. We will outline the steps necessary for participating in a token network. To see all available endpoints visit the resources part of the documentation.

In the examples throughout this tutorial we will be using a hypothetical ERC20 token with the address 0x9aBa529db3FF2D8409A1da4C9eB148879b046700.

Check if Raiden was started correctly

Before we start we’ll make sure that Raiden is running correctly.

This gives us an opportunity to introduce the address endpoint.

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

Your Raiden node is up and running if the response returns the same address as the Ethereum address used for starting Raiden.

You’re now ready to start interacting with the different endpoints and learn how they can be used.

Create a Token Network

Check if the token is registered

Before you can join a token network you need to determine whether the token has been registered and a network for the token has been created.

We can verify this by making a query to the tokens endpoint.

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

If the address exists in the list returned by the response you can go ahead and open a channel in that token network.

If the address is not in the list you’ll have to register the token before you can open a channel.

Register a new token

Registering a new token is as simple as calling the tokens endpoint with a PUT request while providing the address of the token you want to register as a path parameter.

curl -i -X PUT http://localhost:5001/api/v1/tokens/0x9aBa529db3FF2D8409A1da4C9eB148879b046700 \
-H 'Content-Type: application/json'

If the call is successful the response will return a new address of the now newly created token network.

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

{
    "token_network_address": "0xC4F8393fb7971E8B299bC1b302F85BfFB3a1275a"
}

Because this token was just registered by you, no one else will be connected to its network and you’ll have to open a channel with another Raiden node.

Note

Payment channels between parties are opened in token networks.

Warning

Registering a new token is currently only relevant on the testnets. The tokens allowed on the mainnet for the Coruscant release are DAI and W-ETH. At some point in future, you will be able to register new token networks for the Ethereum mainnet, too.

Open a Channel

This section will cover the endpoints you would use to:

  1. Find suitable partner nodes

  2. Open a channel

  3. Query the state of a channel

Find suitable partner nodes

To make payments, you need to be connected to the target node either directly, or indirectly by having a channel with a well connected that mediates your payment to the target. If you already know to which node you want to connect, skip ahead to the next section.

The Path Finding Service (PFS) can suggest partners that are highly connected. These nodes will be able to mediate your payments to a large amount of potential targets and are thus a good choice for your first channel(s). Ask the PFS by sending a GET request to its partner suggestion endpoint for the token you want to use.

curl https://pfs.of.your.choice/api/v1/0x9aBa529db3FF2D8409A1da4C9eB148879b046700/suggest_partner

If you don’t know which PFS to ask, you can get the URL of the PFS used by your Raiden node from the settings endpoint. The list of suggested partners is sorted with the most recommended ones coming first. If you want to open just a single channel, picking the address of the first partner in the results is a reasonable choice.

[
  {
    "address": "0x99eB1aADa98f3c523BE817f5c45Aa6a81B7c734B",
    "score": 2906634538666422000,
    "centrality": 0.0004132990448199853,
    "uptime": 7032.763746,
    "capacity": 1000000000000000000
  },
  {
    "address": "0x4Fc53fBa9dFb545B66a0524216c982536012186e",
    "score": 2906693668947465000,
    "centrality": 0.0004132990448199853,
    "uptime": 7032.906815,
    "capacity": 1000000000000000000
  }
]

Open a channel

To open a channel a PUT request is made to the channels endpoint that includes a JSON object containing:

  1. The address of the node you’d like to open the channel with.

  2. The amount of tokens you want to deposit in the channel. (Remember that it is always possible to deposit more tokens later.)

  3. The settle timeout period which corresponds to the number of blocks that have to be mined before a closed channel can be settled.

curl -i -X PUT \
http://localhost:5001/api/v1/channels \
-H 'Content-Type: application/json' \
--data-raw '{"partner_address": "0x61C808D82A3Ac53231750daDc13c777b59310bD9", "token_address": "0x9aBa529db3FF2D8409A1da4C9eB148879b046700", "total_deposit": "1337", "settle_timeout": "500"}'

This will create a new channel and a successful request will return you the following response object:

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

{
    "token_network_address": "0x3C158a20b47d9613DDb9409099Be186fC272421a",
    "channel_identifier": "99",
    "network_state": "unknown",
    "partner_address": "0x61C808D82A3Ac53231750daDc13c777b59310bD9",
    "token_address": "0x9aBa529db3FF2D8409A1da4C9eB148879b046700",
    "balance": "1337",
    "total_deposit": "1337",
    "total_withdraw": "0",
    "state": "opened",
    "settle_timeout": "500",
    "reveal_timeout": "50"
}

As you can tell by the response object a channel identifier has been generated. This means that there now is a channel with that identifier inside the token network.

You’re now ready to start making payments.

Note

Opening a channel with a partner node is not dependent on whether the partner node holds tokens or not. It will work either way.

Query the state of a channel

Checking the current state of a channel is as easy as making a query to the channels endpoint while providing:

  1. The token address as a path parameter.

  2. The address of the partner node as a path parameter.

curl -i \
http://localhost:5001/api/v1/channels/0x9aBa529db3FF2D8409A1da4C9eB148879b046700/0x61C808D82A3Ac53231750daDc13c777b59310bD9

This will give you the same response object as when opening a channel.

Deposit Tokens

If you opened a channel by yourself you most likely already deposited tokens when sending the request. However, in case someone opened a channel with you, you will not have any tokens at your end of the channel.

You need to make a deposit whenever you want to:

  • Add tokens to an empty channel

  • Top up the amount of tokens in a channel

Deposit into a channel

The channel endpoint together with a PATCH request is used for depositing tokens into a channel. When making the call you need to include:

  1. The token address as a path parameter.

  2. The address of the partner node as a path parameter.

  3. The amount of tokens you want to deposit in the channel as a body parameter.

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

This will give you the same response object as when opening a channel or querying the state of a channel.

Now, once there are tokens at your end of the channel, let’s start making payments.

Make a Payment

A powerful feature of Raiden is the ability to let you pay anyone in the network by using a path of connected payment channels to mediate the payment and not only directly connected nodes. These payments are called mediated transfers.

Pay

Payments are made from the payments endpoint via a POST request that needs to include:

  1. The address of the token you want to pay with as a path parameter.

  2. The address of the node receiving your payment as a path parameter.

  3. The amount you would like to pay as a body parameter.

curl -i -X POST \
http://localhost:5001/api/v1/payments/0x9aBa529db3FF2D8409A1da4C9eB148879b046700/0x61C808D82A3Ac53231750daDc13c777b59310bD9 \
-H 'Content-Type: application/json' \
--data-raw '{"amount": "42"}'

Note

You can provide the body parameter with an additional identifier key with a value of your choice. This value can be a number ("identifier": 42) or the stringified number ("identifier": "42").

This is optional and the purpose of the identifier is to give dApps built on Raiden a way to tag payments.

Your payment will most likely succeed if:

  • The path of channels leading from your node to the node receiving your payment has enough capacity.

  • All nodes needed to mediate the payment are online.

  • You have enough tokens in the channel from which you intend to pay out the amount specified in the request body.

To get your tokens out of a channel and back on-chain you either have to withdraw the tokens or close the channel.

View payment history

You can view all transactions you’ve made with a partner node by querying the payments endpoint in a GET request, using the same path parameters as when making a payment.

curl -i \
http://localhost:5001/api/v1/payments/0x9aBa529db3FF2D8409A1da4C9eB148879b046700/0x61C808D82A3Ac53231750daDc13c777b59310bD9

In the response you will be able to see all successful payments, all failed payments and all payments you have received.

Withdraw Tokens

Similar to depositing, a PATCH call to the channel endpoint is used for withdrawing with the difference that a value for total_withdraw is provided in the request body.

So, whenever you’d like to make a withdraw your request needs to include:

  1. The token address as a path parameter.

  2. The address of the node you have the channel with as a path parameter.

  3. The amount of tokens you want to withdraw as a body parameter.

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

In the next section we will take a look at how to withdraw all tokens for a channel and how to leave a token network completely.

Settle Payments and Close Channels

You can choose to either:

  1. Close a specific channel

  2. Leave a token network and close all channels

Close a specific channel

Closing a specific channel is done with a PATCH request to the channels endpoint that includes:

  1. The token address as a path parameter.

  2. The address of the partner node as a path parameter.

  3. The state set to “closed” in the body parameter.

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

A successful response will return a normal channel object with the state set to "closed".

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

{
    "token_network_address": "0x3C158a20b47d9613DDb9409099Be186fC272421a",
    "channel_identifier": "99",
    "network_state": "unknown",
    "partner_address": "0x61C808D82A3Ac53231750daDc13c777b59310bD9",
    "token_address": "0x9aBa529db3FF2D8409A1da4C9eB148879b046700",
    "balance": "350",
    "total_deposit": "7331",
    "total_withdraw": "0",
    "state": "closed",
    "settle_timeout": "500",
    "reveal_timeout": "50"
}

Note

The settle timeout period will start as soon as a channel is closed and the channel is settled once the settle timeout period is over. The state of the channel will then be changed to settled.

Leave a token network and close all channels

If you wish to leave a token network altogether you can do so by making a DELETE request to the connections endpoint with the token address as a path parameter.

curl -i -X DELETE \
http://localhost:5001/api/v1/connections/0x9aBa529db3FF2D8409A1da4C9eB148879b046700 \
-H 'Content-Type: application/json'

Once done, the response will return a list of channel-state objects of all closed channels.

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

[
     {
         "token_network_address": "0x3C158a20b47d9613DDb9409099Be186fC272421a",
         "channel_identifier": "99",
         "network_state": "unknown",
         "partner_address": "0x61C808D82A3Ac53231750daDc13c777b59310bD9",
         "token_address": "0x9aBa529db3FF2D8409A1da4C9eB148879b046700",
         "balance": "350",
         "total_deposit": "7331",
         "total_withdraw": "0",
         "state": "closed",
         "settle_timeout": "500",
         "reveal_timeout": "50"
     }
]

Note

Please note that leaving a token network will take some time since you need to wait for the settle timeout to expire for each channel before a settle can happen.