JSON-RPC API

Overview

This API is based on JSON-RPC, so the body should always contain the jsonrpc and id fields. The documentation below only specifies the method and params fields for requests, and the result field for responses.

Remember to always include the Content-Type: application/json and Authorization: Bearer YOUR_JWT_TOKEN headers.

For the URLs, remember to substitute the correct network (mainnet, ropsten, rinkeby) for <NETWORK> and zone1 or zone2 for <ZONE>. When transacting, the precise URL prefix (of the form https://<ZONE>.<NETWORK>.kchannels.io/client/) should be obtained from the Client Information endpoint in the Supporting API .

See Schemas for the schemas of the objects mentioned in the document, and see API authentication for how to obtain a JWT token.

Opening a channel

Create a draft of a channel definition

This request asks the backend to draft a channel definition on behalf of the client. The returned draft is not yet signed by anyone and is not binding.

URL: https://zone-manager.<NETWORK>.kchannels.io/client/channel/

REQUEST

  • Method: create_channel_definition

  • Params (array): [] (empty array)

RESPONSE

  • Result: a ChannelDefinition object with an empty signature_list

Next steps 1) Validate the object, making sure the all the fields are correct, including owner_address, deposit_address, and sender_address_list. If one of these fields is incorrect, do not proceed. 2) If you want to, you can add additional addresses to the sender_address_list. If you have a smart contract wallet, you can change the deposit_address (which initially matches owner_address) to the smart contract address. 3) Sign the object (excluding the signature_list portion) using EIP-712 and append the signature to signature_list. 4) Submit the signed draft of the channel definition, as follows:

Update and complete the channel definition

This request submits a signed ChannelDefinition to the backend, which is signed by the backend and returned. Once this happens, the client has an open channel with the backend.

URL: https://zone-manager.<NETWORK>.kchannels.io/client/channel/

REQUEST

  • Method: update_and_complete_channel_definition

  • Params: an array containing the signed ChannelDefinition object

RESPONSE

  • Result: the same channel definition as before, this time with two additional signatures in signature_list. This is the authoritative channel definition, and should be saved away. The channel is now open, and you can send transactions through it.

Next steps 1) Validate the object once more. If anything is incorrect, do not proceed. 2) Save the signed and authoritative ChannelDefinition object for your records. 2) You may start transacting through the channel.

Transacting

Create a new transaction

This requests the backend to create a new transaction based on several parameters. This the first of 3 APIs that are required to transact.

URL: https://<ZONE>.<NETWORK>.kchannels.io/client/transaction/

REQUEST

  • Method: create_new_transaction

  • Params (array):

    • Params[0]: sender's address

    • Params[1]: sender's channel UUID

    • Params[2]: sender's channel definition version

    • Params[3]: recipient's address

    • Params[4]: array of TransactionValue objects (these are the assets being transferred, and their amounts)

    • Params[5]: true to force an external transaction, otherwise false. If the recipient doesn't have an open channel with Kchannels, the backend detects this situation and can send the transaction from the sender's channel to the recipient's address as an Layer1 (on-chain) transaction. However, even if the recipient has an open channel, an external transaction can be forced by setting this flag. This should default to false.

    • Params[6]: null

    • Params[7]: If true, fees will be subtracted from the amount sent, so that the amount received by the recipient is smaller than the nominal amount sent. This is useful for (among other things) completely "emptying out" a channel, without leaving behind any dust. The default should be false (fees are added on top of the nominal amount sent).

RESPONSE

  • Result (object): a Transaction object. The summary fields under sender_party and recipient_party are each null, and the signature_list field under metadata is empty.

Next steps 1) Validate the transaction object. If anything is incorrect, do not proceed. 2) Sign the transaction using EIP-712 and append the signature to the top-level signature_list field 3) Submit the signed transaction, as follows:

Process the transaction

Submit a signed transaction to the backend. This the second of 3 APIs that are required to transact.

URL: https://<ZONE>.<NETWORK>.kchannels.io/client/transaction/

REQUEST

  • Method: process_transaction

  • Params (array):

    • Params[0]: Signed Transaction object

    • Params[1]: Sender's hyphenated channel UUID (36 characters)

    • Params[2]: Sender's channel definition version (integer as a string)

RESPONSE

  • Result (array):

    • Result[0]: Transaction object, this time with 2 additional signatures in the top-level signature_list object, and an additional signature in the metadata field's signature_list object.

    • Result[1]: TransactionSummary object

Next steps 1) Validate the response. If anything is incorrect, do not proceed. 2) Sign the TransactionSummary component using EIP-712 and append the signature to its signature_list. 3) Submit the signed TransactionSummary, as follows:

Complete the transaction

Submit a signed transaction summary to the backend. This the third and last of 3 APIs that are required to transact.

URL: https://<ZONE>.<NETWORK>.kchannels.io/client/transaction/

REQUEST

  • Method: complete_transaction

  • Params (array):

    • Params[0]: Signed TransactionSummary object

    • Params[1]: Sender's hyphenated channel UUID (36 characters)

    • Params[2]: Sender's channel definition version (integer as a string)

RESPONSE

  • Result (array):

    • Result[0]: Signed TransactionSummary object, this time with 2 additional signatures in the signature_list field

    • Result[1]: Status of the transaction (string)

Next steps 1) Validate the response. 2) Save the triply-signed TransactionSummary object for your records. This object shows your final state and can be used as a proof in case of any disputes. 3) Unless the status (Result[1]) indicates an error, the transaction is complete and final.

Fail the transaction

Fail a transaction that hasn't successfully completed.

URL: https://<ZONE>.<NETWORK>.kchannels.io/client/transaction/

REQUEST

  • Method: fail_transaction

  • Params (array):

    • Params[0]: TransactionSummary object

    • Params[1]: Sender's hyphenated channel UUID (36 characters)

    • Params[2]: Sender's channel definition version (integer as a string)

RESPONSE

  • Result (array):

    • Result[0]: TransactionSummary object

Next steps 1) Validate the response. 2) Save the TransactionSummary object for your records. This object shows your final state and can be used as a proof in case of any disputes.

Abandon transactions on the channel

Abandon transactions on the channel.

URL: https://<ZONE>.<NETWORK>.kchannels.io/client/transaction/

REQUEST

  • Method: abandon_transactions

  • Params (array):

    • Params[0]: Ethereum address of the client

    • Params[1]: Sender's hyphenated channel UUID (36 characters)

    • Params[2]: Sender's channel definition version (integer as a string)

RESPONSE

  • Result (array): [] (empty array)

Withdrawing from a channel

To withdraw assets from a channel, simply send a transaction to a desired address (such as the channel definition's deposit_address or owner_address, or any address at all) and force the transaction to be an external transaction (Params[5] = true). You may also want to set Params[7] = true in case you want to easily withdraw every last wei.

PreviousAPI authenticationNextSupporting API

Last updated