Ctrlk
Quick LinksPlatform
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Smart Contracts

Endpoints for interacting with Clarity smart contracts.

Get contract interface

get
/v2/contracts/interface/{deployer_address}/{contract_name}

Get contract interface using a deployer_address and contract name

Path parameters
deployer_addressstring · min: 28 · max: 41Required

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

Example: SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0Pattern: ^S[PTMN][0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26,39}$
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

The interface of a Clarity smart contract.

epochstringRequired

Stacks epoch identifier (e.g., "Epoch30").

clarity_versionstring · enumRequired

Clarity language version used by this contract.

Possible values:
get/v2/contracts/interface/{deployer_address}/{contract_name}
GET /v2/contracts/interface/{deployer_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
/v2/map_entry/{deployer_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
deployer_addressstring · min: 28 · max: 41Required

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

Example: SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0Pattern: ^S[PTMN][0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26,39}$
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: 128Required

A valid Clarity name. Must either:

  • Start with a letter and contain only letters, numbers, and [-_!?+<>=/*]
  • Be exactly one of the special characters: - + = * /
  • Be a comparison operator: < > <= >=
Pattern: ^[a-zA-Z]([a-zA-Z0-9]|[-_!?+<>=/*])*$|^[-+=/*]$|^[<>]=?$
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
string · min: 2Optional

Hex-encoded Clarity value (e.g. "0x0100000000000000000000000000000001")

Example: 0x0100000000000000000000000000000001Pattern: ^(0x)?([0-9a-fA-F]{2})+$
Responses
200

Success

application/json

Response to a GET request for Clarity Data/MARF/MapEntry value

datastringRequired

Hex-encoded 0x prefixed string of the MARF value

Pattern: ^0x[0-9a-f]+$
proofstringOptional

Hex-encoded 0x prefixed string of the Merkle proof for the data. Empty string if proof not requested.

Pattern: ^(0x[0-9a-f]+)?$
post/v2/map_entry/{deployer_address}/{contract_name}/{map_name}
POST /v2/map_entry/{deployer_address}/{contract_name}/{map_name} HTTP/1.1
Host: localhost:20443
Content-Type: application/json
Accept: */*
Content-Length: 38

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

Get contract source

get
/v2/contracts/source/{deployer_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
deployer_addressstring · min: 28 · max: 41Required

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

Example: SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0Pattern: ^S[PTMN][0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26,39}$
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

GET request to get contract source

sourcestringRequired
publish_heightintegerRequired

Block height at which the contract was published (32-bit unsigned integer)

proofstringOptional

Hex-encoded 0x prefixed string of the Merkle proof for the contract source

Pattern: ^0x[0-9a-f]+$
get/v2/contracts/source/{deployer_address}/{contract_name}
GET /v2/contracts/source/{deployer_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
/v2/contracts/call-read/{deployer_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
deployer_addressstring · min: 28 · max: 41Required

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

Example: SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0Pattern: ^S[PTMN][0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26,39}$
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: 128Required

A valid Clarity name. Must either:

  • Start with a letter and contain only letters, numbers, and [-_!?+<>=/*]
  • Be exactly one of the special characters: - + = * /
  • Be a comparison operator: < > <= >=
Pattern: ^[a-zA-Z]([a-zA-Z0-9]|[-_!?+<>=/*])*$|^[-+=/*]$|^[<>]=?$
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

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

senderstring · min: 28 · max: 41RequiredExample: SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0Pattern: ^S[PTMN][0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26,39}$
sponsorstring · min: 28 · max: 170OptionalExample: SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0Pattern: ^S[PTMN][0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26,39}(\.[a-zA-Z]([a-zA-Z0-9]|[-_]){0,127})?$
argumentsstring[]Required

An array of hex serialized Clarity values

Responses
200

Function executed successfully

application/json

The result of a read-only function call.

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

{
  "sender": "SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0",
  "sponsor": "SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0",
  "arguments": [
    "text"
  ]
}
{
  "okay": true,
  "result": "0x0100000000000000000000000000000001"
}

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

post
/v3/contracts/fast-call-read/{deployer_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
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
deployer_addressstring · min: 28 · max: 41Required

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

Example: SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0Pattern: ^S[PTMN][0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26,39}$
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: 128Required

A valid Clarity name. Must either:

  • Start with a letter and contain only letters, numbers, and [-_!?+<>=/*]
  • Be exactly one of the special characters: - + = * /
  • Be a comparison operator: < > <= >=
Pattern: ^[a-zA-Z]([a-zA-Z0-9]|[-_!?+<>=/*])*$|^[-+=/*]$|^[<>]=?$
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

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

senderstring · min: 28 · max: 41RequiredExample: SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0Pattern: ^S[PTMN][0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26,39}$
sponsorstring · min: 28 · max: 170OptionalExample: SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0Pattern: ^S[PTMN][0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26,39}(\.[a-zA-Z]([a-zA-Z0-9]|[-_]){0,127})?$
argumentsstring[]Required

An array of hex serialized Clarity values

Responses
200

Function executed successfully

application/json

The result of a read-only function call.

or
post/v3/contracts/fast-call-read/{deployer_address}/{contract_name}/{function_name}
POST /v3/contracts/fast-call-read/{deployer_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
/v2/traits/{deployer_address}/{contract_name}/{trait_deployer_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
deployer_addressstring · min: 28 · max: 41Required

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

Example: SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0Pattern: ^S[PTMN][0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26,39}$
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_deployer_addressstring · min: 28 · max: 41Required

Stacks address of the trait-defining contract.

Example: SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0Pattern: ^S[PTMN][0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26,39}$
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: 128Required

A valid Clarity name. Must either:

  • Start with a letter and contain only letters, numbers, and [-_!?+<>=/*]
  • Be exactly one of the special characters: - + = * /
  • Be a comparison operator: < > <= >=
Example: some-traitPattern: ^[a-zA-Z]([a-zA-Z0-9]|[-_!?+<>=/*])*$|^[-+=/*]$|^[<>]=?$
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

GET request to get trait implementation information

is_implementedbooleanRequired
get/v2/traits/{deployer_address}/{contract_name}/{trait_deployer_address}/{trait_contract_name}/{trait_name}
GET /v2/traits/{deployer_address}/{contract_name}/{trait_deployer_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
/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

Response to a GET request for Clarity Data/MARF/MapEntry value

datastringRequired

Hex-encoded 0x prefixed string of the MARF value

Pattern: ^0x[0-9a-f]+$
proofstringOptional

Hex-encoded 0x prefixed string of the Merkle proof for the data. Empty string if proof not requested.

Pattern: ^(0x[0-9a-f]+)?$
get/v2/clarity/marf/{marf_key_hash}
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
/v2/clarity/metadata/{deployer_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
deployer_addressstring · min: 28 · max: 41Required

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

Example: SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0Pattern: ^S[PTMN][0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26,39}$
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. Must be either:

  • "analysis" for contract analysis data
  • "vm-metadata::N::TYPE" where N is the epoch (1-2 digits) and TYPE is one of: contract, contract-size, contract-src, contract-data-size, or a valid Clarity name
Example: analysisPattern: ^(analysis)|(vm-metadata::\d{1,2}::(contract|contract-size|contract-src|contract-data-size|[a-zA-Z]([a-zA-Z0-9]|[-_!?+<>=/*])*))$
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

Response of get clarity metadata request

datastringRequired

Metadata value

get/v2/clarity/metadata/{deployer_address}/{contract_name}/{clarity_metadata_key}
GET /v2/clarity/metadata/{deployer_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
/v2/constant_val/{deployer_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
deployer_addressstring · min: 28 · max: 41Required

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

Example: SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0Pattern: ^S[PTMN][0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26,39}$
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: 128Required

A valid Clarity name. Must either:

  • Start with a letter and contain only letters, numbers, and [-_!?+<>=/*]
  • Be exactly one of the special characters: - + = * /
  • Be a comparison operator: < > <= >=
Pattern: ^[a-zA-Z]([a-zA-Z0-9]|[-_!?+<>=/*])*$|^[-+=/*]$|^[<>]=?$
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

Response of get constant val request

datastringRequired

Hex-encoded 0x prefixed string of clarity value.

Pattern: ^0x[0-9a-f]+$
get/v2/constant_val/{deployer_address}/{contract_name}/{constant_name}
GET /v2/constant_val/{deployer_address}/{contract_name}/{constant_name} HTTP/1.1
Host: localhost:20443
Accept: */*

{
  "data": "0x01ce0123456789abcdef"
}

Get contract data variable

get
/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: 41Required

Standard Stacks address (standard principal, not contract principal). Must be 28-41 characters long using Stacks c32check format.

Example: SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0Pattern: ^S[PTMN][0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26,39}$
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_namestring · min: 1 · max: 128Required

A valid Clarity name. Must either:

  • Start with a letter and contain only letters, numbers, and [-_!?+<>=/*]
  • Be exactly one of the special characters: - + = * /
  • Be a comparison operator: < > <= >=
Pattern: ^[a-zA-Z]([a-zA-Z0-9]|[-_!?+<>=/*])*$|^[-+=/*]$|^[<>]=?$
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

Response to a GET request for Clarity Data/MARF/MapEntry value

datastringRequired

Hex-encoded 0x prefixed string of the MARF value

Pattern: ^0x[0-9a-f]+$
proofstringOptional

Hex-encoded 0x prefixed string of the Merkle proof for the data. Empty string if proof not requested.

Pattern: ^(0x[0-9a-f]+)?$
get/v2/data_var/{principal}/{contract_name}/{var_name}
GET /v2/data_var/{principal}/{contract_name}/{var_name} HTTP/1.1
Host: localhost:20443
Accept: */*

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

Last updated

Was this helpful?