About
Protocol
Walkthroughs
Integrations
Intro to NFT Metadata
Tutorials
Smart Contracts
Concepts
Playbooks
Learn
JSON RPC API
API Reference for the core JSON RPC API.
Each Tableland validator provides a simple JSON-RPC 2.0 API to interact with the Tableland network. These API methods are used under the hood by the JavaScript SDK and CLI tool, and they enable tons of flexibility once you start utilizing the power of SQL statements.
Recall that creating and writing to tables requires a transaction to be sent on a blockchain. This requires gas and must be paid for. To make it easy for developers, any smart contracts that are deployed on testnet chains will be able to use the Tableland validator to relay the transaction for them. The transaction will sent by and paid for by the validator free of charge with testnet currency.
On mainnet chains, Tableland will not relay transactions. Thus, the APIs and RPCs that leverage the relay feature cannot be used for a mainnet chain deployment. Only testnet transactions are relayed by the validator to the corresponding chain.
Setup
Before getting started, review the CLI documentation for how to generate a Sign In With Ethereum (SIWE) token using tableland token
. Add this as an environment variable (export SIWE_TOKEN=siwe_token_string
) to then use the token within the various method calls.
All of the RPC calls expect an Authorization header with a signed SIWE, except for read queries. Reads do not require any on-chain interaction to take place and can directly access the Tableland network of validators.
Lastly, a number of examples have been provided using HTTPie and cURL — ensure these are installed if you would like to follow along. An optional tool called jq can be used to format the responses in a “pretty” format (e.g., curl <url> | jq
).
Settings & Request Format
The following HTTP settings are what’s needed to interact with JSON-RPC APIs. All requests should send an HTTP POST
with a Content-Type: application/json
header and contain the following fields in the JSON request data:
jsonrpc: <string>
⇒ Always set to"2.0"
(see JSON-PRC 2.0 spec for details)id: <number>
⇒ Some unique client generated integer; value doesn’t really matter (e.g.,1
)method: <string>
⇒ The desired method to be calledparams: <array>
⇒ A JSON array containing a single object with a key and value (defined by each method)<object>
⇒ Object with the method params<string>: <string>
⇒ A single (or set of) key-value pairs, defined in each method
All requests, except for tableland_runReadQuery
, also need to set a header for Authorization': 'Bearer {siwe_token}'
with the SIWE token.
Endpoint
All chains use the same endpoint:
https://testnet.tableland.network/rpc
Response Format
The response will include a JSON object with the following information:
jsonrpc: <string>
⇒ Should match thejsonrpc
string from the requestid: <number>
⇒ Should match the client-generated number from the requestresult: <object>
⇒ Requested data as a JSON object, along with success confirmation
Errors
If an error occurs, the response will return an error
instead of result
. Namely, the full response will include the jsonrpc
and id
defined above as well as:
error: <object>
⇒ Error object only included if there are request issuescode: <number>
⇒ Numeric code that identifies the error typemessage: <string>
⇒ Addition context about the error
Methods Overview
tableland_runReadQuery
tableland_validateCreateTable
tableland_validateWriteQuery
tableland_getReceipt
Testnet Only Methods
Definitions
- Structure hash ⇒ Hash generated upon table creation that describes uniquely describes a table schema (i.e., identical schemas have equivalent structure hashes)
- Transaction ⇒ Instructions corresponding an on-chain activity, represented as a hash
- Chain ⇒ Blockchain or layer two solution in which transactions are being sent; available chainId options can be found here
JSON-RPC API Reference
tableland_runReadQuery
Execute a read query (SELECT
) request and have the corresponding results returned.
Parameters
<object>
⇒ Object containing a single field that specifies the read query statementstatement: <string>
⇒ The SQL read query statement
Response
<object>
⇒ Object containing all results matching the read query statementdata: <object>
⇒ Object that contains the columns and rowscolumns: <array>
⇒ Array of objects, each describing a corresponding table column<object>
⇒ Object containing information about a single columnname: <string>
⇒ The name of the columnrows: <array>
⇒ Array of arrays, each describing the table rows<array>
⇒ Array of row values, each separated by a comma and corresponding to the order of the objects incolumns
Example
Request (using curl):
curl --location --request POST 'https://testnet.tableland.network/rpc' \
--header 'Content-Type: application/json' \
--data-raw '{
"jsonrpc": "2.0",
"method": "tableland_runReadQuery",
"id" : 1,
"params": [{
"statement": "SELECT * FROM rpc_counter_5_65"
}]
}'
https https://testnet.tableland.network/rpc \
jsonrpc=2.0 id=1 method=tableland_runReadQuery \
params:='[{"statement":"SELECT * FROM rpc_counter_5_65"}]'
Response:
{
"jsonrpc": "2.0",
"id": "1",
"result": {
"data": {
"columns": [
{
"name": "counter"
}
],
"rows": [
[
0
],
]
}
}
}
tableland_validateCreateTable
Validate a CREATE TABLE
query as a pre-creation check, and also calculate its structure hash.
Parameters
<object>
⇒ Object containing a single field that specifies the create table statementcreate_statement: <string>
⇒ SQLCREATE TABLE
statement with corresponding schema, using the table’s prefix_chainId as the table name (i.e., no appended table id)
Response
<object>
⇒ Object containing the structure hashstructure_hash: <string>
⇒ String representing the table’s schema, as a hash
Example
Request (using curl):
curl --location --request POST 'https://testnet.tableland.network/rpc' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer '"$SIWE_TOKEN"'' \
--data-raw '{
"jsonrpc": "2.0",
"method": "tableland_validateCreateTable",
"id" : 1,
"params": [{
"create_statement": "CREATE TABLE rpc_counter_5 (id int, name text)"
}]
}'
https -A bearer -a $TBL_TOKEN post https://testnet.tableland.network/rpc \
jsonrpc=2.0 id=1 method=tableland_validateCreateTable \
params:='[{ "create_statement": "CREATE TABLE rpc_table_5 (id int, name text)" }]'
Response:
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"structure_hash": "466dc130f3b02cf995fb66f6a0bdbadc49d2a527c26ac328daddc3f7b8ef779c"
}
}
tableland_validateWriteQuery
Validate a write query as a pre-write check.
Parameters
<object>
⇒ Object containing a single field that specifies the write query statementstatement: <string>
⇒ SQL write query statement
Response
<object>
⇒ Object containing the tableIdstructure_hash: <string>
⇒ String representing the table’s schema, as a hash
Example
Request (using curl):
curl --location --request POST 'https://testnet.tableland.network/rpc' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer '"$SIWE_TOKEN"'' \
--data-raw '{
"jsonrpc": "2.0",
"method": "tableland_validateWriteQuery",
"id" : 1,
"params": [{
"statement": "INSERT INTO rpc_counter_5_65 VALUES (0)"
}]
}'
https -A bearer -a $TBL_TOKEN post https://testnet.tableland.network/rpc \
jsonrpc=2.0 id=1 method=tableland_validateWriteQuery \
params:='[{ "statement": "INSERT INTO rpc_counter_5_65 VALUES (0)" }]'
Response:
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"table_id": "65"
}
}
tableland_getReceipt
Get the receipt of a chain transaction to verify if it was executed, along with the execution details.
Parameters
<object>
⇒ Object containing a single field that specifies the transaction hashtxn_hash: <string>
⇒ On-chain transaction hash corresponding to an interaction with a table
Response
<object>
⇒ Object containing information about the corresponding transactionok: <bool>
⇒ Boolean that represents if the transaction was executed or notreceipt: <object>
⇒ If"ok": true
, the response includes the related transaction datachain_id: <number>
⇒ Identifier for the corresponding chainIdtxn_hash: <string>
⇒ Matching transaction hash from the requestblock_number: <int>
⇒ Block in which the transaction was includedtable_id: <string>
⇒ Unique id relative to the chain, representing a table’s ERC-721 tokenIderror: <string>
⇒ If there’s no error, an empty string; if there is an error occurred, the message is included (e.g,,db query execution failed (code: SQLITE_cannot…
)error_event_idx: <int>
⇒ Returns-1
if no error message was included, or returns a number that’s not-1
if an error does exist
Example
Request (using curl):
curl --location --request POST 'https://testnet.tableland.network/rpc' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer '"$SIWE_TOKEN"'' \
--data-raw '{
"jsonrpc": "2.0",
"method": "tableland_getReceipt",
"id" : 1,
"params": [{
"txn_hash": "0xb6da1119ab376055767cde770647a66024119b429cea332443682e2b53e378dc"
}]
}'
https -A bearer -a $TBL_TOKEN post https://testnet.tableland.network/rpc \
jsonrpc=2.0 id=1 method=tableland_getReceipt \
params:='[{ "txn_hash": "0xb6da1119ab376055767cde770647a66024119b429cea332443682e2b53e378dc" }]'
Response:
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"ok": true,
"receipt": {
"chain_id": 5,
"txn_hash": "0xb6da1119ab376055767cde770647a66024119b429cea332443682e2b53e378dc",
"block_number": 7223294,
"table_id": "65"
"error": "",
"error_event_idx": -1
}
}
}
}
Testnet Only Methods
tableland_relayWriteQuery
For write queries, use a validator to relay a runSQL
smart contract call on your behalf
Parameters
<object>
⇒ Object containing a single field that specifies the write query statementcaller: <string>
⇒ On-chain address that is setting the controller (must be the table’s owner)token_id: <string>
⇒ Identifier for the table’s tokenId from the smart contractcontroller: <string>
⇒ On-chain address of the controller (EOA or contract)
Response
<object>
⇒ Object containing information about the corresponding transactiontx: <object>
⇒ Object containing the transaction hashhash: <string>
⇒ On-chain transaction hash corresponding to arunQL
smart contract call
Example
Request (using curl):
curl --location --request POST 'https://testnet.tableland.network/rpc' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer '"$SIWE_TOKEN"'' \
--data-raw '{
"jsonrpc": "2.0",
"method": "tableland_relayWriteQuery",
"id" : 1,
"params": [{
"statement": "INSERT INTO rpc_counter_5_65 VALUES (0)"
}]
}'
https -A bearer -a $TBL_TOKEN post https://testnet.tableland.network/rpc \
jsonrpc=2.0 id=1 method=tableland_relayWriteQuery \
params:='[{
"statement": "INSERT INTO rpc_counter_5_65 VALUES (0)"
}]'
Response:
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"tx": {
"hash": "0xe558e5d284f165573e4f716f9b3943f6fbe9c2c66be2a4d7da12dadc0ea9458f"
}
}
}
tableland_setController
Set the table’s controller by using a validator to relay a setController
smart contract call on your behalf, using the SIWE token to infer a caller.
Parameters
<object>
⇒ Object containing a single field that specifies the write query statementtoken_id: <string>
⇒ Identifier for the table’s tokenId from the smart contractcontroller: <string>
⇒ On-chain address of the controller (EOA or contract)
Response
<object>
⇒ Object containing information about the corresponding transactiontx: <object>
⇒ Object containing the transaction hashhash: <string>
⇒ On-chain transaction hash corresponding to asetController
smart contract call
Example
Request (using curl):
curl --location --request POST 'https://testnet.tableland.network/rpc' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer '"$SIWE_TOKEN"'' \
--data-raw '{
"jsonrpc": "2.0",
"method": "tableland_setController",
"id" : 1,
"params": [{
"token_id": "65",
"controller": "0x9bA89c8aD3856C0137E268bD76ed12d14696E140"
}]
}'
https -A bearer -a $TBL_TOKEN post https://testnet.tableland.network/rpc \
jsonrpc=2.0 id=1 method=tableland_setController \
params:='[{
"caller": "0x4D5286d81317E284Cd377cB98b478552Bbe641ae",
"token_id": "65",
"controller": "0x9bA89c8aD3856C0137E268bD76ed12d14696E140"
}]'
Response:
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"tx": true,
"receipt": {
"tx": {
"hash": "0xa69590589a9ae04bfde4ca07351c611f9ddb2ddc3bab6cd0165684dc959be5c7"
}
}
}
}
On this page
- JSON RPC API
- Setup
- Settings & Request Format
- Endpoint
- Response Format
- Errors
- Methods Overview
- Testnet Only Methods
- Definitions
- JSON-RPC API Reference
- tableland_runReadQuery
- Parameters
- Response
- Example
- tableland_validateCreateTable
- Parameters
- Response
- Example
- tableland_validateWriteQuery
- Parameters
- Response
- Example
- tableland_getReceipt
- Parameters
- Response
- Example
- Testnet Only Methods
- tableland_relayWriteQuery
- Parameters
- Response
- Example
- tableland_setController
- Parameters
- Response
- Example