Kaleido Logo
Documentation Powered by Redocly

API Reference for the Kaleido REST API Gateway (1.0)

Download OpenAPI specification:Download

URL: https://api.kaleido.io

Enterprise Grade Connectivity for your Applications

  • Deploy your first Smart Contract in seconds
  • REST APIs for your on-chain Logic & Data
  • Deploy and Manage Smart Contracts
  • OpenAPI Docs and API Exerciser built-in
  • Reliable Transaction Streaming (over Kafka)
  • Reliable Event Streams
Kaleido REST API Gateway (ethconnect) archtecture

Smart Contract REST APIs

Friendly and intuitive REST APIs generated for your smart contracts

    • Generated directly from your Solidity source code and devdocs
    • Simple JSON types
    • Familiar REST semantics
    • OpenAPI 2.0 (Swagger) compliant definitions
    • Built-in UI exerciser
    • Factory APIs to deploy contract instances
    • Instance APIs to query and transact with any deployed contract
    • Subscription APIs to deliver events reliably to Event Streams
    • Automated Gas estimation
  • Synchronous mode
    • Query on-chain data, returning simple JSON types
    • Simulate transactions
    • Submit transactions with blocking calls (just like web3 APIs)
  • Asynchronous mode
    • Reliably stream transactions onto the chain
    • Pre-built infrastructure that is required for production blockchain workloads at scale
    • Also ideal for webhooks - fire and forget
    • Optimized throughput, smoothing peaks in workload to avoid flooding blocks
    • Nonce management
    • Backed by a fully-managed reliable Kafka messaging backbone
    • Receipt store for transaction results
  • Private transaction support
    • Tessera (previously Constellation) - from the Quorum project
    • Orion (sister project to Hyperledger Besu) - from PegaSys engineering
  • High-performance gateway runtime
    • Written in Golang using optimized Ethereum libraries for ABI packing/unpacking
    • Colocated with the Ethereum node
    • Architected for both horizonal scale and ordered delivery
    • Core made available as Apache 2.0 open source in the ethconnect project

Webhook for async transactions

Send a simple JSON or YAML payload that can:

  • Compile and deploy contracts from in-line Solidity source code
  • Deploy contracts from bytecode
  • Asynchronously deliver transactions to your ethereum node over our Kafka backbone
  • Invoke solidity transactions without needing to first install an ABI

You get a response immediately, including an id that you can query for results in the receipt store later.

The same reliable transport as is used on POST methods of the installed REST Gateway generated interfaces (installed via the /abis paths), when kld-sync is unset.

Ideal for use as a webhook endpoint for an integration tool that can emit sevents over HTTPS. Also useful if your application wants to construct the full details for the transaction to sent to a contract, or install a new contract, without first teaching the REST API Gateway about the Solidity interface (ABI).

There are two variations of the webhook:

  • Fire & forget on / and /fasthook: responds as soon as the message is sent to the Kafka client library
  • Kafka acknowledged on /hook: responds only once Kafka has acknowledged receipt of the message

Request Body schema:
required
object

Headers section used in requests, and extended in asynchronous response messages

from
required
string^(0x)?[0-9a-zA-Z]{40}$

The address to use when signing the transaction. Must be a wallet managed by Kaleido. For example account[0] on the node.

to
string^(0x)?[0-9a-zA-Z]{40}$

SendTransaction only: The contract address to send the transaction too.

methodName
string

SendTransaction only: The method name to invoke on the target contract.

Array of objects

The parameters to pass to the ethereum method or constructor.

soldity
string

DeployContract only: Soldity source code to compile.

contractName
string

DeployContract only: When there are multiple contracts in the compiler output, this field is required to select the contract to deploy.

compilerVersion
string
Default: "0.4"

DeployContract only: solc compiler version to use. Only the major version is used in the supplied semver, such as 0.4 or 0.5.

compiled
string <byte>

DeployContract only: Pre-compiled base64 encoded byecode - alternative to supplying Solidity code for compilation.

gas
string

The maximum gas the transaction can consume - omit to allow ethconnect to perform a gas estimation

gasPrice
string

The ETH price offered for gas - omit to use a gas price of zero

value
string

An optional ETH value to send along with the tranaction

nonce
string^[0-9]+$

Assign an explicit nonce to the transaction - omit to allow ethconnect to manage the nonce

privateFrom
string

EEA privacy extensions privateFrom address for private transaction support (Quorum Tessera / PegaSys Orion)

privateFor
Array of strings

EEA privacy extensions privateFor addresses for private transaction support (Quorum Tessera / PegaSys Orion)

Responses

Request samples

Content type
{
  • "headers": {
    },
  • "from": "string",
  • "to": "string",
  • "methodName": "string",
  • "params": [
    ],
  • "soldity": "string",
  • "contractName": "string",
  • "compilerVersion": "0.4",
  • "compiled": "string",
  • "gas": "string",
  • "gasPrice": "string",
  • "value": "string",
  • "nonce": "string",
  • "privateFrom": "string",
  • "privateFor": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "sent": true,
  • "msg": "string"
}

Fire & forget webhook

Responds as soon as the message is passed to the Kafka client library.

Request Body schema:
required
object

Headers section used in requests, and extended in asynchronous response messages

from
required
string^(0x)?[0-9a-zA-Z]{40}$

The address to use when signing the transaction. Must be a wallet managed by Kaleido. For example account[0] on the node.

to
string^(0x)?[0-9a-zA-Z]{40}$

SendTransaction only: The contract address to send the transaction too.

methodName
string

SendTransaction only: The method name to invoke on the target contract.

Array of objects

The parameters to pass to the ethereum method or constructor.

soldity
string

DeployContract only: Soldity source code to compile.

contractName
string

DeployContract only: When there are multiple contracts in the compiler output, this field is required to select the contract to deploy.

compilerVersion
string
Default: "0.4"

DeployContract only: solc compiler version to use. Only the major version is used in the supplied semver, such as 0.4 or 0.5.

compiled
string <byte>

DeployContract only: Pre-compiled base64 encoded byecode - alternative to supplying Solidity code for compilation.

gas
string

The maximum gas the transaction can consume - omit to allow ethconnect to perform a gas estimation

gasPrice
string

The ETH price offered for gas - omit to use a gas price of zero

value
string

An optional ETH value to send along with the tranaction

nonce
string^[0-9]+$

Assign an explicit nonce to the transaction - omit to allow ethconnect to manage the nonce

privateFrom
string

EEA privacy extensions privateFrom address for private transaction support (Quorum Tessera / PegaSys Orion)

privateFor
Array of strings

EEA privacy extensions privateFor addresses for private transaction support (Quorum Tessera / PegaSys Orion)

Responses

Request samples

Content type
{
  • "headers": {
    },
  • "from": "string",
  • "to": "string",
  • "methodName": "string",
  • "params": [
    ],
  • "soldity": "string",
  • "contractName": "string",
  • "compilerVersion": "0.4",
  • "compiled": "string",
  • "gas": "string",
  • "gasPrice": "string",
  • "value": "string",
  • "nonce": "string",
  • "privateFrom": "string",
  • "privateFor": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "sent": true
}

Kafka acknowledged webhook

Waits for an acknowledgment from Kafka that the message has been delivered to a topic partition before responding.
Recommended when reliable transaction delivery is required.

Request Body schema:
required
object

Headers section used in requests, and extended in asynchronous response messages

from
required
string^(0x)?[0-9a-zA-Z]{40}$

The address to use when signing the transaction. Must be a wallet managed by Kaleido. For example account[0] on the node.

to
string^(0x)?[0-9a-zA-Z]{40}$

SendTransaction only: The contract address to send the transaction too.

methodName
string

SendTransaction only: The method name to invoke on the target contract.

Array of objects

The parameters to pass to the ethereum method or constructor.

soldity
string

DeployContract only: Soldity source code to compile.

contractName
string

DeployContract only: When there are multiple contracts in the compiler output, this field is required to select the contract to deploy.

compilerVersion
string
Default: "0.4"

DeployContract only: solc compiler version to use. Only the major version is used in the supplied semver, such as 0.4 or 0.5.

compiled
string <byte>

DeployContract only: Pre-compiled base64 encoded byecode - alternative to supplying Solidity code for compilation.

gas
string

The maximum gas the transaction can consume - omit to allow ethconnect to perform a gas estimation

gasPrice
string

The ETH price offered for gas - omit to use a gas price of zero

value
string

An optional ETH value to send along with the tranaction

nonce
string^[0-9]+$

Assign an explicit nonce to the transaction - omit to allow ethconnect to manage the nonce

privateFrom
string

EEA privacy extensions privateFrom address for private transaction support (Quorum Tessera / PegaSys Orion)

privateFor
Array of strings

EEA privacy extensions privateFor addresses for private transaction support (Quorum Tessera / PegaSys Orion)

Responses

Request samples

Content type
{
  • "headers": {
    },
  • "from": "string",
  • "to": "string",
  • "methodName": "string",
  • "params": [
    ],
  • "soldity": "string",
  • "contractName": "string",
  • "compilerVersion": "0.4",
  • "compiled": "string",
  • "gas": "string",
  • "gasPrice": "string",
  • "value": "string",
  • "nonce": "string",
  • "privateFrom": "string",
  • "privateFor": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "sent": true,
  • "msg": "string"
}

Add new contract REST API

Compiles the supplied Solidity source code into an ABI (and devdocs) from a single file or zip/tarball, then builds a new REST API that can then be used:

  • To query data from any existing contract deployed on-chain
  • As a factory to deploy contract instances on-chain
  • To subscribe for events matching the signatures defined in the Solidity source code
  • To install a friendly named API onto this node that binds a friendly API to an individual smart contract

As there are a number of functions performed by the installed REST API, and the paths are all bespoke to the methods in the Solidity itself, the installed API comes with its own OpenAPI 2.0 (Swagger) definition.

A link to the generated API definition is included in the response payload.

As the primary input is file data the Content-Type for the payload on route is multipart/form-data, rather than JSON.

Request Body schema: multipart/form-data
findsolidity
string

Discovery mode: If set then the response will be an array of Solidity files found in the supplied files, rather than attempting the compilation (can also be set as a URL query parameter)

findcontracts
string

Discovery mode: If set then the response will be an array of contract names returned by solc in the compiled output, rather than attempting to install the REST API (can also be set as a URL query parameter)

source
string

If a zip/tarball is supplied containing multiple solidity files, this field is required to set the Solidity source code file to compile (can also be set as a URL query parameter). Use findsolidity to find possible values.

contract
string

If the compilation results in multipel contracts, this field is required to set the contract name to use when deploying contracts via the factory methods (can also be set as a URL query parameter). Use findcontracts to find possible values.

*
string <binary>

Any other properties should be file-content: .sol .zip .tar .tgz .tar.gz .tar.bz2 files are supported

Responses

Response samples

Content type
application/json
{
  • "created": "2019-08-24T14:15:22Z",
  • "id": "string",
  • "description": "string",
  • "path": "string",
  • "deployable": true,
  • "openapi": true,
  • "compilerVersion": true
}

List contract REST APIs

List the previously installed ABI definitions with available factory, query & event-subscription REST APIs

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get contract REST API

List details of a single previously installed ABI definitions with a factory, query & event-subscription REST API

path Parameters
abi_id
required
string

The ID of the install ABI

Responses

Response samples

Content type
application/json
{
  • "created": "2019-08-24T14:15:22Z",
  • "id": "string",
  • "description": "string",
  • "path": "string",
  • "deployable": true,
  • "openapi": true,
  • "compilerVersion": true
}

List contract instance APIs

List the previously installed ABI definitions with available REST APIs

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get contract instance API

List the previously installed ABI definitions with available REST APIs

path Parameters
contract_address_or_friendly_name
required
string

The ID of the install ABI

Responses

Response samples

Content type
application/json
{
  • "created": "2019-08-24T14:15:22Z",
  • "id": "string",
  • "description": "string",
  • "path": "string",
  • "deployable": true,
  • "openapi": true,
  • "compilerVersion": true
}

Event Streams

Reliably initiate apps and business processes from on-chain events, and sync data to an off-chain cache

Kaleido Event Streams

  • Intuitive REST API to subscribe to simple JSON events
    • Subscribe to events by name - no need to understand Ethereum 'topic' hashes
    • Subscribe to all events with a particular signature
    • Subscribe to events on individual constract instances
    • Delivered as a simple JSON array of events, with JSON types
    • Delivery over Webhooks (HTTPS) with support for custom authentication headers
  • At-least once delivery of events
    • Check-point restart based on block-number to restart streams after restarting a node
    • Exponential back-off retry of delivery for intermittent connectivity issues
    • Efficient blocking retry for longer periods of application downtime
  • High performance batched delivery
    • Batching of events for delivery to an analytics stream, or efficient insert into a database
    • No complexity required in the application itself
  • Webhooks ideal for serverless functions
    • AWS Lambda functions
    • Microsoft Azure functions
  • Websocket connection also available
    • Useful for services with no external facing HTTP server
    • Longer lived, reusable connections
    • Subscribe to specific topics to let apps handle different flows

Add Event Stream

Add a new event stream, to which subscriptions can deliver messages

Request Body schema: application/json
type
string
Enum: "webhook" "websocket"

The type of event stream

batchSize
integer [ 1 .. 1000 ]
Default: 1

The number of events to attempt to batch together before delivery

batchTimeoutMS
integer >= 0
Default: 5000

The number of milliseoconds to wait to fill the batchSize before delivery

retryTimeoutSec
integer >= 0
Default: 0

Amount of time to perform exponential backoff retry for if the endpoint is unable to process a message, before either failing the batch, or entrying blocked state (0 means no backoff retry)

errorHandling
string
Enum: "block" "skip"

Error handling mode defines whether to discard events and move onto the next batch if they cannot be processed after the retryTimeoutSec configured retry interval, or enter a blocked state retrying the batch indefinitely

blockedReryDelaySec
integer
Default: 30

If configured to block indefinitely to deliver events, this is the long retry that comes into effect after any exponential backoff retry period

object

Configuration options specific to type 'webhook'

object

Configuration options specific to type websocket

Responses

Request samples

Content type
application/json
Example
{
  • "type": "webhook",
  • "batchSize": 1,
  • "batchTimeoutMS": 5000,
  • "retryTimeoutSec": 0,
  • "errorHandling": "block",
  • "blockedReryDelaySec": 30,
  • "webhook": {
    }
}

Response samples

Content type
application/json
Example
{
  • "type": "webhook",
  • "batchSize": 1,
  • "batchTimeoutMS": 5000,
  • "retryTimeoutSec": 0,
  • "errorHandling": "block",
  • "blockedReryDelaySec": 30,
  • "webhook": {
    },
  • "created": "2021-04-29T17:40:29.190Z",
  • "id": "string",
  • "path": "string",
  • "suspended": true
}

List Event Streams

Returns a list of all event streams registered on this node

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Event Stream

Get the details of an individual event stream

path Parameters
stream_id
required
string

The ID of the Event Stream

Responses

Response samples

Content type
application/json
{
  • "type": "webhook",
  • "batchSize": 1,
  • "batchTimeoutMS": 5000,
  • "retryTimeoutSec": 0,
  • "errorHandling": "block",
  • "blockedReryDelaySec": 30,
  • "webhook": {
    },
  • "websocket": {
    },
  • "created": "2019-08-24T14:15:22Z",
  • "id": "string",
  • "path": "string",
  • "suspended": true
}

Update Event Stream

Update the details of an individual event stream

path Parameters
stream_id
required
string

The ID of the Event Stream

Responses

Response samples

Content type
application/json
{
  • "type": "webhook",
  • "batchSize": 1,
  • "batchTimeoutMS": 5000,
  • "retryTimeoutSec": 0,
  • "errorHandling": "block",
  • "blockedReryDelaySec": 30,
  • "webhook": {
    },
  • "websocket": {
    },
  • "created": "2019-08-24T14:15:22Z",
  • "id": "string",
  • "path": "string",
  • "suspended": true
}

Delete Event Stream

Delete an event stream, and any registered subscriptions

path Parameters
stream_id
required
string

The ID of the Event Stream

Responses

Suspend a stream

Stops event delivery on an Event Stream, while retaining state of the events delivered so far

path Parameters
stream_id
required
string

The ID of the Event Stream

Responses

Resume a stream

Resumes delivery on an Event Stream that was previously suspended

path Parameters
stream_id
required
string

The ID of the Event Stream

Responses

List Subscriptions

Returns a list of all subscriptions registered on this node

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Subscription

Returns details of an individual subscription

path Parameters
subscription_id
required
string

The ID of the Subscription

Responses

Response samples

Content type
application/json
{
  • "stream": "string",
  • "fromBlock": "string",
  • "created": "2019-08-24T14:15:22Z",
  • "id": "string",
  • "path": "string",
  • "name": "string",
  • "filter": { },
  • "event": { }
}

Delete Subscription

Deletas a subscription

path Parameters
subscription_id
required
string

The ID of the Subscription

Responses