API Reference for the Kaleido REST API Gateway (1.0)

Download OpenAPI specification:Download

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

Smart Contract REST APIs

Friendly and intuitive REST APIs generated for your smart contracts

Kaleido REST API Gateway (ethconnect) archtecture

    • 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