Smart Contracts

Endpoints for interacting with Clarity smart contracts.

Get contract interface

get

http://localhost:20443https://api.mainnet.hiro.sohttps://api.testnet.hiro.so

/v2/contracts/interface/{contract_address}/{contract_name}

Get contract interface using a contract_address and contract name

Path parameters

contract_addressstring · min: 28 · max: 41Required

Standard Stacks address (e.g. SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0). Must be 28-41 characters long using Stacks base58check format.

Example: SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0Pattern: ^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}$

contract_namestring · min: 1 · max: 128Required

Contract name. Must start with a letter and can contain letters, numbers, hyphens, and underscores. Maximum length is 40 characters for new contracts. Legacy contracts may have names up to 128 characters.

Example: get-infoPattern: ^[a-zA-Z]([a-zA-Z0-9]|[-_]){0,127}$

Query parameters

tipstring · max: 64Optional

Stacks chain tip to query from. Options:

• (empty/omitted): Use latest anchored tip (canonical confirmed state)
• latest: Use latest known tip including unconfirmed microblocks
• {block_id}: Use specific block ID (64 hex characters)

Example: latestPattern: ^(latest|[0-9a-f]{64})?$

Responses

200

Contract interface

application/json

400

Bad request

text/plain

404

Not found

text/plain

500

Internal Server Error

text/plain

get

/v2/contracts/interface/{contract_address}/{contract_name}

HTTPcURLJavaScriptPython

GET /v2/contracts/interface/{contract_address}/{contract_name} HTTP/1.1
Host: localhost:20443
Accept: */*

{
  "functions": [
    {
      "name": "protocol-mint-many-iter",
      "access": "private",
      "args": [
        {
          "name": "item",
          "type": {
            "tuple": [
              {
                "name": "amount",
                "type": "uint128"
              },
              {
                "name": "recipient",
                "type": "principal"
              }
            ]
          }
        }
      ],
      "outputs": {
        "type": {
          "response": {
            "ok": "bool",
            "error": "uint128"
          }
        }
      }
    },
    {
      "name": "transfer-many-iter",
      "access": "private",
      "args": [
        {
          "name": "individual-transfer",
          "type": {
            "tuple": [
              {
                "name": "amount",
                "type": "uint128"
              },
              {
                "name": "memo",
                "type": {
                  "optional": {
                    "buffer": {
                      "length": 34
                    }
                  }
                }
              },
              {
                "name": "sender",
                "type": "principal"
              },
              {
                "name": "to",
                "type": "principal"
              }
            ]
          }
        },
        {
          "name": "result",
          "type": {
            "response": {
              "ok": "uint128",
              "error": "uint128"
            }
          }
        }
      ],
      "outputs": {
        "type": {
          "response": {
            "ok": "uint128",
            "error": "uint128"
          }
        }
      }
    },
    {
      "name": "protocol-burn",
      "access": "public",
      "args": [
        {
          "name": "amount",
          "type": "uint128"
        },
        {
          "name": "owner",
          "type": "principal"
        },
        {
          "name": "contract-flag",
          "type": {
            "buffer": {
              "length": 1
            }
          }
        }
      ],
      "outputs": {
        "type": {
          "response": {
            "ok": "bool",
            "error": "uint128"
          }
        }
      }
    },
    {
      "name": "protocol-burn-locked",
      "access": "public",
      "args": [
        {
          "name": "amount",
          "type": "uint128"
        },
        {
          "name": "owner",
          "type": "principal"
        },
        {
          "name": "contract-flag",
          "type": {
            "buffer": {
              "length": 1
            }
          }
        }
      ],
      "outputs": {
        "type": {
          "response": {
            "ok": "bool",
            "error": "uint128"
          }
        }
      }
    },
    {
      "name": "protocol-lock",
      "access": "public",
      "args": [
        {
          "name": "amount",
          "type": "uint128"
        },
        {
          "name": "owner",
          "type": "principal"
        },
        {
          "name": "contract-flag",
          "type": {
            "buffer": {
              "length": 1
            }
          }
        }
      ],
      "outputs": {
        "type": {
          "response": {
            "ok": "bool",
            "error": "uint128"
          }
        }
      }
    },
    {
      "name": "protocol-mint",
      "access": "public",
      "args": [
        {
          "name": "amount",
          "type": "uint128"
        },
        {
          "name": "recipient",
          "type": "principal"
        },
        {
          "name": "contract-flag",
          "type": {
            "buffer": {
              "length": 1
            }
          }
        }
      ],
      "outputs": {
        "type": {
          "response": {
            "ok": "bool",
            "error": "uint128"
          }
        }
      }
    },
    {
      "name": "protocol-mint-many",
      "access": "public",
      "args": [
        {
          "name": "recipients",
          "type": {
            "list": {
              "type": {
                "tuple": [
                  {
                    "name": "amount",
                    "type": "uint128"
                  },
                  {
                    "name": "recipient",
                    "type": "principal"
                  }
                ]
              },
              "length": 200
            }
          }
        },
        {
          "name": "contract-flag",
          "type": {
            "buffer": {
              "length": 1
            }
          }
        }
      ],
      "outputs": {
        "type": {
          "response": {
            "ok": {
              "list": {
                "type": {
                  "response": {
                    "ok": "bool",
                    "error": "uint128"
                  }
                },
                "length": 200
              }
            },
            "error": "uint128"
          }
        }
      }
    },
    {
      "name": "protocol-set-name",
      "access": "public",
      "args": [
        {
          "name": "new-name",
          "type": {
            "string-ascii": {
              "length": 32
            }
          }
        },
        {
          "name": "contract-flag",
          "type": {
            "buffer": {
              "length": 1
            }
          }
        }
      ],
      "outputs": {
        "type": {
          "response": {
            "ok": "bool",
            "error": "uint128"
          }
        }
      }
    },
    {
      "name": "protocol-set-symbol",
      "access": "public",
      "args": [
        {
          "name": "new-symbol",
          "type": {
            "string-ascii": {
              "length": 10
            }
          }
        },
        {
          "name": "contract-flag",
          "type": {
            "buffer": {
              "length": 1
            }
          }
        }
      ],
      "outputs": {
        "type": {
          "response": {
            "ok": "bool",
            "error": "uint128"
          }
        }
      }
    },
    {
      "name": "protocol-set-token-uri",
      "access": "public",
      "args": [
        {
          "name": "new-uri",
          "type": {
            "optional": {
              "string-utf8": {
                "length": 256
              }
            }
          }
        },
        {
          "name": "contract-flag",
          "type": {
            "buffer": {
              "length": 1
            }
          }
        }
      ],
      "outputs": {
        "type": {
          "response": {
            "ok": "bool",
            "error": "uint128"
          }
        }
      }
    },
    {
      "name": "protocol-unlock",
      "access": "public",
      "args": [
        {
          "name": "amount",
          "type": "uint128"
        },
        {
          "name": "owner",
          "type": "principal"
        },
        {
          "name": "contract-flag",
          "type": {
            "buffer": {
              "length": 1
            }
          }
        }
      ],
      "outputs": {
        "type": {
          "response": {
            "ok": "bool",
            "error": "uint128"
          }
        }
      }
    },
    {
      "name": "transfer",
      "access": "public",
      "args": [
        {
          "name": "amount",
          "type": "uint128"
        },
        {
          "name": "sender",
          "type": "principal"
        },
        {
          "name": "recipient",
          "type": "principal"
        },
        {
          "name": "memo",
          "type": {
            "optional": {
              "buffer": {
                "length": 34
              }
            }
          }
        }
      ],
      "outputs": {
        "type": {
          "response": {
            "ok": "bool",
            "error": "uint128"
          }
        }
      }
    },
    {
      "name": "transfer-many",
      "access": "public",
      "args": [
        {
          "name": "recipients",
          "type": {
            "list": {
              "type": {
                "tuple": [
                  {
                    "name": "amount",
                    "type": "uint128"
                  },
                  {
                    "name": "memo",
                    "type": {
                      "optional": {
                        "buffer": {
                          "length": 34
                        }
                      }
                    }
                  },
                  {
                    "name": "sender",
                    "type": "principal"
                  },
                  {
                    "name": "to",
                    "type": "principal"
                  }
                ]
              },
              "length": 200
            }
          }
        }
      ],
      "outputs": {
        "type": {
          "response": {
            "ok": "uint128",
            "error": "uint128"
          }
        }
      }
    },
    {
      "name": "get-balance",
      "access": "read_only",
      "args": [
        {
          "name": "who",
          "type": "principal"
        }
      ],
      "outputs": {
        "type": {
          "response": {
            "ok": "uint128",
            "error": "none"
          }
        }
      }
    },
    {
      "name": "get-balance-available",
      "access": "read_only",
      "args": [
        {
          "name": "who",
          "type": "principal"
        }
      ],
      "outputs": {
        "type": {
          "response": {
            "ok": "uint128",
            "error": "none"
          }
        }
      }
    },
    {
      "name": "get-balance-locked",
      "access": "read_only",
      "args": [
        {
          "name": "who",
          "type": "principal"
        }
      ],
      "outputs": {
        "type": {
          "response": {
            "ok": "uint128",
            "error": "none"
          }
        }
      }
    },
    {
      "name": "get-decimals",
      "access": "read_only",
      "args": [],
      "outputs": {
        "type": {
          "response": {
            "ok": "uint128",
            "error": "none"
          }
        }
      }
    },
    {
      "name": "get-name",
      "access": "read_only",
      "args": [],
      "outputs": {
        "type": {
          "response": {
            "ok": {
              "string-ascii": {
                "length": 32
              }
            },
            "error": "none"
          }
        }
      }
    },
    {
      "name": "get-symbol",
      "access": "read_only",
      "args": [],
      "outputs": {
        "type": {
          "response": {
            "ok": {
              "string-ascii": {
                "length": 10
              }
            },
            "error": "none"
          }
        }
      }
    },
    {
      "name": "get-token-uri",
      "access": "read_only",
      "args": [],
      "outputs": {
        "type": {
          "response": {
            "ok": {
              "optional": {
                "string-utf8": {
                  "length": 256
                }
              }
            },
            "error": "none"
          }
        }
      }
    },
    {
      "name": "get-total-supply",
      "access": "read_only",
      "args": [],
      "outputs": {
        "type": {
          "response": {
            "ok": "uint128",
            "error": "none"
          }
        }
      }
    }
  ],
  "variables": [
    {
      "name": "ERR_NOT_OWNER",
      "type": {
        "response": {
          "ok": "none",
          "error": "uint128"
        }
      },
      "access": "constant"
    },
    {
      "name": "ERR_TRANSFER_INDEX_PREFIX",
      "type": "uint128",
      "access": "constant"
    },
    {
      "name": "token-decimals",
      "type": "uint128",
      "access": "constant"
    },
    {
      "name": "token-name",
      "type": {
        "string-ascii": {
          "length": 32
        }
      },
      "access": "variable"
    },
    {
      "name": "token-symbol",
      "type": {
        "string-ascii": {
          "length": 10
        }
      },
      "access": "variable"
    },
    {
      "name": "token-uri",
      "type": {
        "optional": {
          "string-utf8": {
            "length": 256
          }
        }
      },
      "access": "variable"
    }
  ],
  "maps": [],
  "fungible_tokens": [
    {
      "name": "sbtc-token"
    },
    {
      "name": "sbtc-token-locked"
    }
  ],
  "non_fungible_tokens": [],
  "epoch": "Epoch30",
  "clarity_version": "Clarity3"
}

Get specific data-map inside a contract

post

http://localhost:20443https://api.mainnet.hiro.sohttps://api.testnet.hiro.so

/v2/map_entry/{contract_address}/{contract_name}/{map_name}

Attempt to fetch data from a contract data map. The contract is identified with [Stacks Address] and [Contract Name] in the URL path. The map is identified with [Map Name].

The key to lookup in the map is supplied via the POST body. This should be supplied as the hex string serialization of the key (which should be a Clarity value). Note, this is a JSON string.

The response is a JSON object with the following properties:

• data: The hex serialization of the map response. Note that map responses are Clarity option types, for non-existent values, this is a serialized none, and for all other responses, it is a serialized (some ...) object.

• proof: The hex serialization of the Merkle proof for the data.

Path parameters

contract_addressstring · min: 28 · max: 41Required

Standard Stacks address (e.g. SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0). Must be 28-41 characters long using Stacks base58check format.

Example: SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0Pattern: ^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}$

contract_namestring · min: 1 · max: 128Required

Contract name. Must start with a letter and can contain letters, numbers, hyphens, and underscores. Maximum length is 40 characters for new contracts. Legacy contracts may have names up to 128 characters.

Example: get-infoPattern: ^[a-zA-Z]([a-zA-Z0-9]|[-_]){0,127}$

map_namestring · min: 1 · max: 128RequiredPattern: ^([a-zA-Z0-9_]|[-!?+<>=/*]){1,128}$

Query parameters

proofinteger · enumOptional

Controls MARF proof inclusion in response. Set to 1 (default) to include proof, 0 to exclude. Invalid values default to 0 (no proof).

Default: 1Example: 1Possible values:

tipstring · max: 64Optional

Stacks chain tip to query from. Options:

• (empty/omitted): Use latest anchored tip (canonical confirmed state)
• latest: Use latest known tip including unconfirmed microblocks
• {block_id}: Use specific block ID (64 hex characters)

Example: latestPattern: ^(latest|[0-9a-f]{64})?$

Body

application/json

stringOptional

Responses

200

Success

application/json

400

Bad request

text/plain

404

Not found

text/plain

500

Internal Server Error

text/plain

post

/v2/map_entry/{contract_address}/{contract_name}/{map_name}

HTTPcURLJavaScriptPython

POST /v2/map_entry/{contract_address}/{contract_name}/{map_name} HTTP/1.1
Host: localhost:20443
Content-Type: application/json
Accept: */*
Content-Length: 6

"text"

{
  "data": "0x0a0c000000010a6d6f6e737465722d69640100000000000000000000000000000001",
  "proof": "0x123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
}

Get contract source

get

http://localhost:20443https://api.mainnet.hiro.sohttps://api.testnet.hiro.so

/v2/contracts/source/{contract_address}/{contract_name}

Returns the Clarity source code of a given contract, along with the block height it was published in, and the MARF proof for the data.

Path parameters

contract_addressstring · min: 28 · max: 41Required

Standard Stacks address (e.g. SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0). Must be 28-41 characters long using Stacks base58check format.

Example: SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0Pattern: ^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}$

contract_namestring · min: 1 · max: 128Required

Contract name. Must start with a letter and can contain letters, numbers, hyphens, and underscores. Maximum length is 40 characters for new contracts. Legacy contracts may have names up to 128 characters.

Example: get-infoPattern: ^[a-zA-Z]([a-zA-Z0-9]|[-_]){0,127}$

Query parameters

proofinteger · enumOptional

Controls MARF proof inclusion in response. Set to 1 (default) to include proof, 0 to exclude. Invalid values default to 0 (no proof).

Default: 1Example: 1Possible values:

tipstring · max: 64Optional

Stacks chain tip to query from. Options:

• (empty/omitted): Use latest anchored tip (canonical confirmed state)
• latest: Use latest known tip including unconfirmed microblocks
• {block_id}: Use specific block ID (64 hex characters)

Example: latestPattern: ^(latest|[0-9a-f]{64})?$

Responses

200

Success

application/json

400

Bad request

text/plain

404

Not found

text/plain

500

Internal Server Error

text/plain

get

/v2/contracts/source/{contract_address}/{contract_name}

HTTPcURLJavaScriptPython

GET /v2/contracts/source/{contract_address}/{contract_name} HTTP/1.1
Host: localhost:20443
Accept: */*

{
  "source": "(define-constant sender 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR)\n(define-constant recipient 'SM2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQVX8X0G)\n\n(define-fungible-token novel-token-19)\n(begin (ft-mint? novel-token-19 u12 sender))\n(begin (ft-transfer? novel-token-19 u2 sender recipient))\n\n(define-non-fungible-token hello-nft uint)\n(begin (nft-mint? hello-nft u1 sender))\n(begin (nft-mint? hello-nft u2 sender))\n(begin (nft-transfer? hello-nft u1 sender recipient))\n\n(define-public (test-emit-event)\n    (begin\n        (print \"Event! Hello world\")\n        (ok u1)))\n(begin (test-emit-event))\n\n(define-public (test-event-types)\n    (begin\n        (unwrap-panic (ft-mint? novel-token-19 u3 recipient))\n        (unwrap-panic (nft-mint? hello-nft u2 recipient))\n        (unwrap-panic (stx-transfer? u60 tx-sender 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR))\n        (unwrap-panic (stx-burn? u20 tx-sender))\n        (ok u1)))\n\n(define-map store ((key (buff 32))) ((value (buff 32))))\n(define-public (get-value (key (buff 32)))\n    (begin\n        (match (map-get? store ((key key)))\n            entry (ok (get value entry))\n            (err 0))))\n(define-public (set-value (key (buff 32)) (value (buff 32)))\n    (begin\n        (map-set store ((key key)) ((value value)))\n        (ok u1)))",
  "publish_height": 3196,
  "proof": "0x000000110406000000123456789abcdef"
}

Call read-only function

post

http://localhost:20443https://api.mainnet.hiro.sohttps://api.testnet.hiro.so

/v2/contracts/call-read/{contract_address}/{contract_name}/{function_name}

Call a read-only public function on a given contract.

The contract is identified with [Stacks Address] and [Contract Name] in the URL path. The function is identified with [Function Name].

The arguments to the function are supplied via the POST body. This should be a JSON object with two main properties:

• sender which should be a standard Stacks address

• arguments which should be an array of hex-encoded Clarity values.

Path parameters

contract_addressstring · min: 28 · max: 41Required

Standard Stacks address (e.g. SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0). Must be 28-41 characters long using Stacks base58check format.

Example: SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0Pattern: ^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}$

contract_namestring · min: 1 · max: 128Required

Contract name. Must start with a letter and can contain letters, numbers, hyphens, and underscores. Maximum length is 40 characters for new contracts. Legacy contracts may have names up to 128 characters.

Example: get-infoPattern: ^[a-zA-Z]([a-zA-Z0-9]|[-_]){0,127}$

function_namestring · min: 1 · max: 128RequiredPattern: ^([a-zA-Z0-9_]|[-!?+<>=/*]){1,128}$

Query parameters

tipstring · max: 64Optional

Stacks chain tip to query from. Options:

• (empty/omitted): Use latest anchored tip (canonical confirmed state)
• latest: Use latest known tip including unconfirmed microblocks
• {block_id}: Use specific block ID (64 hex characters)

Example: latestPattern: ^(latest|[0-9a-f]{64})?$

Body

application/json

Describes representation of a Type-0 Stacks 2.0 transaction. https://github.com/stacksgov/sips/blob/main/sips/sip-005/sip-005-blocks-and-transactions.md#type-0-transferring-an-asset

senderstringRequired

The simulated tx-sender

sponsorstringOptional

The simulated sponsor address

argumentsstring[]Required

An array of hex serialized Clarity values

Responses

200

Function executed successfully

application/json

Responseone of

The result of a read-only function call.

or

400

Bad request

text/plain

404

Not found

text/plain

500

Internal Server Error

text/plain

post

/v2/contracts/call-read/{contract_address}/{contract_name}/{function_name}

HTTPcURLJavaScriptPython

POST /v2/contracts/call-read/{contract_address}/{contract_name}/{function_name} HTTP/1.1
Host: localhost:20443
Content-Type: application/json
Accept: */*
Content-Length: 55

{
  "sender": "text",
  "sponsor": "text",
  "arguments": [
    "text"
  ]
}

{
  "okay": true,
  "result": "0x0100000000000000000000000000000001"
}

Call read-only function in fast mode (no cost and memory tracking)

post

http://localhost:20443https://api.mainnet.hiro.sohttps://api.testnet.hiro.so

/v3/contracts/fast-call-read/{contract_address}/{contract_name}/{function_name}

Call a read-only public function on a given smart contract without cost tracking.

The contract is identified with [Stacks Address] and [Contract Name] in the URL path. The function is identified with [Function Name].

The arguments to the function are supplied via the POST body. This should be a JSON object with two main properties:

• sender which should be a standard Stacks address

• arguments which should be an array of hex-encoded Clarity values.

This API endpoint requires a basic Authorization header.

Authorizations

rpcAuth

authorizationstringRequired

Plain-text secret value that must exactly equal the node's configured password, which is set as connection_options.auth_token in the node's configuration file.

Path parameters

contract_addressstring · min: 28 · max: 41Required

Standard Stacks address (e.g. SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0). Must be 28-41 characters long using Stacks base58check format.

Example: SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0Pattern: ^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}$

contract_namestring · min: 1 · max: 128Required

Contract name. Must start with a letter and can contain letters, numbers, hyphens, and underscores. Maximum length is 40 characters for new contracts. Legacy contracts may have names up to 128 characters.

Example: get-infoPattern: ^[a-zA-Z]([a-zA-Z0-9]|[-_]){0,127}$

function_namestring · min: 1 · max: 128RequiredPattern: ^([a-zA-Z0-9_]|[-!?+<>=/*]){1,128}$

Query parameters

tipstring · max: 64Optional

Stacks chain tip to query from. Options:

• (empty/omitted): Use latest anchored tip (canonical confirmed state)
• latest: Use latest known tip including unconfirmed microblocks
• {block_id}: Use specific block ID (64 hex characters)

Example: latestPattern: ^(latest|[0-9a-f]{64})?$

Body

application/json

Describes representation of a Type-0 Stacks 2.0 transaction. https://github.com/stacksgov/sips/blob/main/sips/sip-005/sip-005-blocks-and-transactions.md#type-0-transferring-an-asset

senderstringRequired

The simulated tx-sender

sponsorstringOptional

The simulated sponsor address

argumentsstring[]Required

An array of hex serialized Clarity values

Responses

200

Function executed successfully

application/json

Responseone of

The result of a read-only function call.

or

400

Bad request

text/plain

401

Unauthorized. Invalid or missing authentication token.

text/plain

404

Not found

text/plain

408

Timeout

text/plain

500

Internal Server Error

text/plain

post

/v3/contracts/fast-call-read/{contract_address}/{contract_name}/{function_name}

HTTPcURLJavaScriptPython

POST /v3/contracts/fast-call-read/{contract_address}/{contract_name}/{function_name} HTTP/1.1
Host: localhost:20443
authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 102

{
  "sender": "SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-info",
  "arguments": [
    "0x0011...",
    "0x00231..."
  ]
}

{
  "okay": true,
  "result": "0x0100000000000000000000000000000001"
}

Get trait implementation details

get

http://localhost:20443https://api.mainnet.hiro.sohttps://api.testnet.hiro.so

/v2/traits/{contract_address}/{contract_name}/{trait_contract_address}/{trait_contract_name}/{trait_name}

Determine whether or not a specified trait is implemented (either explicitly or implicitly) within a given contract.

Path parameters

contract_addressstring · min: 28 · max: 41Required

Standard Stacks address (e.g. SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0). Must be 28-41 characters long using Stacks base58check format.

Example: SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0Pattern: ^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}$

contract_namestring · min: 1 · max: 128Required

Contract name. Must start with a letter and can contain letters, numbers, hyphens, and underscores. Maximum length is 40 characters for new contracts. Legacy contracts may have names up to 128 characters.

Example: get-infoPattern: ^[a-zA-Z]([a-zA-Z0-9]|[-_]){0,127}$

trait_contract_addressstring · min: 28 · max: 41Required

Stacks address of the trait-defining contract.

Example: SP2Z1K16238380NBP4T38A4G10A90Q03JJ2C2003Pattern: ^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}$

trait_contract_namestring · min: 1 · max: 128Required

Contract name of the trait-defining contract.

Example: some-traitPattern: ^[a-zA-Z]([a-zA-Z0-9]|[-_]){0,127}$

trait_namestring · min: 1 · max: 128RequiredExample: some-traitPattern: ^([a-zA-Z0-9_]|[-!?+<>=/*]){1,128}$

Query parameters

tipstring · max: 64Optional

Stacks chain tip to query from. Options:

• (empty/omitted): Use latest anchored tip (canonical confirmed state)
• latest: Use latest known tip including unconfirmed microblocks
• {block_id}: Use specific block ID (64 hex characters)

Example: latestPattern: ^(latest|[0-9a-f]{64})?$

Responses

200

Success

application/json

400

Bad request

text/plain

404

Not found

text/plain

get

/v2/traits/{contract_address}/{contract_name}/{trait_contract_address}/{trait_contract_name}/{trait_name}

HTTPcURLJavaScriptPython

GET /v2/traits/{contract_address}/{contract_name}/{trait_contract_address}/{trait_contract_name}/{trait_name} HTTP/1.1
Host: localhost:20443
Accept: */*

{
  "is_implemented": true
}

Get the MARF value for a given key

get

http://localhost:20443https://api.mainnet.hiro.sohttps://api.testnet.hiro.so

/v2/clarity/marf/{marf_key_hash}

Attempt to fetch the value of a MARF key. The key is a 64-character hex string representing the MARF node hash.

Path parameters

marf_key_hashstring · min: 64 · max: 64Required

The 64-character hex-encoded hash of the MARF key.

Pattern: ^[0-9a-f]{64}$

Query parameters

proofinteger · enumOptional

Controls MARF proof inclusion in response. Set to 1 (default) to include proof, 0 to exclude. Invalid values default to 0 (no proof).

Default: 1Example: 1Possible values:

tipstring · max: 64Optional

Stacks chain tip to query from. Options:

• (empty/omitted): Use latest anchored tip (canonical confirmed state)
• latest: Use latest known tip including unconfirmed microblocks
• {block_id}: Use specific block ID (64 hex characters)

Example: latestPattern: ^(latest|[0-9a-f]{64})?$

Responses

200

Success

application/json

400

Bad request

text/plain

404

Not found

text/plain

get

/v2/clarity/marf/{marf_key_hash}

HTTPcURLJavaScriptPython

GET /v2/clarity/marf/{marf_key_hash} HTTP/1.1
Host: localhost:20443
Accept: */*

{
  "data": "0x0a0c000000010a6d6f6e737465722d69640100000000000000000000000000000001",
  "proof": "0x123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
}

Get the contract metadata for the metadata key

get

http://localhost:20443https://api.mainnet.hiro.sohttps://api.testnet.hiro.so

/v2/clarity/metadata/{contract_address}/{contract_name}/{clarity_metadata_key}

Attempt to fetch the metadata of a contract. The contract is identified with [Contract Address] and [Contract Name] in the URL path. The metadata key is identified with [Clarity Metadata Key].

In the response, data is formatted as JSON.

Path parameters

contract_addressstring · min: 28 · max: 41Required

Standard Stacks address (e.g. SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0). Must be 28-41 characters long using Stacks base58check format.

Example: SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0Pattern: ^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}$

contract_namestring · min: 1 · max: 128Required

Contract name. Must start with a letter and can contain letters, numbers, hyphens, and underscores. Maximum length is 40 characters for new contracts. Legacy contracts may have names up to 128 characters.

Example: get-infoPattern: ^[a-zA-Z]([a-zA-Z0-9]|[-_]){0,127}$

clarity_metadata_keystringRequired

Metadata key

Query parameters

tipstring · max: 64Optional

Stacks chain tip to query from. Options:

• (empty/omitted): Use latest anchored tip (canonical confirmed state)
• latest: Use latest known tip including unconfirmed microblocks
• {block_id}: Use specific block ID (64 hex characters)

Example: latestPattern: ^(latest|[0-9a-f]{64})?$

Responses

200

Success

application/json

400

Bad request

text/plain

404

Not found

text/plain

500

Internal Server Error

text/plain

get

/v2/clarity/metadata/{contract_address}/{contract_name}/{clarity_metadata_key}

HTTPcURLJavaScriptPython

GET /v2/clarity/metadata/{contract_address}/{contract_name}/{clarity_metadata_key} HTTP/1.1
Host: localhost:20443
Accept: */*

{
  "data": "'{\"contract_identifier\":{...}, \"private_function_types\":{...}'"
}

Get the value of a constant inside a contract

get

http://localhost:20443https://api.mainnet.hiro.sohttps://api.testnet.hiro.so

/v2/constant_val/{contract_address}/{contract_name}/{constant_name}

Attempt to fetch the value of a constant inside a contract. The contract is identified with [Stacks Address] and [Contract Name] in the URL path. The constant is identified with [Constant Name].

In the response, data is the hex serialization of the constant value.

Path parameters

contract_addressstring · min: 28 · max: 41Required

Standard Stacks address (e.g. SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0). Must be 28-41 characters long using Stacks base58check format.

Example: SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0Pattern: ^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}$

contract_namestring · min: 1 · max: 128Required

Contract name. Must start with a letter and can contain letters, numbers, hyphens, and underscores. Maximum length is 40 characters for new contracts. Legacy contracts may have names up to 128 characters.

Example: get-infoPattern: ^[a-zA-Z]([a-zA-Z0-9]|[-_]){0,127}$

constant_namestring · min: 1 · max: 128RequiredPattern: ^([a-zA-Z0-9_]|[-!?+<>=/*]){1,128}$

Query parameters

tipstring · max: 64Optional

Stacks chain tip to query from. Options:

• (empty/omitted): Use latest anchored tip (canonical confirmed state)
• latest: Use latest known tip including unconfirmed microblocks
• {block_id}: Use specific block ID (64 hex characters)

Example: latestPattern: ^(latest|[0-9a-f]{64})?$

Responses

200

Success

application/json

400

Bad request

text/plain

404

Not found

text/plain

500

Internal Server Error

text/plain

get

/v2/constant_val/{contract_address}/{contract_name}/{constant_name}

HTTPcURLJavaScriptPython

GET /v2/constant_val/{contract_address}/{contract_name}/{constant_name} HTTP/1.1
Host: localhost:20443
Accept: */*

{
  "data": "0x01ce0123456789abcdef"
}

Get contract data variable

get

http://localhost:20443https://api.mainnet.hiro.sohttps://api.testnet.hiro.so

/v2/data_var/{principal}/{contract_name}/{var_name}

Fetch a data variable from a smart contract. Returns the raw hex-encoded value of the variable.

Path parameters

principalstring · min: 28 · max: 170Required

Stacks address (28-41 characters) or a Contract identifier in format {address}.{contract_name} (e.g. SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-info). Contract names have a maximum length of 40 characters for new contracts. Legacy contracts may have names up to 128 characters.

Example: SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-infoPattern: ^([0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41})|([0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}\.[a-zA-Z]([a-zA-Z0-9]|[-_]){0,127})$

contract_namestring · min: 1 · max: 128Required

Contract name. Must start with a letter and can contain letters, numbers, hyphens, and underscores. Maximum length is 40 characters for new contracts. Legacy contracts may have names up to 128 characters.

Example: get-infoPattern: ^[a-zA-Z]([a-zA-Z0-9]|[-_]){0,127}$

var_namestringRequired

Variable name

Query parameters

proofinteger · enumOptional

Controls MARF proof inclusion in response. Set to 1 (default) to include proof, 0 to exclude. Invalid values default to 0 (no proof).

Default: 1Example: 1Possible values:

tipstring · max: 64Optional

Stacks chain tip to query from. Options:

• (empty/omitted): Use latest anchored tip (canonical confirmed state)
• latest: Use latest known tip including unconfirmed microblocks
• {block_id}: Use specific block ID (64 hex characters)

Example: latestPattern: ^(latest|[0-9a-f]{64})?$

Responses

200

The data variable value

application/json

400

Bad request

text/plain

404

Not found

text/plain

get

/v2/data_var/{principal}/{contract_name}/{var_name}

HTTPcURLJavaScriptPython

GET /v2/data_var/{principal}/{contract_name}/{var_name} HTTP/1.1
Host: localhost:20443
Accept: */*

{
  "data": "0x0a0c000000010a6d6f6e737465722d69640100000000000000000000000000000001",
  "proof": "0x123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
}