Kwil v2

Quickstart Guide


To use Kwil, we will need to lock up some tokens in an escrow smart contract. Right now, the Kwil testnet is programmed to accept a test ERC20 deployed on the Goerli testnet. In the future, dApp developers will be able to choose the token that they use to pay for their usage.
In order to start using Kwil, you will need 3 things:
  1. 1.
    An Ethereum wallet.
  2. 2.
    A small amount of gETH (faucet).
  3. 3.
    Some Kwil Test Tokens (faucet).


To access Kwil, you will need to use a Kwil Endpoint:
Where to use
Kwil Provider
Kwil SDK
GRPC Provider
Kwil CLI

Javascript/Typescript SDK

The quickest way to begin using Kwil is with our Javascript/Typescript SDK. The SDK can be installed by running:
npm i kwil


To initialize Kwil, you need to create a new Kwil object, as well as either a wallet or provider


const { ethers } = require('ethers');
const kwiljs = require('kwil');
// instead of a provider, nodeJS requires a wallet
const wallet = new ethers.Wallet("my_ethereum_private_key")
// create a new Kwil web client
const kwil = new kwiljs.NodeKwil({
kwilProvider: "kwil_provider_endpoint",


import { ethers } from 'ethers';
import kwiljs from 'kwil';
// prompt metamask to connect
const provider = new ethers.providers.Web3Provider(window.ethereum)
await provider._ready()
await ethereum.request({ method: 'eth_requestAccounts' });
// create a new Kwil web client
const kwil = new kwiljs.WebKwil({
kwilProvider: "kwil_provider_endpoint",
kwil_provider_endpoint can be found here.

Funding and Payment

Payment to the Kwil network occurs through deposit contracts that exist on other chains. Right now, a testnet contract using testnet tokens is deployed to Ethereum's Goerli Testnet. The SDK will automatically retrieve the necessary smart contract and token information from your Kwil RPC provider.
Since Kwil is built to handle any number of tokens, the tooling does not currently handle token decimals. Values passed to the SDK need to use the integer representation of an ERC20 amount. Read more on ERC20 decimals here.
// get funder
const funder = await kwil.getFunder(ethereum_signer);
// approve funds
const approve = await funder.approve(ethers.BigNumber.from("1000000000"));
// Deposit funds
const deposit = await funder.deposit(ethers.BigNumber.from("1000000000"));

Reading Database Schemas

The database schema returns a JSON representations of a database. Information on full JSON representations can be found in the databases section.
const res = await kwil.getSchema("0xOwner_address", "database_name")
/* = {
name: "database_name",
owner: "0xowner_address",
tables: [ tableObject1, tableObject2, tableObject3 ]
sqlQueries: [ sqlQueryObject1, sqlQueryObject2, sqlQueryObject3 ]
roles: [ roleObject1, roleObject2, roleObject3 ]
indexes: [ indexObject1, indexObject2, indexObject3 ]

Retrieving DBIs and Executables

Different from schemas, Database Interfaces (DBIs) are small structures that provide an easy-to-use interface for databases. They are conceptually similar to smart contract ABIs.
let dbi = await kwil.selectDatabase("0xOwner_address", "database_name")
dbi = DBI {
owner: "0xOwner_address",
name: "database_name",
queries: map<name, executable>
// getting a query
const query = dbi.getQuery("my_query")

Writing Data

Data can be written by using executables provided through the DBI. The setInput method receives two arguments: the name of the input being set and the value.
// setting query inputs
query.setInput("input_name", "satoshi")
query.setInput("other_input_name", 20)
// you can check if all required inputs have been set
if (!query.isComplete()) {
throw new Error("Executable is not complete")
// generated a new transaction from the filled query
let tx = query.newTx()
// prepare tx
tx = await kwil.prepareTx(tx, provider) // can also use the "wallet" here
// broadcast the transaction
const res = await kwil.broadcast(tx)
/* = {
hash: "TxHash",
fee: "some_spent_fee"

Reading Data

Data can be read from schemas with GraphQL. Our team is actively working to provide more ways to read data.
const res = await kwil.graphql(`query GraphQLQuery {
where: {col1: {_eq: "my_val"}}
) {