JSON-RPC API

Search…
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.
​
API authentication
Supporting API
Last modified 1yr ago
Copy link
Contents
Overview
Opening a channel
Transacting
Withdrawing from a channel