# Smart Contracts
Endpoints for interacting with Clarity smart contracts.
## Get contract interface
> Get contract interface using a \`deployer\_address\` and \`contract name\`
```json
{"openapi":"3.1.0","info":{"title":"Stacks 3.0+ RPC API","version":"1.0.0"},"tags":[{"name":"Smart Contracts","description":"Endpoints for interacting with Clarity smart contracts."}],"servers":[{"url":"http://localhost:20443","description":"Local Stacks Node"},{"url":"https://api.mainnet.hiro.so","description":"Stacks Mainnet API"},{"url":"https://api.testnet.hiro.so","description":"Stacks Testnet API"}],"security":[],"paths":{"/v2/contracts/interface/{deployer_address}/{contract_name}":{"get":{"summary":"Get contract interface","description":"Get contract interface using a `deployer_address` and `contract name`","tags":["Smart Contracts"],"operationId":"getContractInterface","parameters":[{"name":"deployer_address","in":"path","required":true,"description":"Standard Stacks address (e.g. `SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0`).\nMust be 28-41 characters long using Stacks c32check format.\n","schema":{"type":"string","pattern":"^S[PTMN][0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26,39}$","minLength":28,"maxLength":41}},{"name":"contract_name","in":"path","required":true,"description":"Contract name. Must start with a letter and can contain letters, numbers,\nhyphens, and underscores. Maximum length is 40 characters for new contracts.\nLegacy contracts may have names up to 128 characters.\n","schema":{"type":"string","pattern":"^[a-zA-Z]([a-zA-Z0-9]|[-_]){0,127}$","minLength":1,"maxLength":128}},{"name":"tip","in":"query","schema":{"type":"string","pattern":"^(latest|[0-9a-f]{64})?$","maxLength":64},"description":"Stacks chain tip to query from. Options:\n- (empty/omitted): Use latest anchored tip (canonical confirmed state)\n- `latest`: Use latest known tip including unconfirmed microblocks\n- `{block_id}`: Use specific block ID (64 hex characters)\n"}],"responses":{"200":{"description":"Contract interface","content":{"application/json":{"schema":{"description":"The interface of a Clarity smart contract.","type":"object","required":["functions","variables","maps","fungible_tokens","non_fungible_tokens","epoch","clarity_version"],"$defs":{"ClarityType":{"description":"Represents a Clarity type. It can be a simple string for primitive types or a nested object for complex types like lists and tuples.","oneOf":[{"type":"string","description":"Simple primitive type (e.g., 'int', 'uint', 'bool', 'principal')"},{"type":"object","description":"List type","required":["list"],"properties":{"list":{"type":"object","required":["type"],"properties":{"type":{"description":"Type of list elements","type":"object","additionalProperties":true},"length":{"type":"integer","description":"Fixed length for list types"}}}}},{"type":"object","description":"Tuple type","required":["tuple"],"properties":{"tuple":{"type":"array","items":{"type":"object","required":["name","type"],"properties":{"name":{"type":"string","description":"Field name in the tuple"},"type":{"description":"Type of the tuple field","type":"object","additionalProperties":true}}}}}},{"type":"object","description":"Response type","required":["response"],"properties":{"response":{"type":"object","required":["ok","error"],"properties":{"ok":{"description":"Success type","type":"object","additionalProperties":true},"error":{"description":"Error type","type":"object","additionalProperties":true}}}}},{"type":"object","description":"Optional type","required":["optional"],"properties":{"optional":{"description":"Wrapped optional type","type":"object","additionalProperties":true}}},{"type":"object","description":"Buffer type","required":["buffer"],"properties":{"buffer":{"type":"object","required":["length"],"properties":{"length":{"type":"integer","description":"Fixed length for buffer types"}}}}},{"type":"object","description":"ASCII string type with fixed maximum length","required":["string-ascii"],"properties":{"string-ascii":{"type":"object","required":["length"],"properties":{"length":{"type":"integer","description":"Maximum number of characters (ASCII)"}}}}},{"type":"object","description":"UTF-8 string type with fixed maximum length","required":["string-utf8"],"properties":{"string-utf8":{"type":"object","required":["length"],"properties":{"length":{"type":"integer","description":"Maximum number of code-points (UTF-8)"}}}}}]}},"properties":{"functions":{"type":"array","description":"List of defined methods","items":{"type":"object","required":["name","access","args","outputs"],"properties":{"name":{"type":"string"},"access":{"type":"string","enum":["public","private","read_only"]},"args":{"type":"array","items":{"type":"object","required":["name","type"],"properties":{"name":{"type":"string"},"type":{"description":"Represents a Clarity type. It can be a simple string for primitive types or a nested object for complex types like lists and tuples.","type":"object","additionalProperties":true}}}},"outputs":{"type":"object","required":["type"],"properties":{"type":{"description":"Represents a Clarity type. It can be a simple string for primitive types or a nested object for complex types like lists and tuples.","type":"object","additionalProperties":true}}}}}},"variables":{"type":"array","description":"List of defined constants","items":{"type":"object","required":["name","type","access"],"properties":{"name":{"type":"string"},"type":{"description":"Represents a Clarity type. It can be a simple string for primitive types or a nested object for complex types like lists and tuples.","type":"object","additionalProperties":true},"access":{"type":"string","enum":["constant","variable"]}}}},"maps":{"type":"array","description":"List of defined data-maps","items":{"type":"object","required":["name","key","value"],"properties":{"name":{"type":"string"},"key":{"description":"Represents a Clarity type. It can be a simple string for primitive types or a nested object for complex types like lists and tuples.","type":"object","additionalProperties":true},"value":{"description":"Represents a Clarity type. It can be a simple string for primitive types or a nested object for complex types like lists and tuples.","type":"object","additionalProperties":true}}}},"fungible_tokens":{"type":"array","description":"List of fungible tokens in the contract","items":{"type":"object","required":["name"],"properties":{"name":{"type":"string"}}}},"non_fungible_tokens":{"type":"array","description":"List of non-fungible tokens in the contract","items":{"type":"object","required":["name","type"],"properties":{"name":{"type":"string"},"type":{"description":"Represents a Clarity type. It can be a simple string for primitive types or a nested object for complex types like lists and tuples.","type":"object","additionalProperties":true}}}},"epoch":{"type":"string","description":"Stacks epoch identifier (e.g., \"Epoch30\")."},"clarity_version":{"type":"string","description":"Clarity language version used by this contract.","enum":["Clarity1","Clarity2","Clarity3"]}}}}}},"400":{"description":"Bad request","content":{"text/plain":{"schema":{"type":"string"}}}},"404":{"description":"Not found","content":{"text/plain":{"schema":{"type":"string"}}}},"500":{"description":"Internal Server Error","content":{"text/plain":{"schema":{"type":"string"}}}}}}}}}
```
## Get specific data-map inside a contract
> 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.
```json
{"openapi":"3.1.0","info":{"title":"Stacks 3.0+ RPC API","version":"1.0.0"},"tags":[{"name":"Smart Contracts","description":"Endpoints for interacting with Clarity smart contracts."}],"servers":[{"url":"http://localhost:20443","description":"Local Stacks Node"},{"url":"https://api.mainnet.hiro.so","description":"Stacks Mainnet API"},{"url":"https://api.testnet.hiro.so","description":"Stacks Testnet API"}],"security":[],"paths":{"/v2/map_entry/{deployer_address}/{contract_name}/{map_name}":{"post":{"summary":"Get specific data-map inside a contract","tags":["Smart Contracts"],"operationId":"getContractDataMapEntry","description":"Attempt to fetch data from a contract data map. The contract is\nidentified with [Stacks Address] and [Contract Name] in the URL path.\nThe map is identified with [Map Name].\n\nThe key to lookup in the map is supplied via the POST body. This should\nbe supplied as the hex string serialization of the key (which should be\na Clarity value). Note, this is a JSON string.\n\nThe response is a JSON object with the following properties:\n- `data`: The hex serialization of the map response. Note that map\n responses are Clarity option types, for non-existent values, this is\n a serialized none, and for all other responses, it is a serialized\n (some ...) object.\n- `proof`: The hex serialization of the Merkle proof for the data.\n","parameters":[{"name":"deployer_address","in":"path","required":true,"description":"Standard Stacks address (e.g. `SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0`).\nMust be 28-41 characters long using Stacks c32check format.\n","schema":{"type":"string","pattern":"^S[PTMN][0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26,39}$","minLength":28,"maxLength":41}},{"name":"contract_name","in":"path","required":true,"description":"Contract name. Must start with a letter and can contain letters, numbers,\nhyphens, and underscores. Maximum length is 40 characters for new contracts.\nLegacy contracts may have names up to 128 characters.\n","schema":{"type":"string","pattern":"^[a-zA-Z]([a-zA-Z0-9]|[-_]){0,127}$","minLength":1,"maxLength":128}},{"name":"map_name","in":"path","required":true,"schema":{"type":"string","description":"A valid Clarity name. Must either:\n- Start with a letter and contain only letters, numbers, and [-_!?+<>=/*]\n- Be exactly one of the special characters: - + = * /\n- Be a comparison operator: < > <= >=\n","pattern":"^[a-zA-Z]([a-zA-Z0-9]|[-_!?+<>=/*])*$|^[-+=/*]$|^[<>]=?$","minLength":1,"maxLength":128}},{"name":"proof","in":"query","schema":{"type":"integer","enum":[0,1],"default":1},"description":"Controls MARF proof inclusion in response. Set to 1 (default) to include proof, 0 to exclude.\nInvalid values default to 0 (no proof).\n"},{"name":"tip","in":"query","schema":{"type":"string","pattern":"^(latest|[0-9a-f]{64})?$","maxLength":64},"description":"Stacks chain tip to query from. Options:\n- (empty/omitted): Use latest anchored tip (canonical confirmed state)\n- `latest`: Use latest known tip including unconfirmed microblocks\n- `{block_id}`: Use specific block ID (64 hex characters)\n"}],"requestBody":{"description":"Hex string serialization of the lookup key (which should be a Clarity value)","required":true,"content":{"application/json":{"schema":{"type":"string","minLength":2,"pattern":"^(0x)?([0-9a-fA-F]{2})+$","description":"Hex-encoded Clarity value (e.g. \"0x0100000000000000000000000000000001\")"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Response to a GET request for Clarity Data/MARF/MapEntry value","type":"object","required":["data"],"properties":{"data":{"type":"string","description":"Hex-encoded 0x prefixed string of the MARF value","pattern":"^0x[0-9a-f]+$"},"proof":{"type":"string","description":"Hex-encoded 0x prefixed string of the Merkle proof for the data. Empty string if proof not requested.","pattern":"^(0x[0-9a-f]+)?$"}}}}}},"400":{"description":"Bad request","content":{"text/plain":{"schema":{"type":"string"}}}},"404":{"description":"Not found","content":{"text/plain":{"schema":{"type":"string"}}}},"500":{"description":"Internal Server Error","content":{"text/plain":{"schema":{"type":"string"}}}}}}}}}
```
## Get contract source
> 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.
```json
{"openapi":"3.1.0","info":{"title":"Stacks 3.0+ RPC API","version":"1.0.0"},"tags":[{"name":"Smart Contracts","description":"Endpoints for interacting with Clarity smart contracts."}],"servers":[{"url":"http://localhost:20443","description":"Local Stacks Node"},{"url":"https://api.mainnet.hiro.so","description":"Stacks Mainnet API"},{"url":"https://api.testnet.hiro.so","description":"Stacks Testnet API"}],"security":[],"paths":{"/v2/contracts/source/{deployer_address}/{contract_name}":{"get":{"summary":"Get contract source","tags":["Smart Contracts"],"operationId":"getContractSource","description":"Returns the Clarity source code of a given contract, along with the\nblock height it was published in, and the MARF proof for the data.\n","parameters":[{"name":"deployer_address","in":"path","required":true,"description":"Standard Stacks address (e.g. `SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0`).\nMust be 28-41 characters long using Stacks c32check format.\n","schema":{"type":"string","pattern":"^S[PTMN][0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26,39}$","minLength":28,"maxLength":41}},{"name":"contract_name","in":"path","required":true,"description":"Contract name. Must start with a letter and can contain letters, numbers,\nhyphens, and underscores. Maximum length is 40 characters for new contracts.\nLegacy contracts may have names up to 128 characters.\n","schema":{"type":"string","pattern":"^[a-zA-Z]([a-zA-Z0-9]|[-_]){0,127}$","minLength":1,"maxLength":128}},{"name":"proof","in":"query","schema":{"type":"integer","enum":[0,1],"default":1},"description":"Controls MARF proof inclusion in response. Set to 1 (default) to include proof, 0 to exclude.\nInvalid values default to 0 (no proof).\n"},{"name":"tip","in":"query","schema":{"type":"string","pattern":"^(latest|[0-9a-f]{64})?$","maxLength":64},"description":"Stacks chain tip to query from. Options:\n- (empty/omitted): Use latest anchored tip (canonical confirmed state)\n- `latest`: Use latest known tip including unconfirmed microblocks\n- `{block_id}`: Use specific block ID (64 hex characters)\n"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"GET request to get contract source","type":"object","additionalProperties":false,"required":["source","publish_height"],"properties":{"source":{"type":"string"},"publish_height":{"type":"integer","minimum":0,"description":"Block height at which the contract was published (32-bit unsigned integer)"},"proof":{"type":"string","description":"Hex-encoded 0x prefixed string of the Merkle proof for the contract source","pattern":"^0x[0-9a-f]+$"}}}}}},"400":{"description":"Bad request","content":{"text/plain":{"schema":{"type":"string"}}}},"404":{"description":"Not found","content":{"text/plain":{"schema":{"type":"string"}}}},"500":{"description":"Internal Server Error","content":{"text/plain":{"schema":{"type":"string"}}}}}}}}}
```
## Call read-only function
> 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.
```json
{"openapi":"3.1.0","info":{"title":"Stacks 3.0+ RPC API","version":"1.0.0"},"tags":[{"name":"Smart Contracts","description":"Endpoints for interacting with Clarity smart contracts."}],"servers":[{"url":"http://localhost:20443","description":"Local Stacks Node"},{"url":"https://api.mainnet.hiro.so","description":"Stacks Mainnet API"},{"url":"https://api.testnet.hiro.so","description":"Stacks Testnet API"}],"security":[],"paths":{"/v2/contracts/call-read/{deployer_address}/{contract_name}/{function_name}":{"post":{"summary":"Call read-only function","description":"Call a read-only public function on a given contract.\n\nThe contract is identified with [Stacks Address] and [Contract Name] in the URL path.\nThe function is identified with [Function Name].\n\nThe arguments to the function are supplied via the POST body.\nThis should be a JSON object with two main properties:\n- `sender` which should be a standard Stacks address\n- `arguments` which should be an array of hex-encoded Clarity values.\n","tags":["Smart Contracts"],"operationId":"callReadOnlyFunction","parameters":[{"name":"deployer_address","in":"path","required":true,"description":"Standard Stacks address (e.g. `SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0`).\nMust be 28-41 characters long using Stacks c32check format.\n","schema":{"type":"string","pattern":"^S[PTMN][0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26,39}$","minLength":28,"maxLength":41}},{"name":"contract_name","in":"path","required":true,"description":"Contract name. Must start with a letter and can contain letters, numbers,\nhyphens, and underscores. Maximum length is 40 characters for new contracts.\nLegacy contracts may have names up to 128 characters.\n","schema":{"type":"string","pattern":"^[a-zA-Z]([a-zA-Z0-9]|[-_]){0,127}$","minLength":1,"maxLength":128}},{"name":"function_name","in":"path","required":true,"schema":{"type":"string","description":"A valid Clarity name. Must either:\n- Start with a letter and contain only letters, numbers, and [-_!?+<>=/*]\n- Be exactly one of the special characters: - + = * /\n- Be a comparison operator: < > <= >=\n","pattern":"^[a-zA-Z]([a-zA-Z0-9]|[-_!?+<>=/*])*$|^[-+=/*]$|^[<>]=?$","minLength":1,"maxLength":128}},{"name":"tip","in":"query","schema":{"type":"string","pattern":"^(latest|[0-9a-f]{64})?$","maxLength":64},"description":"Stacks chain tip to query from. Options:\n- (empty/omitted): Use latest anchored tip (canonical confirmed state)\n- `latest`: Use latest known tip including unconfirmed microblocks\n- `{block_id}`: Use specific block ID (64 hex characters)\n"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"description":"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","type":"object","additionalProperties":false,"required":["sender","arguments"],"properties":{"sender":{"description":"The simulated tx-sender.","allOf":[{"type":"string","pattern":"^S[PTMN][0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26,39}$","minLength":28,"maxLength":41}]},"sponsor":{"description":"The simulated sponsor address.","allOf":[{"type":"string","pattern":"^S[PTMN][0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26,39}(\\.[a-zA-Z]([a-zA-Z0-9]|[-_]){0,127})?$","minLength":28,"maxLength":170}]},"arguments":{"type":"array","description":"An array of hex serialized Clarity values","items":{"type":"string","pattern":"^(0x)?([0-9a-fA-F]{2})+$","description":"Hex-encoded Clarity value (optionally prefixed with 0x)"}}}}}}},"responses":{"200":{"description":"Function executed successfully","content":{"application/json":{"schema":{"description":"The result of a read-only function call.","oneOf":[{"type":"object","description":"Successful read-only function call result","required":["okay","result"],"properties":{"okay":{"type":"boolean","enum":[true]},"result":{"type":"string","description":"Hex-encoded Clarity value of the successful result."}}},{"type":"object","description":"Failed read-only function call result","required":["okay","cause"],"properties":{"okay":{"type":"boolean","enum":[false]},"cause":{"type":"string","description":"A string representing the cause of the error."}}}]}}}},"400":{"description":"Bad request","content":{"text/plain":{"schema":{"type":"string"}}}},"404":{"description":"Not found","content":{"text/plain":{"schema":{"type":"string"}}}},"500":{"description":"Internal Server Error","content":{"text/plain":{"schema":{"type":"string"}}}}}}}}}
```
## Call read-only function in fast mode (no cost and memory tracking)
> 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.\*\*
```json
{"openapi":"3.1.0","info":{"title":"Stacks 3.0+ RPC API","version":"1.0.0"},"tags":[{"name":"Smart Contracts","description":"Endpoints for interacting with Clarity smart contracts."}],"servers":[{"url":"http://localhost:20443","description":"Local Stacks Node"},{"url":"https://api.mainnet.hiro.so","description":"Stacks Mainnet API"},{"url":"https://api.testnet.hiro.so","description":"Stacks Testnet API"}],"security":[{"rpcAuth":[]}],"components":{"securitySchemes":{"rpcAuth":{"type":"apiKey","in":"header","name":"authorization","description":"Plain-text secret value that must exactly equal the node's\nconfigured password, which is set as `connection_options.auth_token`\nin the node's configuration file.\n"}}},"paths":{"/v3/contracts/fast-call-read/{deployer_address}/{contract_name}/{function_name}":{"post":{"summary":"Call read-only function in fast mode (no cost and memory tracking)","description":"Call a read-only public function on a given smart contract without cost tracking.\n\nThe contract is identified with [Stacks Address] and [Contract Name] in the URL path.\nThe function is identified with [Function Name].\n\nThe arguments to the function are supplied via the POST body.\nThis should be a JSON object with two main properties:\n- `sender` which should be a standard Stacks address\n- `arguments` which should be an array of hex-encoded Clarity values.\n\n**This API endpoint requires a basic Authorization header.**\n","tags":["Smart Contracts"],"operationId":"fastCallReadOnlyFunction","parameters":[{"name":"deployer_address","in":"path","required":true,"description":"Standard Stacks address (e.g. `SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0`).\nMust be 28-41 characters long using Stacks c32check format.\n","schema":{"type":"string","pattern":"^S[PTMN][0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26,39}$","minLength":28,"maxLength":41}},{"name":"contract_name","in":"path","required":true,"description":"Contract name. Must start with a letter and can contain letters, numbers,\nhyphens, and underscores. Maximum length is 40 characters for new contracts.\nLegacy contracts may have names up to 128 characters.\n","schema":{"type":"string","pattern":"^[a-zA-Z]([a-zA-Z0-9]|[-_]){0,127}$","minLength":1,"maxLength":128}},{"name":"function_name","in":"path","required":true,"schema":{"type":"string","description":"A valid Clarity name. Must either:\n- Start with a letter and contain only letters, numbers, and [-_!?+<>=/*]\n- Be exactly one of the special characters: - + = * /\n- Be a comparison operator: < > <= >=\n","pattern":"^[a-zA-Z]([a-zA-Z0-9]|[-_!?+<>=/*])*$|^[-+=/*]$|^[<>]=?$","minLength":1,"maxLength":128}},{"name":"tip","in":"query","schema":{"type":"string","pattern":"^(latest|[0-9a-f]{64})?$","maxLength":64},"description":"Stacks chain tip to query from. Options:\n- (empty/omitted): Use latest anchored tip (canonical confirmed state)\n- `latest`: Use latest known tip including unconfirmed microblocks\n- `{block_id}`: Use specific block ID (64 hex characters)\n"}],"requestBody":{"description":"map of arguments and the simulated tx-sender where sender is either a Contract identifier or a normal Stacks address, and arguments is an array of hex serialized Clarity values.","required":true,"content":{"application/json":{"schema":{"description":"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","type":"object","additionalProperties":false,"required":["sender","arguments"],"properties":{"sender":{"description":"The simulated tx-sender.","allOf":[{"type":"string","pattern":"^S[PTMN][0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26,39}$","minLength":28,"maxLength":41}]},"sponsor":{"description":"The simulated sponsor address.","allOf":[{"type":"string","pattern":"^S[PTMN][0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26,39}(\\.[a-zA-Z]([a-zA-Z0-9]|[-_]){0,127})?$","minLength":28,"maxLength":170}]},"arguments":{"type":"array","description":"An array of hex serialized Clarity values","items":{"type":"string","pattern":"^(0x)?([0-9a-fA-F]{2})+$","description":"Hex-encoded Clarity value (optionally prefixed with 0x)"}}}}}}},"responses":{"200":{"description":"Function executed successfully","content":{"application/json":{"schema":{"description":"The result of a read-only function call.","oneOf":[{"type":"object","description":"Successful read-only function call result","required":["okay","result"],"properties":{"okay":{"type":"boolean","enum":[true]},"result":{"type":"string","description":"Hex-encoded Clarity value of the successful result."}}},{"type":"object","description":"Failed read-only function call result","required":["okay","cause"],"properties":{"okay":{"type":"boolean","enum":[false]},"cause":{"type":"string","description":"A string representing the cause of the error."}}}]}}}},"400":{"description":"Bad request","content":{"text/plain":{"schema":{"type":"string"}}}},"401":{"description":"Unauthorized. Invalid or missing authentication token.","content":{"text/plain":{"schema":{"type":"string"}}}},"404":{"description":"Not found","content":{"text/plain":{"schema":{"type":"string"}}}},"408":{"description":"Timeout","content":{"text/plain":{"schema":{"type":"string"}}}},"500":{"description":"Internal Server Error","content":{"text/plain":{"schema":{"type":"string"}}}}}}}}}
```
## Get trait implementation details
> Determine whether or not a specified trait is implemented (either\
> explicitly or implicitly) within a given contract.
```json
{"openapi":"3.1.0","info":{"title":"Stacks 3.0+ RPC API","version":"1.0.0"},"tags":[{"name":"Smart Contracts","description":"Endpoints for interacting with Clarity smart contracts."}],"servers":[{"url":"http://localhost:20443","description":"Local Stacks Node"},{"url":"https://api.mainnet.hiro.so","description":"Stacks Mainnet API"},{"url":"https://api.testnet.hiro.so","description":"Stacks Testnet API"}],"security":[],"paths":{"/v2/traits/{deployer_address}/{contract_name}/{trait_deployer_address}/{trait_contract_name}/{trait_name}":{"get":{"summary":"Get trait implementation details","description":"Determine whether or not a specified trait is implemented (either\nexplicitly or implicitly) within a given contract.\n","tags":["Smart Contracts"],"operationId":"checkTraitImplementation","parameters":[{"name":"deployer_address","in":"path","required":true,"description":"Standard Stacks address (e.g. `SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0`).\nMust be 28-41 characters long using Stacks c32check format.\n","schema":{"type":"string","pattern":"^S[PTMN][0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26,39}$","minLength":28,"maxLength":41}},{"name":"contract_name","in":"path","required":true,"description":"Contract name. Must start with a letter and can contain letters, numbers,\nhyphens, and underscores. Maximum length is 40 characters for new contracts.\nLegacy contracts may have names up to 128 characters.\n","schema":{"type":"string","pattern":"^[a-zA-Z]([a-zA-Z0-9]|[-_]){0,127}$","minLength":1,"maxLength":128}},{"name":"trait_deployer_address","in":"path","required":true,"description":"Stacks address of the trait-defining contract.\n","schema":{"type":"string","pattern":"^S[PTMN][0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26,39}$","minLength":28,"maxLength":41}},{"name":"trait_contract_name","in":"path","required":true,"description":"Contract name of the trait-defining contract.","schema":{"type":"string","pattern":"^[a-zA-Z]([a-zA-Z0-9]|[-_]){0,127}$","minLength":1,"maxLength":128}},{"name":"trait_name","in":"path","required":true,"schema":{"type":"string","description":"A valid Clarity name. Must either:\n- Start with a letter and contain only letters, numbers, and [-_!?+<>=/*]\n- Be exactly one of the special characters: - + = * /\n- Be a comparison operator: < > <= >=\n","pattern":"^[a-zA-Z]([a-zA-Z0-9]|[-_!?+<>=/*])*$|^[-+=/*]$|^[<>]=?$","minLength":1,"maxLength":128}},{"name":"tip","in":"query","schema":{"type":"string","pattern":"^(latest|[0-9a-f]{64})?$","maxLength":64},"description":"Stacks chain tip to query from. Options:\n- (empty/omitted): Use latest anchored tip (canonical confirmed state)\n- `latest`: Use latest known tip including unconfirmed microblocks\n- `{block_id}`: Use specific block ID (64 hex characters)\n"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"GET request to get trait implementation information","type":"object","additionalProperties":false,"required":["is_implemented"],"properties":{"is_implemented":{"type":"boolean"}}}}}},"400":{"description":"Bad request","content":{"text/plain":{"schema":{"type":"string"}}}},"404":{"description":"Not found","content":{"text/plain":{"schema":{"type":"string"}}}}}}}}}
```
## Get the MARF value for a given key
> Attempt to fetch the value of a MARF key. The key is a 64-character\
> hex string representing the MARF node hash.
```json
{"openapi":"3.1.0","info":{"title":"Stacks 3.0+ RPC API","version":"1.0.0"},"tags":[{"name":"Smart Contracts","description":"Endpoints for interacting with Clarity smart contracts."}],"servers":[{"url":"http://localhost:20443","description":"Local Stacks Node"},{"url":"https://api.mainnet.hiro.so","description":"Stacks Mainnet API"},{"url":"https://api.testnet.hiro.so","description":"Stacks Testnet API"}],"security":[],"paths":{"/v2/clarity/marf/{marf_key_hash}":{"get":{"summary":"Get the MARF value for a given key","tags":["Smart Contracts"],"operationId":"getClarityMarfValue","description":"Attempt to fetch the value of a MARF key. The key is a 64-character\nhex string representing the MARF node hash.\n","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Response to a GET request for Clarity Data/MARF/MapEntry value","type":"object","required":["data"],"properties":{"data":{"type":"string","description":"Hex-encoded 0x prefixed string of the MARF value","pattern":"^0x[0-9a-f]+$"},"proof":{"type":"string","description":"Hex-encoded 0x prefixed string of the Merkle proof for the data. Empty string if proof not requested.","pattern":"^(0x[0-9a-f]+)?$"}}}}}},"400":{"description":"Bad request","content":{"text/plain":{"schema":{"type":"string"}}}},"404":{"description":"Not found","content":{"text/plain":{"schema":{"type":"string"}}}}},"parameters":[{"name":"marf_key_hash","in":"path","required":true,"description":"The 64-character hex-encoded hash of the MARF key.","schema":{"type":"string","pattern":"^[0-9a-f]{64}$","minLength":64,"maxLength":64}},{"name":"proof","in":"query","schema":{"type":"integer","enum":[0,1],"default":1},"description":"Controls MARF proof inclusion in response. Set to 1 (default) to include proof, 0 to exclude.\nInvalid values default to 0 (no proof).\n"},{"name":"tip","in":"query","schema":{"type":"string","pattern":"^(latest|[0-9a-f]{64})?$","maxLength":64},"description":"Stacks chain tip to query from. Options:\n- (empty/omitted): Use latest anchored tip (canonical confirmed state)\n- `latest`: Use latest known tip including unconfirmed microblocks\n- `{block_id}`: Use specific block ID (64 hex characters)\n"}]}}}}
```
## Get the contract metadata for the 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.
```json
{"openapi":"3.1.0","info":{"title":"Stacks 3.0+ RPC API","version":"1.0.0"},"tags":[{"name":"Smart Contracts","description":"Endpoints for interacting with Clarity smart contracts."}],"servers":[{"url":"http://localhost:20443","description":"Local Stacks Node"},{"url":"https://api.mainnet.hiro.so","description":"Stacks Mainnet API"},{"url":"https://api.testnet.hiro.so","description":"Stacks Testnet API"}],"security":[],"paths":{"/v2/clarity/metadata/{deployer_address}/{contract_name}/{clarity_metadata_key}":{"get":{"summary":"Get the contract metadata for the metadata key","tags":["Smart Contracts"],"operationId":"getClarityMetadata","description":"Attempt to fetch the metadata of a contract. The contract is identified\nwith [Contract Address] and [Contract Name] in the URL path. The metadata\nkey is identified with [Clarity Metadata Key].\n\nIn the response, `data` is formatted as JSON.\n","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Response of get clarity metadata request","type":"object","required":["data"],"properties":{"data":{"type":"string","description":"Metadata value"}}}}}},"400":{"description":"Bad request","content":{"text/plain":{"schema":{"type":"string"}}}},"404":{"description":"Not found","content":{"text/plain":{"schema":{"type":"string"}}}},"500":{"description":"Internal Server Error","content":{"text/plain":{"schema":{"type":"string"}}}}},"parameters":[{"name":"deployer_address","in":"path","required":true,"description":"Standard Stacks address (e.g. `SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0`).\nMust be 28-41 characters long using Stacks c32check format.\n","schema":{"type":"string","pattern":"^S[PTMN][0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26,39}$","minLength":28,"maxLength":41}},{"name":"contract_name","in":"path","required":true,"description":"Contract name. Must start with a letter and can contain letters, numbers,\nhyphens, and underscores. Maximum length is 40 characters for new contracts.\nLegacy contracts may have names up to 128 characters.\n","schema":{"type":"string","pattern":"^[a-zA-Z]([a-zA-Z0-9]|[-_]){0,127}$","minLength":1,"maxLength":128}},{"name":"clarity_metadata_key","in":"path","required":true,"description":"Metadata key. Must be either:\n- \"analysis\" for contract analysis data\n- \"vm-metadata::N::TYPE\" where N is the epoch (1-2 digits) and TYPE is one of:\n contract, contract-size, contract-src, contract-data-size, or a valid Clarity name\n","schema":{"type":"string","pattern":"^(analysis)|(vm-metadata::\\d{1,2}::(contract|contract-size|contract-src|contract-data-size|[a-zA-Z]([a-zA-Z0-9]|[-_!?+<>=/*])*))$"}},{"name":"tip","in":"query","schema":{"type":"string","pattern":"^(latest|[0-9a-f]{64})?$","maxLength":64},"description":"Stacks chain tip to query from. Options:\n- (empty/omitted): Use latest anchored tip (canonical confirmed state)\n- `latest`: Use latest known tip including unconfirmed microblocks\n- `{block_id}`: Use specific block ID (64 hex characters)\n"}]}}}}
```
## Get the value of a constant inside a contract
> 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.
```json
{"openapi":"3.1.0","info":{"title":"Stacks 3.0+ RPC API","version":"1.0.0"},"tags":[{"name":"Smart Contracts","description":"Endpoints for interacting with Clarity smart contracts."}],"servers":[{"url":"http://localhost:20443","description":"Local Stacks Node"},{"url":"https://api.mainnet.hiro.so","description":"Stacks Mainnet API"},{"url":"https://api.testnet.hiro.so","description":"Stacks Testnet API"}],"security":[],"paths":{"/v2/constant_val/{deployer_address}/{contract_name}/{constant_name}":{"get":{"summary":"Get the value of a constant inside a contract","tags":["Smart Contracts"],"operationId":"getConstantValue","description":"Attempt to fetch the value of a constant inside a contract. The contract\nis identified with [Stacks Address] and [Contract Name] in the URL path.\nThe constant is identified with [Constant Name].\n\nIn the response, `data` is the hex serialization of the constant value.\n","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Response of get constant val request","type":"object","required":["data"],"properties":{"data":{"type":"string","description":"Hex-encoded 0x prefixed string of clarity value.","pattern":"^0x[0-9a-f]+$"}}}}}},"400":{"description":"Bad request","content":{"text/plain":{"schema":{"type":"string"}}}},"404":{"description":"Not found","content":{"text/plain":{"schema":{"type":"string"}}}},"500":{"description":"Internal Server Error","content":{"text/plain":{"schema":{"type":"string"}}}}},"parameters":[{"name":"deployer_address","in":"path","required":true,"description":"Standard Stacks address (e.g. `SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0`).\nMust be 28-41 characters long using Stacks c32check format.\n","schema":{"type":"string","pattern":"^S[PTMN][0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26,39}$","minLength":28,"maxLength":41}},{"name":"contract_name","in":"path","required":true,"description":"Contract name. Must start with a letter and can contain letters, numbers,\nhyphens, and underscores. Maximum length is 40 characters for new contracts.\nLegacy contracts may have names up to 128 characters.\n","schema":{"type":"string","pattern":"^[a-zA-Z]([a-zA-Z0-9]|[-_]){0,127}$","minLength":1,"maxLength":128}},{"name":"constant_name","in":"path","required":true,"schema":{"type":"string","description":"A valid Clarity name. Must either:\n- Start with a letter and contain only letters, numbers, and [-_!?+<>=/*]\n- Be exactly one of the special characters: - + = * /\n- Be a comparison operator: < > <= >=\n","pattern":"^[a-zA-Z]([a-zA-Z0-9]|[-_!?+<>=/*])*$|^[-+=/*]$|^[<>]=?$","minLength":1,"maxLength":128}},{"name":"tip","in":"query","schema":{"type":"string","pattern":"^(latest|[0-9a-f]{64})?$","maxLength":64},"description":"Stacks chain tip to query from. Options:\n- (empty/omitted): Use latest anchored tip (canonical confirmed state)\n- `latest`: Use latest known tip including unconfirmed microblocks\n- `{block_id}`: Use specific block ID (64 hex characters)\n"}]}}}}
```
## Get contract data variable
> Fetch a data variable from a smart contract.\
> Returns the raw hex-encoded value of the variable.
```json
{"openapi":"3.1.0","info":{"title":"Stacks 3.0+ RPC API","version":"1.0.0"},"tags":[{"name":"Smart Contracts","description":"Endpoints for interacting with Clarity smart contracts."}],"servers":[{"url":"http://localhost:20443","description":"Local Stacks Node"},{"url":"https://api.mainnet.hiro.so","description":"Stacks Mainnet API"},{"url":"https://api.testnet.hiro.so","description":"Stacks Testnet API"}],"security":[],"paths":{"/v2/data_var/{principal}/{contract_name}/{var_name}":{"get":{"summary":"Get contract data variable","tags":["Smart Contracts"],"operationId":"getContractDataVariable","description":"Fetch a data variable from a smart contract.\nReturns the raw hex-encoded value of the variable.\n","parameters":[{"name":"principal","in":"path","required":true,"description":"Standard Stacks address (standard principal, not contract principal).\nMust be 28-41 characters long using Stacks c32check format.\n","schema":{"type":"string","pattern":"^S[PTMN][0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26,39}$","minLength":28,"maxLength":41}},{"name":"contract_name","in":"path","required":true,"description":"Contract name. Must start with a letter and can contain letters, numbers,\nhyphens, and underscores. Maximum length is 40 characters for new contracts.\nLegacy contracts may have names up to 128 characters.\n","schema":{"type":"string","pattern":"^[a-zA-Z]([a-zA-Z0-9]|[-_]){0,127}$","minLength":1,"maxLength":128}},{"name":"var_name","in":"path","required":true,"description":"Variable name (must be a valid Clarity name)","schema":{"type":"string","description":"A valid Clarity name. Must either:\n- Start with a letter and contain only letters, numbers, and [-_!?+<>=/*]\n- Be exactly one of the special characters: - + = * /\n- Be a comparison operator: < > <= >=\n","pattern":"^[a-zA-Z]([a-zA-Z0-9]|[-_!?+<>=/*])*$|^[-+=/*]$|^[<>]=?$","minLength":1,"maxLength":128}},{"name":"proof","in":"query","schema":{"type":"integer","enum":[0,1],"default":1},"description":"Controls MARF proof inclusion in response. Set to 1 (default) to include proof, 0 to exclude.\nInvalid values default to 0 (no proof).\n"},{"name":"tip","in":"query","schema":{"type":"string","pattern":"^(latest|[0-9a-f]{64})?$","maxLength":64},"description":"Stacks chain tip to query from. Options:\n- (empty/omitted): Use latest anchored tip (canonical confirmed state)\n- `latest`: Use latest known tip including unconfirmed microblocks\n- `{block_id}`: Use specific block ID (64 hex characters)\n"}],"responses":{"200":{"description":"The data variable value","content":{"application/json":{"schema":{"description":"Response to a GET request for Clarity Data/MARF/MapEntry value","type":"object","required":["data"],"properties":{"data":{"type":"string","description":"Hex-encoded 0x prefixed string of the MARF value","pattern":"^0x[0-9a-f]+$"},"proof":{"type":"string","description":"Hex-encoded 0x prefixed string of the Merkle proof for the data. Empty string if proof not requested.","pattern":"^(0x[0-9a-f]+)?$"}}}}}},"400":{"description":"Bad request","content":{"text/plain":{"schema":{"type":"string"}}}},"404":{"description":"Not found","content":{"text/plain":{"schema":{"type":"string"}}}}}}}}}
```