Insolar API (v1.1.2)

Download OpenAPI specification:Download

MainNet API documentation

Welcome to Insolar documentation for the MainNet JSON RPC 2.0 API.

The API allows to manage members (Insolar users) and their transactions.

Definitions Overview

Insolar is being developed to provide interoperability 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. The seed:

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

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

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

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

    For example, the getSeed request:

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

    And the response to it:

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

    Every contract request must 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. For example:

    {
      "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-encoded <hashString> with the SHA-256 hash of the payload's bytes.

    • Signature HTTP header contains the Base64-encoded <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-encoded 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 method.

    • callSite is the contract method call point. In this case, member.create.

    • callParams are the contract method 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 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 MainNet 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 MainNet error.
-31106 Request timeout has expired.
-31401 Action is not authorized.
-31429 Service unavailable, try again later.
-31103 Execution error.

Versioning

API changes in particular Insolar releases and uses the SemVer 2.0 versioning system.

API versions do not have to tally with Insolar MainNet 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 and:

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

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

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

Request ID to link the request 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

post /api/rpc#node.getSeed

MainNet

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

TestNet

https://wallet-api.testnet.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 a SHA-256 hash of the request's payload bytes in a Base64-encoded <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-encoded <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 ID to link the request 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

post /api/rpc#member.create

MainNet

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

TestNet

https://wallet-api.testnet.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 on 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 a SHA-256 hash of the request's payload bytes in a Base64-encoded <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-encoded <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 ID to link the request 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

post /api/rpc#member.get

MainNet

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

TestNet

https://wallet-api.testnet.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 XNS coin fractions from.
  • in callParams: the toMemberReference to transfer XNS coin fractions to.
  • in params: the amount of XNS coin fractions to transfer.

Returns the fee value.

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

Digest HTTP header with a SHA-256 hash of the request's payload bytes in a Base64-encoded <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-encoded <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 ID to link the request 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

post /api/rpc#member.transfer

MainNet

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

TestNet

https://wallet-api.testnet.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 a SHA-256 hash of the request's payload bytes in a Base64-encoded <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-encoded <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 ID to link the request 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

post /api/rpc#member.migrationCreate

MainNet

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

TestNet

https://wallet-api.testnet.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 current 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 a SHA-256 hash of the request's payload bytes in a Base64-encoded <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-encoded <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 ID to link the request 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

post /api/rpc#deposit.transfer

MainNet

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

TestNet

https://wallet-api.testnet.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":
    {
    }
}