The main repository of this library is hosted on Codeberg. If you are viewing this anywhere else, it is just a mirror. Please use the Codeberg repository for collaboration. Thank you!
This is a Common Lisp Client for the Stacks REST API, hosted by Hiro. The official Documentation can be found on here.
- execute (almost) all GET requests and get-stx-testnet-tokens faucet.
- network support: mainnet (default) and testnet
- output types: hash-table (default), json, alist
- static type checking & further input validation
This library is now on Ultralisp (not yet on quicklisp). You can either set up Ultralisp or put it manually in the local-project folder (or any other folder visible to quicklisp) and then load it via:
(ql:quickload :stacks-api)Alternatively, you can load it with asdf:load-system. However then you need to manually make sure all dependencies are installed before.
Main package nickname is “stacks”.
The API request-functions from the API references are transferred to names according to the Lisp Naming Guidelines: lowercase and separated by single dashes (-). The parameters are same as in the API reference: lower-case and with underscore. Only the array-parameter (type, tx_id, asset_identifiers) have a [] at the end: (tx_id[], type[] asset_identifiers[]).
Inputs are statically type-checked at run time by default. Additional input validation is implemented for certain parameters. Array parameters need to be supplied as quoted list (see examples). All numbers are non-negative / positive integers. Boolean values are t or nil as usual in lisp.
By default, functions query the mainnet (exemption: get-stx-testnet-tokens). You can change the network by setting the global variable *network/ast to “testnet” (or “mainnet”).
(setf *network* "testnet")Default output type is hash-table. Other options are alist, or (raw) json. The setting can be adjusted with the global variable *output/ast .
(setf *output* :json)(in-package :stacks-api)(get-account-balances "SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-info"
:until_block "64500")(get-account-stx-balances "SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-info"
:until_block "65000")(get-account-transactions "SP5C5J1AVSD63C0PEH965TGFDT1CQWFJY37DTZW5"
:limit 10
:offset 1
:height 1000
:unanchored nil)(get-account-transaction-information-for-specific-transaction
"SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.staking-helper"
"0x0356c8a0662be5186652bcf70669471c65829400479caef769d5b2d0db871d31")(get-account-transactions-including-stx-transfers-for-each-transaction
"SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9")(get-the-latest-nonce-used-by-an-account
"SP3E1NPCV8QE4DXPC618VFW3ZFA8QPBD8HCS22KF2")(get-account-assets "SP1Z92MPDQEWZXW36VX71Q25HKF5K2EPCJ304F275")(get-inbound-stx-transfers "SP1Z92MPDQEWZXW36VX71Q25HKF5K2EPCJ304F275")(get-account-info "SP1TCA7QER9J9NKCKBB78K48TADDFC2GXYM3QQV3X")(get-mempool-transactions :recipient_address "SP5C5J1AVSD63C0PEH965TGFDT1CQWFJY37DTZW5")(get-recent-blocks :offset 10)(get-block-by-hash "0x8c1100bc445873c53eeb5446946c97a70114c7fa8624aa7f8fd73cd3ebb51246")(get-block-by-height 1000)(get-block-by-burnchain-block-hash "0x0000000000000000000469320514f215cf176237696d0f8be97cad0a8de1b5d7")(get-block-by-burnchain-height 742673)(get-stx-testnet-tokens :address "your-testnet-adddress")(get-estimated-fee)(fungible-tokens-metadata-list)(fungible-tokens-metadata-for-contract-id "SP2C2YFP12AJZB4MABJBAJ55XECVS7E4PMMZ89YZR.usda-token")(get-core-api-info)(api-status)(get-the-network-target-block-time)(get-a-given-network-target-block-time "mainnet")(get-total-and-unlocked-stx-supply :height 12000)(get-total-stx-supply-in-plain-text-format)(get-circulating-stx-supply-in-plain-text-format)(get-total-and-unlocked-stx-supply-legacy)(get-proof-of-transfer-details)(get-recent-microblocks)(get-microblock "0x72f05f5135caf2a17c8a993e7357072d7a91f1f74925543b12b93c22181b396d")(get-the-list-of-current-transactions-that-belong-to-unanchored-microblocks)(get-namespace-price "app")(get-name-price "100.btc")(get-all-namespaces)(get-namespace-names "btc")(get-all-names)(get-name-details "100.btc")(get-zone-file "11street.btc")(get-names-owned-by-address "stacks" "SP3PW4MC0CZE0FY7MFTKGM7C2DCCXZ24SD0JWJTFT")(non-fungible-token-holdings
:principal "SPNWZ5V2TPWGQGVDR6T7B6RQ4XMGZ4PXTEE0VQ0S.marketplace-v3"
:asset_identifiers[] '("SPQZF23W7SEYBFG5JQ496NMY0G7379SRYEDREMSV.Candy::candy"))(non-fungible-token-history
:asset_identifier "SP2X0TZ59D5SZ8ACQ6YMCHHNR2ZN51Z32E2CJ173.the-explorer-guild::The-Explorer-Guild"
:value "0x0100000000000000000000000000000803")(non-fungible-token-mints
:asset_identifier "SP2X0TZ59D5SZ8ACQ6YMCHHNR2ZN51Z32E2CJ173.the-explorer-guild::The-Explorer-Guild")(search "0x589f73b5cb3f14ae96a9413dfc78fe2e59eff6bd4ddfe76746578884246dd63f")(get-contract-info "SP213KNHB5QD308TEESY1ZMX1BP8EZDPG4JWD0MEA.web4")(get-contract-events "SP000000000000000000002Q6VF78.genesis")(get-contract-interface "SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9" "collateral-rebalancing-pool-v1")(get-contract-source "SP2PABAF9FTAJYNFZH93XENAJ8FVY99RRM50D2JG9" "nft-trait"
:proof 0)(get-recent-reward-slot-holders)(get-recent-reward-slot-holder-entries-for-the-given-address "1BFfc2e6Kk82ut7S3C5yaN3pWRxEFRLLu5")(get-recent-burnchain-reward-recipients)(get-recent-burnchain-reward-for-the-given-recipient "1BFfc2e6Kk82ut7S3C5yaN3pWRxEFRLLu5")(get-total-burnchain-rewards-for-the-given-recipient "1BFfc2e6Kk82ut7S3C5yaN3pWRxEFRLLu5")(get-recent-transactions
:type[] '("coinbase" "contract_call"))(get-mempool-transactions)(get-dropped-mempool-transactions)(get-list-of-details-for-transactions
:tx_id[] '("0xea052bfb2b80732f392e1a16be30be41d84b8bc1bdcf259f58f4b1b5339de452"
"0x8506a60971a586dcfaf01d758e9ff34d3b2fcd4ffea655e3ca759cbe18a6e4db"))(get-transaction "0xeca4233a2ef466e3d311510f391f93d3e783cb050deea755fec5d3ffa1d8bf5c"
:unanchored t
:event_limit 5
:event_offset 1)(get-raw-transaction "0xef7e5b73e6cc55140c5374ce21bc4454476ed0650676cc9c653740b7d2fb4c4a")(transactions-by-block-hash "0x589f73b5cb3f14ae96a9413dfc78fe2e59eff6bd4ddfe76746578884246dd63f")(transactions-by-block-height 1540
:limit 10
:offset 3
:unanchored nil)(transactions-for-address "SP22PCWZ9EJMHV4PHVS0C8H3B3E4Q079ZHY6CXDS1")- REST GET:
- Non-Fungible Tokens metadata functions (non-fungible-tokens-metadata-list & non-fungible-tokens-metadata-for-contract-id) are not activated on public hiro node
- POST requests:
- faucet: add-testnet-btc-tokens-to-address fees: get-approximate-fees-for-the-given-transaction
- rosetta: (only get-list-of-available-networks working)
- Smart Contracts: get-specific-data-map-inside-a-contract, call-read-only-function
- Transactions: broadcast-raw-transaction
- Websocket: real-time updates for
- account-transactions
- recent blocks
- recent-microblocks
- mempool-transactions
- JSON output validation
- warn if there are no results
- advanced input validation
- query specific parts of contracts: (get-read-only-functions, get-maps, etc.)
- more detailed analysis (and tracking?) for SIP 09 Non-fungible token and SIP 10 fungible tokens.
- contract interaction (functions, variables, maps, token)
- creating valid signed transactions
- connect to a local API node
- cross validation with local bitcoin node (https://github.com/rodentrabies/bp)
Feel free to contribute by opening issues, pull request, feature requests etc. Your help is much appreciated.
(C) 2022 Kilian M. Haemmerle ([email protected])
Licensed under the AGPLv3 License.