Skip to main content
POST
/
v1
/
w3s
/
contracts
/
query
Execute a query function on a contract
curl --request POST \
  --url https://api.circle.com/v1/w3s/contracts/query \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "address": "0x1e124d7384cd34448ea5907bd0052a79355ab5eb",
  "blockchain": "MATIC-AMOY",
  "abiFunctionSignature": "burn(uint256)",
  "abiParameters": [
    "100",
    "1"
  ],
  "abiJson": "[{\"inputs\": [],\"stateMutability\": \"nonpayable\",\"type\": \"constructor\"},...",
  "callData": "<string>",
  "fromAddress": "<string>"
}
'
{
  "data": {
    "outputValues": [
      "<unknown>"
    ],
    "outputData": "<string>"
  }
}

Authorizations

​
Authorization
string
header
required

Circle's API Keys are formatted in the following structure "PREFIX:ID:SECRET". All three parts are requred to make a successful request.

Headers

​
X-Request-Id
string<uuid>

Developer-provided identifier for this request, used for tracing requests in Wallets API logs and the Developer Console, and when communicating with Circle Support. Must be a UUID to appear in logs. Non-UUID values are accepted by the API but are ignored by logging and tracing systems.

A unique identifier, which can be helpful for identifying a request when communicating with Circle support.

Example:

"2adba88e-9d63-44bc-b975-9b6ae3440dde"

Body

application/json

Read contract state by executing a read ABI function.

​
address
string
required

Address of the contract to be queried.

Example:

"0x1e124d7384cd34448ea5907bd0052a79355ab5eb"

​
blockchain
enum<string>
required

The blockchain network that the resource is to be created on or is currently on. Required along with sourceAddress if you don't provide walletId. The blockchain and walletId fields are mutually exclusive.

Available options:
ETH,
ETH-SEPOLIA,
MATIC,
MATIC-AMOY,
ARB,
ARB-SEPOLIA,
UNI,
UNI-SEPOLIA,
BASE,
BASE-SEPOLIA,
OP,
OP-SEPOLIA,
AVAX,
AVAX-FUJI,
ARC-TESTNET,
MONAD,
MONAD-TESTNET
Example:

"MATIC-AMOY"

​
abiFunctionSignature
string

The contract ABI function signature or callData field is required for interacting with the smart contract. The ABI function signature cannot be used simultaneously with callData. e.g. burn(uint256)

Example:

"burn(uint256)"

​
abiParameters
(string | integer | boolean | any[])[]

The contract ABI function signature parameters for executing the contract interaction. Supported parameter types include string, integer, boolean, and array. These parameters should be used exclusively with the abiFunctionSignature and cannot be used with callData.

Example:
["100", "1"]
​
abiJson
string

The contract's ABI in a JSON stringified format.

Example:

"[{\"inputs\": [],\"stateMutability\": \"nonpayable\",\"type\": \"constructor\"},..."

​
callData
string

CallData is input data that encodes method and parameters.

​
fromAddress
string

FromAddress is the address that will populate msg.sender in the contract call.

Response

Contract read successfully.

​
data
object
required