Insolar API (1.0.6)

Download OpenAPI specification:Download

Insolar Platform JSON RPC 2.0 API documentation.

Definitions Overview

Insolar is being developed to provide interoperation between enterprises.

From a business perspective:

  • Any enterprise is regarded as an entity with a corresponding identity — a member object stored in the blockchain.
  • Any member has its own account to/from which the member can transfer funds.

From a technical perspective:

  • Every member object is identified by a reference in the blockchain.
  • The reference is effectively the member's address.

Therefore, an entity wishing to transfer funds to/from its account from/to a particular address, in Insolar's terms, is a member object identified by its reference wishing to transfer funds to some other member identified by the corresponding reference.

Insolar uses these terms in method and parameter names.

Request Specification

Insolar has two types of requests that have the same base structure in accordance with the JSON RPC 2.0 specification:

  • Information requests that do not require a seed.
  • Contract requests that do. These requests are described in Member and Migration sections.

Seed is a unique piece of information generated by a node that:

  • has a short lifespan — 10 minutes;
  • expires upon first use;
  • protects from request duplicates.

Since the seed is generated by a node, it must be validated by the same node. Therefore, each subsequent contract request containing the seed must be sent to the node that generated it.

To call a smart contract's method, go through the following steps:

  1. Send a getSeed information request and receive the seed.

    For example, the getSeed request is as follows:

    {
        "jsonrpc": "2.0",
        "id": 1,
        "method": "node.getSeed"
    }

    And the response is:

    {
      "jsonrpc": "2.0",
      "id": 1,
      "result": {
      "seed": "<seed>"
      }
    }
  2. Form and sign a contract request (e.g., member.create) with the acquired seed.

    Every contract request is to contain the Digest and Signature HTTP headers. For example:

    POST /<endpoint> HTTP/1.1
    Host: <Host>
    Date: Tue, 07 Jun 2019 20:51:35 GMT
    Content-Type: application/json
    Digest: SHA-256=<hashString>
    Signature: keyId="public-key", algorithm="ecdsa", headers="digest", signature=<signatureString>
    
    { <payload> }

    And the contract request's <payload> with the seed may be as follows:

    {
      "jsonprc": "2.0",
      "id": 2,
      "method": "contract.call",
      "params": {
        "seed": "<seed>",
        "callSite": "member.create",
        "callParams": {},
        "publicKey": "<pubicKey>"
      }
    }

    In this example:

    • Digest HTTP header contains the Base64 <hashString> with the SHA-256 hash of the payload's bytes.

    • Signature HTTP header contains the Base64 <signatureString> with the ECDSA (Elliptic Curve Digital Signature Algorithm) signature in the ASN.1 DER format. Signed are the bytes of the hash from the Digest header.

    • <pubicKey> contains a Base64 string with the ECDSA public key in PEM format.

    • <seed> contains the seed acquired in the previous getSeed request.

    • "method": "contract.call" designates a call to a contract's method.

    • callSite is the contract method's call point, in this case, member.create.

    • callParams are the contract method's parameters.

  3. Send the formed and signed contract request to the node that generated the seed.

    Insolar responds to contract requests with:

    {
      "jsonrpc": "2.0",
      "id": 2,
      "result": {
      "callResult": {
         "reference": <referenceString>
         },
      "requestReference": <requestReferenceString>,
      "traceID": <traceIDString>
      }
    }

    Where "callResult" contains the result of the contract's method execution. In this case, it is a reference to a newly created member object since the "callSite" of the request is "member.create".

Errors

Insolar follows the JSON RPC API conventions on error codes, with values -31000--31999 reserved for the Insolar network.

Below is the list of Insolar Platform errors.

Code Message
-31700 Parsing error on the server side: received an invalid JSON.
-31600 The JSON received is not a valid request payload.
-31601 Method does not exist / is not available.
-31602 Invalid method parameter(s).
-31603 Internal Platform error.
-31106 Request's timeout has expired.
-31401 Action is not authorized.
-31429 Service unavailable, try again later.
-31103 Execution error.

Versioning

The API is usually changed in each release of Insolar, so API calls are versioned to ensure that clients do not break.

To lock to an API version, prefix the URL with the version number. For example, calling /api/rpc is the same as calling /v1.0.0/api/rpc.

Insolar releases in the near future will support this version of the API, so your client will continue to work even if it is talking to a newer API.

API versions do not have correlations to Insolar Platform versions.

Information

node.getSeed

Gets a new seed (random byte range).

Each signed contract request has to contain a new seed in its body. Seed is a unique piece of information generated by a node that:

  • has a short lifespan — 10 minutes;
  • expires upon first use;
  • protects from request duplicates.

Since the seed is generated by a node, it must be validated by the same node. Therefore, each subsequent contract request containing the seed must be sent to the node that generated it.

Request Body schema: application/json
jsonrpc
required
string
Value: "2.0"
id
required
string or number

Request's ID to link it with the corresponding result.

method
required
string
Value: "node.getSeed"

Name of the method to invoke.

params
object

May be omitted as the method does not require any.

Responses

200

OK

Response Schema: application/json
One of
  • Success
  • Errors
jsonrpc
required
string
Value: "2.0"
id
required
string or number

ID passed by the request.

result
required
object

Execution result of the invoked method.

post /api/rpc#node.getSeed

Production server

https://wallet-api.insolar.io/api/rpc#node.getSeed

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "jsonrpc": "2.0",
  • "method": "node.getSeed",
  • "id": 1
}

Response samples

Content type
application/json
Example
Copy
Expand all Collapse all
{
  • "jsonrpc": "2.0",
  • "id": 1,
  • "result":
    {
    }
}

Member

member.create

Creates a new member object with a corresponding account and wallet.

To invoke this method, specify a publicKey to associate with the new member.

Returns a reference to the new member object.

header Parameters
Digest
required
string^SHA-256=.+$
Example: SHA-256=<hashString>

Digest HTTP header with an SHA-256 hash of the request's payload bytes in a Base64 <hashString>.

Signature
required
string
Example: keyId="member-pub-key", algorithm="ecdsa", headers="digest", signature=<signatureString>

Signature HTTP header with the signed hash bytes in a Base64 <signatureString>.

The signature is:

  • in ASN.1 DER format;
  • generated by an ECDSA private key;
  • checked by the paired public key (publicKey).
Request Body schema: application/json
jsonrpc
required
string
Value: "2.0"
id
required
string or number

Request's ID to link it with the corresponding result.

method
required
string
Value: "contract.call"

Name of the method to invoke.

params
required
object

Parameter values to pass to the invoked method.

Responses

200

OK

Response Schema: application/json
One of
  • Success
  • Errors
jsonrpc
required
string
Value: "2.0"
id
required
string or number

ID passed by the request.

result
required
object

Execution result of the invoked method.

post /api/rpc#member.create

Production server

https://wallet-api.insolar.io/api/rpc#member.create

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "jsonrpc": "2.0",
  • "method": "contract.call",
  • "id": 1,
  • "params":
    {
    }
}

Response samples

Content type
application/json
Example
Copy
Expand all Collapse all
{
  • "jsonrpc": "2.0",
  • "id": 1,
  • "result":
    {
    }
}

member.get

Gets information on an existing member and, effectively, authorizes the member in the Insolar network.

To invoke this method, specify a publicKey associated with an existing member.

Returns the following information:

  • (required) reference to the member object,
  • (optional) associated migrationAddress (if any) — only during the period of token migration from the Ethereum network.
header Parameters
Digest
required
string^SHA-256=.+$
Example: SHA-256=<hashString>

Digest HTTP header with an SHA-256 hash of the request's payload bytes in a Base64 <hashString>.

Signature
required
string
Example: keyId="member-pub-key", algorithm="ecdsa", headers="digest", signature=<signatureString>

Signature HTTP header with the signed hash bytes in a Base64 <signatureString>.

The signature is:

  • in ASN.1 DER format;
  • generated by an ECDSA private key;
  • checked by the paired public key (publicKey).
Request Body schema: application/json
jsonrpc
required
string
Value: "2.0"
id
required
string or number

Request's ID to link it with the corresponding result.

method
required
string
Value: "contract.call"

Name of the method to invoke.

params
required
object

Parameter values to pass to the invoked method.

Responses

200

OK

Response Schema: application/json
One of
  • Success
  • Errors
jsonrpc
required
string
Value: "2.0"
id
required
string or number

ID passed by the request.

result
required
object

Execution result of the invoked method.

post /api/rpc#member.get

Production server

https://wallet-api.insolar.io/api/rpc#member.get

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "jsonrpc": "2.0",
  • "method": "contract.call",
  • "id": 1,
  • "params":
    {
    }
}

Response samples

Content type
application/json
Example
Copy
Expand all Collapse all
{
  • "jsonrpc": "2.0",
  • "id": 1,
  • "result":
    {
    }
}

member.transfer

Transfers an amount of XNS coin fractions from some member's account to another.

To invoke this method, specify the following parameters:

  • in params, the member reference (returned by member.create) to transfer coins from;
  • in callParams, the toMemberReference to transfer coins to;
  • in params, the amount of XNS coin fractions to transfer.

Returns factual fee value according to the current tariff.

header Parameters
Digest
required
string^SHA-256=.+$
Example: SHA-256=<hashString>

Digest HTTP header with an SHA-256 hash of the request's payload bytes in a Base64 <hashString>.

Signature
required
string
Example: keyId="member-pub-key", algorithm="ecdsa", headers="digest", signature=<signatureString>

Signature HTTP header with the signed hash bytes in a Base64 <signatureString>.

The signature is:

  • in ASN.1 DER format;
  • generated by an ECDSA private key;
  • checked by the paired public key (publicKey).
Request Body schema: application/json
jsonrpc
required
string
Value: "2.0"
id
required
string or number

Request's ID to link it with the corresponding result.

method
required
string
Value: "contract.call"

Name of the method to invoke.

params
required
object

Parameter values to pass to the invoked method.

Responses

200

OK

Response Schema: application/json
One of
  • Success
  • Errors
jsonrpc
required
string
Value: "2.0"
id
required
string or number

ID passed by the request.

result
required
object

Execution result of the invoked method.

post /api/rpc#member.transfer

Production server

https://wallet-api.insolar.io/api/rpc#member.transfer

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "jsonrpc": "2.0",
  • "id": 1,
  • "method": "contract.call",
  • "params":
    {
    }
}

Response samples

Content type
application/json
Example
Copy
Expand all Collapse all
{
  • "jsonrpc": "2.0",
  • "id": "1",
  • "result":
    {
    }
}

Migration

member.migrationCreate

Creates a new member object with a corresponding account and wallet.

To invoke this method, specify a publicKey to associate with the new member.

Returns the following information:

  • reference to the new member object,
  • associated migrationAddress — only during the period of token migration from the Ethereum network.
header Parameters
Digest
required
string^SHA-256=.+$
Example: SHA-256=<hashString>

Digest HTTP header with an SHA-256 hash of the request's payload bytes in a Base64 <hashString>.

Signature
required
string
Example: keyId="member-pub-key", algorithm="ecdsa", headers="digest", signature=<signatureString>

Signature HTTP header with the signed hash bytes in a Base64 <signatureString>.

The signature is:

  • in ASN.1 DER format;
  • generated by an ECDSA private key;
  • checked by the paired public key (publicKey).
Request Body schema: application/json
jsonrpc
required
string
Value: "2.0"
id
required
string or number

Request's ID to link it with the corresponding result.

method
required
string
Value: "contract.call"

Name of the method to invoke.

params
required
object

Parameter values to pass to the invoked method.

Responses

200

OK

Response Schema: application/json
One of
  • Success
  • Errors
jsonrpc
required
string
Value: "2.0"
id
required
string or number

ID passed by the request.

result
required
object

Execution result of the invoked method.

post /api/rpc#member.migrationCreate

Production server

https://wallet-api.insolar.io/api/rpc#member.migrationCreate

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "jsonrpc": "2.0",
  • "method": "contract.call",
  • "id": 1,
  • "params":
    {
    }
}

Response samples

Content type
application/json
Example
Copy
Expand all Collapse all
{
  • "jsonrpc": "2.0",
  • "id": 1,
  • "result":
    {
    }
}

deposit.transfer

Transfers an amount of released XNS coin fractions from the member's deposit to the member's account.

To invoke this method, specify the following parameters:

  • in callParams, ethTxHash — deposit identifier;
  • in params, member reference to identify the account. This reference is returned by member.create;
  • in params, amount of XNS coin fractions to transfer.
header Parameters
Digest
required
string^SHA-256=.+$
Example: SHA-256=<hashString>

Digest HTTP header with an SHA-256 hash of the request's payload bytes in a Base64 <hashString>.

Signature
required
string
Example: keyId="member-pub-key", algorithm="ecdsa", headers="digest", signature=<signatureString>

Signature HTTP header with the signed hash bytes in a Base64 <signatureString>.

The signature is:

  • in ASN.1 DER format;
  • generated by an ECDSA private key;
  • checked by the paired public key (publicKey).
Request Body schema: application/json
jsonrpc
required
string
Value: "2.0"
id
required
string or number

Request's ID to link it with the corresponding result.

method
required
string
Value: "contract.call"

Name of the method to invoke.

params
required
object

Parameter values to pass to the invoked method.

Responses

200

OK

Response Schema: application/json
One of
  • Success
  • Errors
jsonrpc
required
string
Value: "2.0"
id
required
string or number

ID passed by the request.

result
required
object

Execution result of the invoked method.

post /api/rpc#deposit.transfer

Production server

https://wallet-api.insolar.io/api/rpc#deposit.transfer

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "jsonrpc": "2.0",
  • "id": 1,
  • "method": "contract.call",
  • "params":
    {
    }
}

Response samples

Content type
application/json
Example
Copy
Expand all Collapse all
{
  • "jsonrpc": "2.0",
  • "id": 1,
  • "result":
    {
    }
}