Contracts and AST

These endpoints return a contract's parsed abstract syntax tree (AST). Every expression has an id and a span (line:col-line:col, 1-based, inclusive), which is how a trace node maps back to source.

Contract AST

GET /contracts/{contract_id}

The AST, source and ABI of a deployed contract. 404 if no contract is deployed under that id.

curl -s https://api.stxer.xyz/contracts/SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.amm-pool-v2-01

Response (abbreviated):

{
  "contract_id": "SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.amm-pool-v2-01",
  "tx_id": "0x6ca4ab5626410f6ba1c12e77d00a93912a24a486fc6af8f163925c358e159602",
  "block_height": 152429,
  "canonical": true,
  "clarity_version": 2,
  "source_code": "(use-trait ft-trait .trait-sip-010.sip-010-trait)\n(define-constant ERR-NOT-AUTHORIZED (err u1000))\n…",
  "abi": { "epoch": "Epoch25", "functions": [ "…" ], "maps": [], "…": "…" },
  "expressions": [
    { "id": 1, "span": "1:1-1:49", "expr": { "list": [
      { "id": 2, "expr": { "atom": "use-trait" }, "span": "1:2-1:10" }, "…" ] } }
  ],
  "top_level_expression_sorting": [0, 1, 2, "…"],
  "referenced_traits": { "ft-trait": { "trait_definition": "SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.trait-sip-010.sip-010-trait", "trait_definition_type": "Imported" } },
  "implemented_traits": [],
  "cached": true
}

Responses are served with a long-lived cache-control; cache them on your side too.

AST from a deploy transaction

GET /contracts/by-deploy/{txid}

Parses the source carried by a contract-deploy transaction. Unlike GET /contracts/{id}, this also answers for a deploy that aborted and left no contract on chain. txid may carry a 0x prefix. 404 if the transaction is unknown or is not a contract deploy.

curl -s https://api.stxer.xyz/contracts/by-deploy/0xa083ff31b409cc34598e4a0d68ac0edeff3f3ae591c7c2625eaeb419a7204e03

The response has the AST fields above plus tx_id, contract_id, block_height, burn_block_height, tx_status, source_code, clarity_version and epoch.

Parse source

POST /contracts:parse

Parses source you supply, for contracts that are not on chain (for example, deployed inside a simulation).

Body field	Required	Meaning
contract_id	yes	The id the contract would have, e.g. SP….my-contract
source_code	yes	Clarity source
clarity_version	no	"1" … "6", default "6"
epoch	no	Epoch30 … Epoch40, default Epoch40

curl -s -X POST https://api.stxer.xyz/contracts:parse \
  -H 'content-type: application/json' \
  -d '{"contract_id":"SP000000000000000000002Q6VF78.hello","source_code":"(define-read-only (hello) (ok \"Hello, World!\"))"}'

{
  "contract_identifier": "SP000000000000000000002Q6VF78.hello",
  "expressions": [
    { "id": 1, "span": "1:1-1:47", "expr": { "list": [
      { "id": 2, "expr": { "atom": "define-read-only" }, "span": "1:2-1:17" },
      { "id": 3, "expr": { "list": [ { "id": 4, "expr": { "atom": "hello" }, "span": "1:20-1:24" } ] }, "span": "1:19-1:25" },
      { "id": 5, "expr": { "list": [
        { "id": 6, "expr": { "atom": "ok" }, "span": "1:28-1:29" },
        { "id": 7, "expr": { "literal_value": "0d0000000d48656c6c6f2c20576f726c6421" }, "span": "1:31-1:45" } ] }, "span": "1:27-1:46" }
    ] } }
  ],
  "top_level_expression_sorting": [0],
  "referenced_traits": {},
  "implemented_traits": []
}