Insolar Observer API (1.0.7)

Download OpenAPI specification:Download

Insolar's REST-like API documentation for the observer service.

Observer is a fast report service that pulls the data from Insolar MainNet and offloads read requests from it.

Additionally, Observer provides coin statistics and notification messages.

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.

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 some /api/<endpoint> is the same as calling /v1.0.0/api/<endpoint>.

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.

Member

member

Gets the following information on a member object:

  • (required) member's reference, accountReference, and walletReference;
  • (required) account's balance;
  • (optional) array of details on all deposits associated with the member (if any);
  • (optional) migrationAddress during the migration period.

To invoke this request, specify the member reference (or the corresponding migrationAddress).

path Parameters
reference
required
string^insolar:[A-z0-9_-]+$
Example: insolar%3A1GlDeBOnc7Ar5N34ShBdkx_SAVOfnZJKUCoQMi0_OcvE

Reference to the member object (or the corresponding migrationAddress).

Note: since path parameters must be valid parts of URL, the : after insolar in references is to be replaced with %3A in accordance with the HTML URL encoding.

Responses

200

OK

Response Schema: application/json
reference
required
string^insolar:[A-z0-9_-]+$

Reference to the member object.

balance
required
string

Account's balance in XNS coin fractions — a whole number. The smallest fraction of XNS is 1/10^10. To calculate XNS, divide the number of fractions by 10^10. For example: 1000000000 fractions / 10^10 = 0.1 XNS.

walletReference
required
string^insolar:[A-z0-9_-]+$

Reference to the member's wallet object.

accountReference
required
string^insolar:[A-z0-9_-]+$

Reference to the member's account object.

deposits
Array of objects (deposit)

Deposits associated with the member.

migrationAddress
string

Special address in the Ethereum network — transfer destination for INS tokens during the migration period.

204

Reference not found

400

Invalid reference format

Response Schema: application/json
error
required
Array of strings

Array of error messages.

404

Endpoint not found

500

Internal server error

get /api/member/{reference}

Production server

https://wallet-api.insolar.io/api/member/{reference}

Response samples

Content type
application/json
Example
Copy
Expand all Collapse all
{
  • "balance": "1000000000000",
  • "reference": "insolar:1GlDeBOnc7Ar5N34ShBdkx_SAVOfnZJKUCoQMi0_OcvE",
  • "walletReference": "insolar:1AfNjPWh7Ut-P7Ky7Mj7HLCte3gjGXi4RpXNxTvrhlww",
  • "accountReference": "insolar:1LBBNgDpzKt0YGkrInkqGlsME4RAnSzQRIySreTX0j7g",
  • "deposits":
    [
    ]
}

member by public key

Gets the following information on a member object:

  • (required) member's reference, accountReference, and walletReference;
  • (required) account's balance;
  • (optional) array of details on all deposits associated with the member (if any);
  • (optional) migrationAddress during the migration period.

To invoke this request, specify the member's publicKey.

query Parameters
publicKey
required
string
Example: publicKey=-----BEGIN%20PUBLIC%20KEY-----MFYwEAYHKoZIzj0CAQYFK4EEAAoDQgAE9qmU2JVIlNPE%2FhGxuJnXprOyFIIL5fkcJlFOLMIQnNK8uPyFgexekQKFvyy3%2FdvPCEYoXOVi25CQ9t2UAj4v%2BQ%3D%3D-----END%20PUBLIC%20KEY-----

Public key of the target member object. With or without -----BEGIN PUBLIC KEY----- and -----END PUBLIC KEY----- delimiters.

Note: since query parameters must be valid parts of URL, the publicKey value should be URL-encoded.

Responses

200

OK

Response Schema: application/json
reference
required
string^insolar:[A-z0-9_-]+$

Reference to the member object.

balance
required
string

Account's balance in XNS coin fractions — a whole number. The smallest fraction of XNS is 1/10^10. To calculate XNS, divide the number of fractions by 10^10. For example: 1000000000 fractions / 10^10 = 0.1 XNS.

walletReference
required
string^insolar:[A-z0-9_-]+$

Reference to the member's wallet object.

accountReference
required
string^insolar:[A-z0-9_-]+$

Reference to the member's account object.

deposits
Array of objects (deposit)

Deposits associated with the member.

migrationAddress
string

Special address in the Ethereum network — transfer destination for INS tokens during the migration period.

204

Reference not found

400

Invalid reference format

Response Schema: application/json
error
required
Array of strings

Array of error messages.

404

Endpoint not found

500

Internal server error

get /api/member/byPublicKey

Production server

https://wallet-api.insolar.io/api/member/byPublicKey

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "reference": "insolar:1AfNjPWh7Ut-P7Ky7Mj7HLCte3gjGXi4RpXNxTvrhlww",
  • "balance": "1000000000",
  • "walletReference": "insolar:1AfNjPWh7Ut-P7Ky7Mj7HLCte3gjGXi4RpXNxTvrhlww",
  • "accountReference": "insolar:1LBBNgDpzKt0YGkrInkqGlsME4RAnSzQRIySreTX0j7g",
  • "deposits":
    [
    ],
  • "migrationAddress": "0xF4e1507486dFE411785B00d7D00A1f1a484f00E6"
}

member balance

Gets the balance of a member's account.

To invoke this request, specify the member reference.

path Parameters
reference
required
string^insolar:[A-z0-9_-]+$
Example: insolar%3A1GlDeBOnc7Ar5N34ShBdkx_SAVOfnZJKUCoQMi0_OcvE

Reference to the member object.

Note: since path parameters must be valid parts of URL, the : after insolar in references is to be replaced with %3A in accordance with the HTML URL encoding.

Responses

200

OK

Response Schema: application/json
balance
required
string

Member's balance in XNS coin fractions — a whole number. The smallest fraction of XNS is 1/10^10. To calculate XNS, divide the number of fractions by 10^10. For example: 1000000000 fractions / 10^10 = 0.1 XNS.

204

Reference not found

400

Invalid reference format

Response Schema: application/json
error
required
Array of strings

Array of error messages.

404

Endpoint not found

500

Internal server error

get /api/member/{reference}/balance

Production server

https://wallet-api.insolar.io/api/member/{reference}/balance

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "balance": "1000000000"
}

member transactions

Gets a list (page) of member's transactions.

To invoke this request, specify the member reference in path and parameters listed below.

Filters:

  • (optional) direction of transactions in the list — incoming, outgoing, or all.
  • (optional) type of transactions in the list.
  • (optional) status of transactions in the list.

Pagination parameters and chronological order:

  • (optional) order of the transaction list — chronological or reverse (default).
  • page size — (required) limit to the number of transactions to get.
  • (optional) index of the last known transaction to start the list from the next one.

Each returned transaction has an index which can be specified in the corresponding parameter in subsequent requests.

If the index parameter is not specified, the request returns a list of the most recent or old (depending on the order value) transactions.

path Parameters
reference
required
string^insolar:[A-z0-9_-]+$
Example: insolar%3A1GlDeBOnc7Ar5N34ShBdkx_SAVOfnZJKUCoQMi0_OcvE

Reference to the member object.

Note: since path parameters must be valid parts of URL, the : after insolar in references is to be replaced with %3A in accordance with the HTML URL encoding.

query Parameters
limit
required
integer [ 1 .. 1000 ]
Example: limit=100

Number of entries per list.

index
string
Example: index=38134090%3A7

Index of the last known transaction to start the list from the next one.

Each returned transaction has an index that can be specified as the value of this parameter.

To get the list of most recent or old (depending on the order value) transactions, omit the index.

direction
string
Default: "all"
Enum: "incoming" "outgoing" "all"
Example: direction=incoming

Transaction's direction:

  • incoming - transactions only to member,
  • outgoing - transactions only from member,
  • all - both to and from.
order
string
Default: "reverse"
Enum: "chronological" "reverse"

Chronological order of the transaction list starting from a given index:

  • chronological — get transactions that chronologically follow a transaction with a given index;
  • reverse — get transactions that chronologically preceed a transaction with a given index.
type
string
Enum: "transfer" "migration" "release"
Example: type=transfer

Transaction type:

  • transfer - transactions to/from to member,
  • migration - transactions only to member's deposits,
  • release - transactions only from member's deposits to member's account.
status
string
Enum: "registered" "sent" "received" "failed"
Example: status=received

Transaction status:

  • registered — transfer request is registered;
  • sent — transfer of funds from the sender is finalized;
  • received — transfer of funds to the receiver is finalized.
  • failed — transfer of funds is finalized with an error, e.g., in case of insufficient balance.

Responses

200

OK

Response Schema: application/json
Array
index
required
string

Transaction index.

txID
required
string

Transaction ID.

amount
required
string

Amount of XNS coin fractions — a whole number. The smallest fraction of XNS is 1/10^10. To calculate XNS, divide the number of fractions by 10^10. For example: 1000000000 fractions / 10^10 = 0.1 XNS.

fee
string

Fee value in XNS coin fractions. Only finalized transactions (with received status) have this value.

timestamp
required
integer <int64>

Timestamp of the initial transfer request in UNIX format.

status
required
string
Enum: "registered" "sent" "received" "failed"

Transaction status:

  • registered — transfer request is registered;
  • sent — transfer of funds from the sender is finalized;
  • received — transfer of funds to the receiver is finalized.
  • failed — transfer of funds is finalized with an error, e.g., in case of insufficient balance.
pulseNumber
required
integer <int64>

Pulse number at transaction timestamp.

type
required
string

Transaction type upon which all references depend.

toMemberReference
required
string Nullable ^insolar:[A-z0-9_-]+$

Reference to the receiving member object.

fromMemberReference
required
string^insolar:[A-z0-9_-]+$

Reference to the sending member object.

204

Reference not found

400

Invalid parameter(s) format

Response Schema: application/json
error
required
Array of strings

Array of error messages.

404

Endpoint not found

500

Internal server error

get /api/member/{reference}/transactions

Production server

https://wallet-api.insolar.io/api/member/{reference}/transactions

Response samples

Content type
application/json
Example
Copy
Expand all Collapse all
[
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

Transaction

closed transactions

Gets a list (page) of closed transactions (only with received and failed statuses) observed in the Insolar network.

To invoke this request, specify:

  • page size — (required) limit to the number of transactions to get.
  • (optional) index of the last known transaction to start the list from the next one.
  • (optional) order of the transaction list — chronological or reverse (default).

Note: Indexes in the list of closed transactions do not match the indexes in the lists returned by member transactions, transactions, and transactions in pulse range.

Each returned transaction has an index which can be specified in the corresponding parameter in subsequent requests for closed transactions.

If the index parameter is not specified, the request returns a list of the most recent or old (depending on the order value) transactions.

query Parameters
limit
required
integer [ 1 .. 1000 ]
Example: limit=100

Number of entries per list.

index
string
Example: index=38134090%3A7

Index of the last known transaction to start the list from the next one.

Each returned transaction has an index that can be specified as the value of this parameter.

To get the list of most recent or old (depending on the order value) transactions, omit the index.

order
string
Default: "reverse"
Enum: "chronological" "reverse"

Chronological order of the transaction list starting from a given index:

  • chronological — get transactions that chronologically follow a transaction with a given index;
  • reverse — get transactions that chronologically precede a transaction with a given index.

Responses

200

OK

Response Schema: application/json
Array
index
required
string

Transaction index.

txID
required
string

Transaction ID.

amount
required
string

Amount of XNS coin fractions — a whole number. The smallest fraction of XNS is 1/10^10. To calculate XNS, divide the number of fractions by 10^10. For example: 1000000000 fractions / 10^10 = 0.1 XNS.

fee
string

Fee value in XNS coin fractions. Only finalized transactions (with received status) have this value.

timestamp
required
integer <int64>

Timestamp of the initial transfer request in UNIX format.

status
required
string
Enum: "registered"