Download OpenAPI specification:Download
Welcome to Insolar documentation for the MainNet JSON RPC 2.0 API.
The API allows to manage members (Insolar users) and their transactions.
Insolar is being developed to provide interoperability between enterprises.
From a business perspective:
From a technical perspective:
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.
Insolar has two types of requests that have the same base structure in accordance with the JSON RPC 2.0 specification:
Seed is a unique piece of information generated by a node. The seed:
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:
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>"
}
}
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.
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"
.
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. |
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.
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:
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.
jsonrpc required | |
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. |
OK
MainNet
TestNet
{- "jsonrpc": "2.0",
- "method": "node.getSeed",
- "id": 1
}
{- "jsonrpc": "2.0",
- "id": 1,
- "result": {
- "seed": "U1wGm8xl+WUFIPFLdFupTXKMXbLoJbv0nA/ImZAtHZk="
}
}
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.
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 |
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 The signature is:
|
jsonrpc required | |
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. |
OK
MainNet
TestNet
{- "jsonrpc": "2.0",
- "method": "contract.call",
- "id": 1,
- "params": {
- "seed": "fhDEwRRbSnYnbMnALKMh8gXdzaSvRv/nfsGC9S7kqik=",
- "callSite": "member.create",
- "publicKey": "-----BEGIN PUBLIC KEY-----\\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEMSbA4KvO/jlwY+8WFDEdwhCLlsEC\\nF3/GYvu9iTWHwCctx1wTbGGjNLY03EjXyYxaf8coNbSbZeu+jXcWeMHG0A==\\n-----END PUBLIC KEY-----"
}
}
{- "jsonrpc": "2.0",
- "id": 1,
- "result": {
- "callResult": {
- "reference": "insolar:1GlDeBOnc7Ar5N34ShBdkx_SAVOfnZJKUCoQMi0_OcvE"
}, - "requestReference"": "insolar:1FUpUFSfNpmyX05nustQ7B8al0xj-_j3_ndqXfgLRra4.record",
- "traceID": "0b9ac245-2522-4364-9059-efc17907ce54"
}
}
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:
reference
to the member object,migrationAddress
, if any; only during the period of token migration from the Ethereum network.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 |
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 The signature is:
|
jsonrpc required | |
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. |
OK
MainNet
TestNet
{- "jsonrpc": "2.0",
- "method": "contract.call",
- "id": 1,
- "params": {
- "seed": "fhDEwRRbSnYnbMnALKMh8gXdzaSvRv/nfsGC9S7kqik=",
- "callSite": "member.get",
- "publicKey": "-----BEGIN PUBLIC KEY-----\\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEMSbA4KvO/jlwY+8WFDEdwhCLlsEC\\nF3/GYvu9iTWHwCctx1wTbGGjNLY03EjXyYxaf8coNbSbZeu+jXcWeMHG0A==\\n-----END PUBLIC KEY-----"
}
}
{- "jsonrpc": "2.0",
- "id": 1,
- "result": {
- "callResult": {
- "reference": "insolar:1GlDeBOnc7Ar5N34ShBdkx_SAVOfnZJKUCoQMi0_OcvE",
- "migrationAddress": "0xF4e1507486dFE411785B00d7D00A1f1a484f00E6"
}, - "requestReference": "insolar:1FUpUFSfNpmyX05nustQ7B8al0xj-_j3_ndqXfgLRra4.record",
- "traceID": "0b9ac245-2522-4364-9059-efc17907ce54"
}
}
Transfers an amount
of XNS coin fractions from some member's account to another.
To invoke this method, specify the following parameters:
params
: the member reference
(returned by member.create) to transfer XNS coin fractions from.callParams
: the toMemberReference
to transfer XNS coin fractions to.params
: the amount
of XNS coin fractions to transfer.Returns the fee value.
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 |
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 The signature is:
|
jsonrpc required | |
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. |
OK
MainNet
TestNet
{- "jsonrpc": "2.0",
- "id": 1,
- "method": "contract.call",
- "params": {
- "seed": "U1wGm8xl+WUFIPFLdFupTXKMXbLoJbv0nA/ImZAtHZk=",
- "callSite": "member.transfer",
- "callParams": {
- "amount": "1000000000",
- "toMemberReference": "insolar:1AfNjPWh7Ut-P7Ky7Mj7HLCte3gjGXi4RpXNxTvrhlww"
}, - "publicKey": "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEMSbA4KvO/jlwY+8WFDEdwhCLlsEC\nF3/GYvu9iTWHwCctx1wTbGGjNLY03EjXyYxaf8coNbSbZeu+jXcWeMHG0A==\n-----END PUBLIC KEY-----",
- "reference": "insolar:1GlDeBOnc7Ar5N34ShBdkx_SAVOfnZJKUCoQMi0_OcvE"
}
}
{- "jsonrpc": "2.0",
- "id": "1",
- "result": {
- "callResult": {
- "fee": "10"
}, - "requestReference": "insolar:1FUpUFSfNpmyX05nustQ7B8al0xj-_j3_ndqXfgLRra4.record",
- "traceID": "0b9ac245-2522-4364-9059-efc17907ce54"
}
}
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,migrationAddress
; only during the period of token migration from the Ethereum network.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 |
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 The signature is:
|
jsonrpc required | |
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. |
OK
MainNet
TestNet
{- "jsonrpc": "2.0",
- "method": "contract.call",
- "id": 1,
- "params": {
- "seed": "fhDEwRRbSnYnbMnALKMh8gXdzaSvRv/nfsGC9S7kqik=",
- "callSite": "member.migrationCreate",
- "publicKey": "-----BEGIN PUBLIC KEY-----\\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEMSbA4KvO/jlwY+8WFDEdwhCLlsEC\\nF3/GYvu9iTWHwCctx1wTbGGjNLY03EjXyYxaf8coNbSbZeu+jXcWeMHG0A==\\n-----END PUBLIC KEY-----"
}
}
{- "jsonrpc": "2.0",
- "id": 1,
- "result": {
- "callResult": {
- "reference": "insolar:1GlDeBOnc7Ar5N34ShBdkx_SAVOfnZJKUCoQMi0_OcvE",
- "migrationAddress": "0x12eB9bce34341D1163814843f8DcA44DFebe913c"
}, - "requestReference": "insolar:1FUpUFSfNpmyX05nustQ7B8al0xj-_j3_ndqXfgLRra4.record",
- "traceID": "0b9ac245-2522-4364-9059-efc17907ce54"
}
}
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:
callParams
: ethTxHash
—deposit identifier.params
: member reference
to identify the account; this reference is returned by member.create.params
: amount
of XNS coin fractions to transfer.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 |
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 The signature is:
|
jsonrpc required | |
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. |
OK
MainNet
TestNet
{- "jsonrpc": "2.0",
- "id": 1,
- "method": "contract.call",
- "params": {
- "seed": "U1wGm8xl+WUFIPFLdFupTXKMXbLoJbv0nA/ImZAtHZk=",
- "callSite": "deposit.transfer",
- "callParams": {
- "amount": "1000000000",
- "ethTxHash": "0x21145195deb606bd75eab41a7afe38d7c3ae60a091cadc201f0ba489cbec8f09"
}, - "publicKey": "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEMSbA4KvO/jlwY+8WFDEdwhCLlsEC\nF3/GYvu9iTWHwCctx1wTbGGjNLY03EjXyYxaf8coNbSbZeu+jXcWeMHG0A==\n-----END PUBLIC KEY-----",
- "reference": "insolar:1GlDeBOnc7Ar5N34ShBdkx_SAVOfnZJKUCoQMi0_OcvE"
}
}
{- "jsonrpc": "2.0",
- "id": 1,
- "result": {
- "callResult": { },
- "requestReference": "insolar:1FUpUFSfNpmyX05nustQ7B8al0xj-_j3_ndqXfgLRra4.record",
- "traceID": "0b9ac245-2522-4364-9059-efc17907ce54"
}
}