Skip to main content

HTTP Methods

Koii nodes accept HTTP requests using the JSON-RPC 2.0 specification.

info

For JavaScript applications, use the @_koi/web3.js library as a convenient interface for the RPC methods to interact with a Koii node.

RPC HTTP Endpoint​

Default port: 10899

Request Formatting​

To make a JSON-RPC request, send an HTTP POST request with a Content-Type: application/json header. The JSON request data should contain 4 fields:

  • jsonrpc: <string> - set to "2.0"
  • id: <number> - a unique client-generated identifying integer
  • method: <string> - a string containing the method to be invoked
  • params: <array> - a JSON array of ordered parameter values

Example using curl:

curl https://testnet.koii.network -X POST -H "Content-Type: application/json" -d '
  {
    "jsonrpc": "2.0",
    "id": 1,
    "method": "getBalance",
    "params": [
      "83astBRguLMdt2h5U1Tpdq5tjFoJ6noeGwaY3mDLVcri"
    ]
  }
'

The response output will be a JSON object with the following fields:

  • jsonrpc: <string> - matching the request specification
  • id: <number> - matching the request identifier
  • result: <array|number|object|string> - requested data or success confirmation

Requests can be sent in batches by sending an array of JSON-RPC request objects as the data for a single POST.

Example Request​

The commitment parameter should be included as the last element in the params array:

curl https://testnet.koii.network -X POST -H "Content-Type: application/json" -d '
  {
    "jsonrpc": "2.0",
    "id": 1,
    "method": "getBalance",
    "params": [
      "83astBRguLMdt2h5U1Tpdq5tjFoJ6noeGwaY3mDLVcri",
      {
        "commitment": "finalized"
      }
    ]
  }
'

Definitions​

  • Hash: A SHA-256 hash of a chunk of data.
  • Pubkey: The public key of a Ed25519 key-pair.
  • Transaction: A list of Koii instructions signed by a client keypair to authorize those actions.
  • Signature: An Ed25519 signature of transaction's payload data including instructions. This can be used to identify transactions.

Health Check​

Although not a JSON RPC API, a GET /health at the RPC HTTP Endpoint provides a health-check mechanism for use by load balancers or other network infrastructure. This request will always return a HTTP 200 OK response with a body of "ok", "behind" or "unknown":

  • ok: The node is within HEALTH_CHECK_SLOT_DISTANCE slots from the latest cluster confirmed slot
  • behind { distance }: The node is behind distance slots from the latest cluster confirmed slot where distance > HEALTH_CHECK_SLOT_DISTANCE
  • unknown: The node is unable to determine where it stands in relation to the cluster