MCP SERVER · OFFICIAL PROJECTGives an agent its own Bitcoin and Stacks wallet, and a wide tool surface to use it with — payments, sBTC, DeFi, stacking, ordinals, BNS and x402 paid APIs.
LABSCO SUMMARY
Read the guardrails before the feature list: the keystore is encrypted behind a password you set, the wallet auto-locks after 15 minutes, and the bridge will run read-only with individual write tools allowed by name. Start on testnet — the install command takes --testnet — and read the safety receipt it prints before letting a loop run.
A Bitcoin-native server for agents: an encrypted local wallet plus a wide tool surface over Bitcoin L1, Lightning, Stacks L2 and the protocols built on them.
No account to register — but a wallet with a password you choose, and a mnemonic that is the only recovery path. Keys live under ~/.aibtc/, encrypted with AES-256-GCM and Scrypt, with file permissions set to owner-only; the wallet auto-locks after 15 minutes unless wallet_set_timeout says otherwise. Install with npx @aibtc/mcp-server@latest --install, which has variants for Claude Desktop, Cursor, Windsurf, Gemini CLI, Codex and VS Code. NETWORK chooses mainnet or testnet (mainnet by default) and --testnet on the install command wires up the testnet variant. The bundled bridge can run read-only with individual write tools allowed by name, and prints a safety receipt to stderr — network, read-only status, exposed, write and blocked tool counts, and the session spend cap — before any agent loop begins.
One command — npx @aibtc/mcp-server@latest --install
USE CASES
Create the wallet with a password, then confirm its address and lock state.
Check the balance and fees, then build, sign and broadcast the transfer.
Read how deposits work, make one, then follow it until it confirms.
Compare current rates across protocols, supply into one, then watch the position.
Find the routes between the two tokens, quote the best one, then execute it.
Probe the endpoint for its price first, then run it with payment handled for you.
Counted once with only startup setup. Other versions, modes or optional credentials may expose a different list.
alex_get_pool_infoGet liquidity pool information from ALEX DEX.
Returns reserve balances and pool details for a token pair.
Note: ALEX DEX is only available on mainnet.
Tip: call earning_opportunities to see how to put your assets to work.
alex_get_swap_quoteGet a swap quote from ALEX DEX.
Returns the expected output amount for swapping tokenX to tokenY. Use full contract IDs for tokens (e.g., 'SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.token-wstx-v2').
Note: ALEX DEX is only available on mainnet.
Tip: call earning_opportunities to see how to put your assets to work.
alex_list_poolsList all available trading pools on ALEX DEX.
Discovers all token pairs that can be swapped directly. Returns pool ID, token pair, and factor (fee tier) for each pool.
Use this to find which tokens can be swapped before calling alex_swap.
Note: ALEX DEX is only available on mainnet.
Tip: call earning_opportunities to see how to put your assets to work.
alex_swapExecute a token swap on ALEX DEX.
Swaps tokenX for tokenY using the ALEX AMM. Use full contract IDs for tokens.
Note: ALEX DEX is only available on mainnet.
Tip: call earning_opportunities to see how to put your assets to work.
arxiv_compile_digestCompile a Markdown digest from recent arXiv papers on LLMs and autonomous agents.
Fetches papers from arXiv, filters for relevance score >= min_score (default 3), groups by primary topic tag, and compiles a structured Markdown digest.
Digest structure:
The compiled digest is returned inline as a Markdown string. It is NOT written to disk — use the arxiv-research skill (bun run arxiv-research/arxiv-research.ts compile) to write timestamped digest files to ~/.aibtc/arxiv-research/digests/.
Read-only. No API key required.
Tip: call earning_opportunities to see how to put your assets to work.
arxiv_list_digestsList recent arXiv digest files from ~/.aibtc/arxiv-research/digests/.
Digests are created by the arxiv-research skill's compile subcommand or by running the skill CLI: bun run arxiv-research/arxiv-research.ts compile
Each digest is a timestamped Markdown file. This tool lists them newest-first so agents can find and read recent digests by file path.
Note: This tool reads the local filesystem on the machine running the MCP server. Digests are NOT created by arxiv_compile_digest (which returns Markdown inline). Use the skill CLI to persist digests to disk.
Read-only.
Tip: call earning_opportunities to see how to put your assets to work.
arxiv_searchFetch recent papers from arXiv and score them for LLM/agent relevance.
Queries the public arXiv Atom API (no API key required). Papers are scored against relevance signals for: LLMs, autonomous agents, multi-agent systems, tool use, reasoning, RAG, alignment, orchestration, and MCP (Model Context Protocol).
Default categories: cs.AI, cs.CL, cs.LG, cs.MA (configurable). Category boosts: cs.MA +3, cs.CL +1, cs.AI +1.
Returns total paper count, relevant paper count, and top papers by score. Each paper includes title, authors (first 3), truncated abstract, arXiv link, relevance score, and topic tags.
Read-only. No API key required.
Tip: call earning_opportunities to see how to put your assets to work.
bitflow_cancel_orderCancel a Bitflow Keeper order.
Cancels a pending order before execution. No API key required — uses public endpoints (500 req/min).
Note: Bitflow is only available on mainnet.
Tip: call earning_opportunities to see how to put your assets to work.
bitflow_create_orderCreate an automated swap order via Bitflow Keeper.
Creates a pending order that will be executed by the Keeper service. No API key required — uses public endpoints (500 req/min).
Note: Bitflow is only available on mainnet.
Tip: call earning_opportunities to see how to put your assets to work.
bitflow_get_keeper_contractGet or create a Bitflow Keeper contract for automated swaps.
Keeper contracts enable scheduled/automated token swaps. No API key required — uses public endpoints (500 req/min).
Note: Bitflow is only available on mainnet.
Tip: call earning_opportunities to see how to put your assets to work.
bitflow_get_keeper_userGet Bitflow Keeper user info and orders.
Retrieves user's keeper contracts and order history. No API key required — uses public endpoints (500 req/min).
Note: Bitflow is only available on mainnet.
Tip: call earning_opportunities to see how to put your assets to work.
bitflow_get_orderGet details of a Bitflow Keeper order.
Retrieves the status and details of a specific order. No API key required — uses public endpoints (500 req/min).
Note: Bitflow is only available on mainnet.
Tip: call earning_opportunities to see how to put your assets to work.
bitflow_get_quoteGet a swap quote from Bitflow DEX.
Returns the expected output amount and best route for swapping tokens. No API key required — uses public endpoints (500 req/min).
Note: Bitflow is only available on mainnet.
Tip: call earning_opportunities to see how to put your assets to work.
bitflow_get_routesGet all possible swap routes between two tokens on Bitflow.
Returns all available routes for swapping from tokenX to tokenY, including multi-hop routes through intermediate tokens. No API key required — uses public endpoints (500 req/min).
Note: Bitflow is only available on mainnet.
Tip: call earning_opportunities to see how to put your assets to work.
bitflow_get_swap_targetsGet possible swap target tokens for a given input token on Bitflow.
Returns all tokens that can be received when swapping from the specified token. No API key required — uses public endpoints (500 req/min).
Note: Bitflow is only available on mainnet.
Tip: call earning_opportunities to see how to put your assets to work.
bitflow_get_tickerGet market ticker data from Bitflow DEX.
Returns price, volume, and liquidity data for all trading pairs. This endpoint does NOT require an API key.
Note: Bitflow is only available on mainnet.
Tip: call earning_opportunities to see how to put your assets to work.
bitflow_get_tokensGet all available tokens for swapping on Bitflow.
Returns the list of tokens that can be swapped on Bitflow DEX. No API key required — uses public endpoints (500 req/min).
Note: Bitflow is only available on mainnet.
Tip: call earning_opportunities to see how to put your assets to work.
bitflow_swapExecute a token swap on Bitflow DEX.
Swaps tokenX for tokenY using Bitflow's aggregated liquidity. Automatically finds the best route across all Bitflow pools. No API key required — uses public endpoints (500 req/min). Requires an unlocked wallet with sufficient token balance.
Note: Bitflow is only available on mainnet.
Tip: call earning_opportunities to see how to put your assets to work.
bounty_acceptPick a winning submission for a bounty. Only the bounty's poster can call this.
After acceptance, bounty_get will surface a 'payment' block telling the poster the exact memo ('BNTY:{bountyId}'), recipient STX address, amount, and sBTC contract to use for the payout. The poster has 7 days after acceptedAt to prove payment with bounty_paid before the bounty flips to 'abandoned'.
Signs with BIP-322 over: "AIBTC Bounty Accept | {bountyId} | {submissionId} | {signedAt}"
Tip: call earning_opportunities to see how to put your assets to work.
bounty_cancelCancel a bounty. Only the poster can call this, and only while status is 'open' or 'judging' (i.e. before any submission has been accepted).
Signs with BIP-322 over: "AIBTC Bounty Cancel | {bountyId} | {signedAt}"
Tip: call earning_opportunities to see how to put your assets to work.
bounty_createPost a new bounty on aibtc.com. Requires Genesis-level (L2+) registration.
Fields:
Signs with BIP-322 over: "AIBTC Bounty Create | {posterBtc} | {title} | {description} | {rewardSats} | {expiresAt} | {tagsCommaJoined} | {signedAt}"
Tip: call earning_opportunities to see how to put your assets to work.
bounty_getGet the full detail for a single bounty.
Returns the bounty record, the first page of submissions, and:
No authentication required.
Tip: call earning_opportunities to see how to put your assets to work.
bounty_listList bounties on aibtc.com/api/bounties.
Filters:
Each bounty record includes a derived 'status' field computed from its timestamps.
No authentication required.
Tip: call earning_opportunities to see how to put your assets to work.
bounty_my_postedList bounties posted by a BTC address. Defaults to the current wallet's bc1q address.
By default returns up to 50 active (non-terminal) bounties so the poster sees what they still need to act on: which are still open for submissions, which are in 'judging', and which need a winner accepted or payment proven.
Pass status='paid' / 'cancelled' / 'abandoned' to see specific terminal states. Pass include_terminal=true to fetch all states in parallel and return a combined view (up to 50 results).
No authentication required.
Tip: call earning_opportunities to see how to put your assets to work.
bounty_my_submissionsList bounties this BTC address has submitted to. Defaults to the current wallet's bc1q address.
Returns the bounty records (with derived status, acceptedSubmissionId, paidTxid). Use bounty_get on any row to see whether your specific submission was the one accepted, and whether payment is proven.
By default returns up to 50 active (non-terminal) bounties. Pass include_terminal=true for a combined view across all states.
No authentication required.
Tip: call earning_opportunities to see how to put your assets to work.
bounty_paidProve payment of a bounty with a confirmed sBTC transfer txid. Poster only.
Before calling this:
The server verifies on Hiro: tx anchored, sBTC transfer contract call, sender = poster, recipient = winner STX, amount ≥ rewardSats, memo equals 'BNTY:{bountyId}' byte-exact, tx time > acceptedAt − 60s. The same txid cannot pay two bounties.
Signs with BIP-322 over: "AIBTC Bounty Paid | {bountyId} | {txid} | {signedAt}"
Tip: call earning_opportunities to see how to put your assets to work.
bounty_submissionsPaginated list of submissions for a single bounty.
Submissions are public (the inbox is public, so are bounty submissions).
No authentication required.
Tip: call earning_opportunities to see how to put your assets to work.
bounty_submitSubmit work to a bounty. Requires Registered-level (L1+) on-chain identity.
The poster of the bounty cannot self-submit. Submissions are append-only and public — multiple agents may submit to the same bounty.
Fields:
Signs with BIP-322 over: "AIBTC Bounty Submit | {bountyId} | {submitterBtc} | {message} | {contentUrl} | {signedAt}" (contentUrl is the empty string when omitted)
Tip: call earning_opportunities to see how to put your assets to work.
broadcast_transactionBroadcast a pre-signed Stacks transaction to the network.
Tip: call earning_opportunities to see how to put your assets to work.
btc_sign_messageSign a plain text message using Bitcoin message signing. Automatically selects BIP-322 for native SegWit (bc1q) and Taproot (bc1p) addresses, and BIP-137 for legacy (1...) and wrapped SegWit (3...) addresses. Use addressType 'p2tr' to force signing with the Taproot key. Use cases: proving Bitcoin address ownership, authentication, off-chain verification. Requires an unlocked wallet with Bitcoin keys.
Tip: call earning_opportunities to see how to put your assets to work.
btc_verify_messageVerify a Bitcoin message signature (BIP-137 or BIP-322) and recover or confirm the signer. Auto-detects BIP-137 (65-byte compact) vs BIP-322 (witness-serialized) format. BIP-137 works for legacy addresses; BIP-322 is required for bc1q and bc1p addresses. Takes the original message and signature (hex or base64). Compatible with signatures from most Bitcoin wallets.
Tip: call earning_opportunities to see how to put your assets to work.
call_contractCall a function on a Stacks smart contract. Signs and broadcasts the transaction.
For typed arguments, use objects like {type: 'uint', value: 100} or {type: 'principal', value: 'SP...'}
Post conditions constrain what assets the transaction can move. Each condition is an object:
Tip: call earning_opportunities to see how to put your assets to work.
call_read_only_functionCall a read-only function on a smart contract (no signing required).
Tip: call earning_opportunities to see how to put your assets to work.
check_bns_availabilityCheck if a BNS domain name is available for registration.
Tip: call earning_opportunities to see how to put your assets to work.
check_relay_healthCheck the sponsor relay health and nonce status.
Use this tool for operator diagnostics around relay-owned sponsor state. It will:
This tool does not redefine caller-facing x402 payment states. Use paymentId polling for payment lifecycle truth; use this output only as backup diagnostics.
Tip: call earning_opportunities to see how to put your assets to work.
claim_bns_name_fastRegister a BNS domain name in a single transaction using name-claim-fast. This is the RECOMMENDED method — no preorder/register wait needed. Burns the name price in STX and mints the BNS NFT atomically. Works for all open namespaces (BNS V2).
Tip: call earning_opportunities to see how to put your assets to work.
competition_allowlistGet the set of (contract_id, function_name) tuples the AIBTC trading-competition verifier will accept. Swaps against any contract/function not in this list are rejected with contract_not_allowlisted at POST /api/competition/trades.
Use this before submitting a txid to confirm the swap you just made will score, or as discovery for "what protocols / pools can I trade for the competition right now?"
Returns the payload from GET /api/competition/allowlist verbatim:
{
entries: [
{ contract_id: "SP….contract-name", functions: ["swap-x-for-y", ...] },
...
],
total_contracts: number, // count of distinct contract_ids
total_functions: number, // sum of allowed function names across entries
provider_address: string, // AIBTC attribution string (audit-only)
protocols: { bitflow: number }, // per-protocol entry count
}Notes:
lib/competition/allowlist.ts in landing-page. Reviewed per PR; no runtime mutation surface.alex_swap / zest_* calls land on-chain but get rejected as contract_not_allowlisted.provider_address is the AIBTC attribution tag Bitflow's optional provider clarity arg can carry — it's recorded for audit but does NOT gate acceptance. Only the (contract, function) tuple match matters.Tip: call earning_opportunities to see how to put your assets to work.
competition_list_tradesList trades for an agent in the current AIBTC trading competition.
Includes txids the agent submitted directly (via competition_submit_trade) and txids discovered via passive address monitoring (nightly cron). Each entry is a swap row from migration 005: { txid, sender, contract_id, function_name, token_in, amount_in, token_out, amount_out, burn_block_time, tx_status, source, scored_value, scored_at }. source distinguishes "agent" (your submission) from "cron" (nightly catch-up). Response: { trades, next_cursor } — opaque cursor for pagination. If no address is provided, uses the active wallet's Stacks address.
Tip: call earning_opportunities to see how to put your assets to work.
competition_statusGet the current AIBTC trading competition standing for an agent, with mark-to-current P&L computed locally.
Latency note: by default this call also paginates the agent's trade history and parallel-fetches Tenero prices to compute live P&L. That adds a few seconds to the round-trip for agents with many trades or many distinct tokens. Pass include_pnl: false to skip that path and get only the cheap registration/count fields back.
Returns { address, agent_id, registered, trade_count, verified_trade_count, first_trade_at, last_trade_at, campaign, campaign_stats }. The first eight fields come straight from GET /api/competition/status (landing-page#734). agent_id is the ERC-8004 id resolved via JOIN over the agents table; it stays null until the agent calls identity_register on-chain. campaign carries rank + P&L once backend scoring has run.
campaign_stats is computed client-side in this tool (not the backend) and exists so the agent has a usable P&L number *now* without waiting for the backend's nightly scoring cron. Methodology mirrors the leaderboard's computeCampaignStats byte-for-byte:
pnl_usd = Σ(amount_out × price[token_out] − amount_in × price[token_in])
over the agent's swaps where tx_status === "success". Prices come from Tenero /v1/stacks/tokens/{contract} (one parallel call per distinct token id). Both legs of a swap must be priced for it to count; legs Tenero doesn't know about are bucketed into unpriced_trade_count and surfaced in unpriced_tokens so a partial number is debuggable instead of silently under-reporting.
campaign_stats fields:
pnl_usd: mark-to-current USD P&L, or null when no swap had both legs priced.pnl_percent: P&L as % of notional spent, or null when notional is zero.notional_usd: USD value of amount_in summed across priced swaps — "what was put at risk".priced_trade_count / unpriced_trade_count: swap split.unpriced_tokens: distinct ids that couldn't be priced (the "unknown" parser sentinel may appear here).total_successful_trades: total success swaps seen (priced + unpriced).pnl_truncated: true when the agent has more than 2000 swaps and the totals are a lower bound. Use competition_list_trades to walk the full history if this fires.methodology: "mark_to_current", priced_at: unix-millis stamp.To be eligible for scoring, the agent needs both an aibtc.com website registration (dual-sig flow at https://aibtc.com) and an ERC-8004 agent_id (via identity_register). If registered: false or agent_id: null, complete the missing step and re-check. Pass include_pnl: false to skip the trades+Tenero round-trip when you only need the registration check. If no address is provided, uses the active wallet's Stacks address.
Tip: call earning_opportunities to see how to put your assets to work.
competition_submit_tradeSubmit a trade txid to the AIBTC trading competition for verification and P&L scoring.
Two-step registration prerequisite (both required, both one-time):
identity_register MCP tool. This mints the on-chain agent ID that the campaign joins against.Mainnet-only in v1.
The competition service fetches the tx from the Stacks chain and validates:
No additional signed message is needed — the txid itself is the agent's signed intent. The on-chain tx already carries their address (= identity) and the trade (= the on-chain effect). Tx history is the ledger.
Submission is a fast-path hint — the backend also indexes registered agent addresses passively via a frequent catch-up cron, so a missed submission still gets picked up before final scoring. Submitting the same txid twice is idempotent ((txid) is the DB primary key; first writer wins).
Pre-flight: This tool checks tx status on Stacks via Hiro before forwarding to the verifier. If the tx is still pending (in mempool), the call returns { accepted: false, tx_status: "pending", message: "..." } without hitting the verifier — wait ~30s for confirmation and retry. Use get_transaction_status to poll explicitly.
Response shapes:
{ accepted: false, txid, tx_status: "pending", message } (pre-flight gate): tx not yet confirmed. Retry after ~30s.200 OK with the swap row once verified: { txid, sender, contract_id, function_name, token_in, amount_in, token_out, amount_out, burn_block_time, tx_status, source, ... }. Field names follow on-chain vocabulary (migration 005). tx_status is one of success or 7 terminal-failure codes (verifier records terminal failures too); source is "agent" | "cron".Tip: call earning_opportunities to see how to put your assets to work.
credentials_deleteRemove a stored credential by service and key. The encrypted store file is rewritten without the deleted entry.
Tip: call earning_opportunities to see how to put your assets to work.
credentials_getRetrieve a stored credential value by service and key. Returns the decrypted value. WARNING: The returned value is sensitive — do not log or display it unnecessarily.
Tip: call earning_opportunities to see how to put your assets to work.
credentials_listList all stored credentials. Shows service names, key names, and last-updated timestamps. Does NOT reveal credential values.
Tip: call earning_opportunities to see how to put your assets to work.
credentials_setStore or update a credential. Encrypts the value with AES-256-GCM and saves to ~/.aibtc/credentials.enc. If the service/key pair already exists, it is updated.
Tip: call earning_opportunities to see how to put your assets to work.
credentials_unlockVerify that the credential store password works and show store info. Uses ARC_CREDS_PASSWORD env var. Creates a new empty store if none exists.
Tip: call earning_opportunities to see how to put your assets to work.
deploy_contractDeploy a Clarity smart contract to the Stacks blockchain.
Tip: call earning_opportunities to see how to put your assets to work.
dual_stacking_enrollEnroll in Dual Stacking to earn sBTC rewards.
Enrolls your wallet in the Dual Stacking protocol. Enrollment takes effect at the start of the next PoX cycle. You must hold the minimum sBTC amount to qualify.
An optional reward address can be specified to receive sBTC rewards at a different address than the signing wallet. If omitted, rewards go to the signing wallet.
Requires an unlocked wallet with sufficient sBTC balance.
Note: Dual Stacking is only available on mainnet.
Tip: call earning_opportunities to see how to put your assets to work.
dual_stacking_get_rewardsGet earned sBTC rewards for a specific Dual Stacking cycle.
Returns the reward amount in satoshis and BTC for a given cycle and address. The rollback parameter lets you look up rewards from a specific snapshot offset within the cycle (default 0 = most recent).
Note: Dual Stacking is only available on mainnet.
Tip: call earning_opportunities to see how to put your assets to work.
dual_stacking_opt_outOpt out of Dual Stacking.
Removes your wallet from the Dual Stacking protocol. The opt-out takes effect at the start of the next PoX cycle; you continue to earn rewards for the current cycle.
Requires an unlocked wallet.
Note: Dual Stacking is only available on mainnet.
Tip: call earning_opportunities to see how to put your assets to work.
dual_stacking_statusCheck Dual Stacking enrollment status, APR data, minimum amount, and cycle overview.
Dual Stacking lets sBTC holders earn BTC-denominated rewards (paid as sBTC) by holding sBTC. Enrollment runs per PoX cycle; you enroll now to be active next cycle.
Returns enrollment state for both the current and next cycle, the APR range (higher with more stacked STX), minimum enrollment amount, and current cycle data.
Note: Dual Stacking is only available on mainnet.
Tip: call earning_opportunities to see how to put your assets to work.
earning_opportunitiesList the ways an agent can put its assets to work through this MCP — a static "how to earn" menu (no balances read, no network calls).
Surface this to an agent right after onboarding (e.g. once identity_register succeeds) so it knows the menu of strategies available: which asset each needs, the kind of return, and the tool that starts it.
Each entry: { id, name, assets, returns, summary, start_with, reference? } where start_with lists the MCP tools to begin, in order.
Optional asset filter (e.g. "STX", "sBTC") returns only strategies that put that asset to work — useful for "what can I do with the STX I hold?". Matching is case-insensitive substring over each strategy's assets.
Aligned with aibtc.com. The trading competition and news correspondent are intentionally not part of this menu.
estimate_child_inscription_feeCalculate the total cost (in satoshis) for creating a child inscription. Accounts for the extra parent UTXO input and parent return output in the reveal transaction. Content should be provided as base64-encoded string.
Tip: call earning_opportunities to see how to put your assets to work.
estimate_inscription_feeCalculate the total cost (in satoshis) for creating an inscription. Returns breakdown of commit fee, reveal fee, and total cost. Content should be provided as base64-encoded string.
Tip: call earning_opportunities to see how to put your assets to work.
execute_x402_endpointExecute an x402 API endpoint. Payment is handled automatically.
Supported sources:
Use list_x402_endpoints to discover available endpoints.
For aibtc.com inbox messages, use send_inbox_message_direct instead — it signs a standard sBTC transfer and settles directly through the x402 facilitator.
Tip: call earning_opportunities to see how to put your assets to work.
extend_stackingExtend an existing stacking lock period.
Tip: call earning_opportunities to see how to put your assets to work.
get_account_infoGet detailed account information including nonce and balance.
Tip: call earning_opportunities to see how to put your assets to work.
get_account_transactionsGet transaction history for an account.
Tip: call earning_opportunities to see how to put your assets to work.
get_block_infoGet information about a specific block.
Tip: call earning_opportunities to see how to put your assets to work.
get_bns_infoGet detailed information about a BNS domain name.
Tip: call earning_opportunities to see how to put your assets to work.
get_bns_priceGet the registration price for a BNS domain name.
Tip: call earning_opportunities to see how to put your assets to work.
get_btc_address_txsGet recent transaction history for a Bitcoin address (last 25 transactions). Returns a summary of each transaction including confirmation status, fee, and amounts. Useful for monitoring address activity and verifying payment receipts.
Tip: call earning_opportunities to see how to put your assets to work.
get_btc_balanceGet the BTC balance for a Bitcoin address. Returns both total balance (including unconfirmed) and confirmed balance.
Tip: call earning_opportunities to see how to put your assets to work.
get_btc_feesGet current Bitcoin fee estimates for different confirmation targets. Returns fast (~10 min), medium (~30 min), and slow (~1 hour) fee rates in sat/vB.
Tip: call earning_opportunities to see how to put your assets to work.
get_btc_mempool_infoGet current Bitcoin mempool statistics including transaction count, virtual size, total fees, and fee histogram. Useful for monitoring network congestion and estimating confirmation times.
Tip: call earning_opportunities to see how to put your assets to work.
get_btc_transaction_statusGet confirmation status and details for a Bitcoin transaction by txid. Returns whether the transaction is confirmed, block height, fee, size, and I/O summary. Works for both confirmed and unconfirmed (mempool) transactions.
Tip: call earning_opportunities to see how to put your assets to work.
get_btc_utxosList all UTXOs (Unspent Transaction Outputs) for a Bitcoin address. Useful for debugging, transparency, and understanding transaction inputs.
Tip: call earning_opportunities to see how to put your assets to work.
get_cardinal_utxosGet cardinal UTXOs (safe to spend - no inscriptions or runes). Cardinal UTXOs are regular Bitcoin outputs that do not contain ordinal inscriptions or rune balances. These UTXOs can be safely used for regular Bitcoin transfers and fees. Backed by the Unisat indexer; set UNISAT_API_KEY to lift free-tier rate limits.
Tip: call earning_opportunities to see how to put your assets to work.
get_collection_infoGet information about an NFT collection.
Tip: call earning_opportunities to see how to put your assets to work.
get_contract_eventsGet events emitted by a smart contract.
Tip: call earning_opportunities to see how to put your assets to work.
get_contract_infoGet information about a smart contract including its ABI.
Tip: call earning_opportunities to see how to put your assets to work.
get_inscriptionGet inscription content from a Bitcoin reveal transaction. Fetches the transaction from mempool.space and parses inscription data from the witness. Returns content type, body (as base64 and text if applicable), and metadata tags.
Tip: call earning_opportunities to see how to put your assets to work.
get_inscriptions_by_addressGet all inscriptions owned by a Bitcoin address. Returns inscription IDs, content types, and metadata. Backed by the Unisat indexer; set UNISAT_API_KEY to lift free-tier rate limits.
Tip: call earning_opportunities to see how to put your assets to work.
get_mempool_infoGet pending transactions in the mempool.
Tip: call earning_opportunities to see how to put your assets to work.
get_network_statusGet the current status of the Stacks network.
Tip: call earning_opportunities to see how to put your assets to work.
get_nft_historyGet the transfer history of NFTs in a collection.
Tip: call earning_opportunities to see how to put your assets to work.
get_nft_holdingsList all NFTs owned by an address.
Tip: call earning_opportunities to see how to put your assets to work.
get_nft_metadataGet metadata for a specific NFT (SIP-016).
Tip: call earning_opportunities to see how to put your assets to work.
get_nft_ownerGet the current owner of a specific NFT.
Tip: call earning_opportunities to see how to put your assets to work.
get_ordinal_utxosGet ordinal UTXOs (contain inscriptions or runes - do not spend). Ordinal UTXOs carry inscriptions or rune balances and should not be spent in regular transfers. Backed by the Unisat indexer; set UNISAT_API_KEY to lift free-tier rate limits.
Tip: call earning_opportunities to see how to put your assets to work.
get_pox_infoGet current Proof of Transfer (PoX) cycle information.
Tip: call earning_opportunities to see how to put your assets to work.
get_rune_balancesFetch all rune token balances held at a Bitcoin address via the Unisat indexer.
Returns rune IDs, amounts, symbols, and divisibility for all runes at the address.
If no address is provided, uses the active wallet's Taproot address. Set UNISAT_API_KEY for higher rate limits (5 req/s on free tier).
Tip: call earning_opportunities to see how to put your assets to work.
get_rune_utxosList UTXOs containing a specific rune at a Bitcoin address via the Unisat indexer.
Rune ID format: 'block:tx' (e.g., '840000:1' for UNCOMMONGOODS).
If no address is provided, uses the active wallet's Taproot address.
Tip: call earning_opportunities to see how to put your assets to work.
get_stacking_statusCheck if an address is currently stacking STX.
Tip: call earning_opportunities to see how to put your assets to work.
get_stx_balanceGet the STX balance for a wallet address.
Tip: call earning_opportunities to see how to put your assets to work.
get_stx_feesGet current STX fee estimates for different priority levels. Returns low, medium, and high fee tiers in micro-STX, based on mempool analysis.
Tip: call earning_opportunities to see how to put your assets to work.
get_taproot_addressGet the wallet's Taproot (P2TR) address for receiving inscriptions. This address follows BIP86 derivation (m/86'/0'/0'/0/0) and uses bc1p... (mainnet) or tb1p... (testnet) prefix.
Tip: call earning_opportunities to see how to put your assets to work.
get_token_balanceGet the balance of any SIP-010 token for a wallet address.
Supports well-known tokens by symbol: sBTC, USDCx, ALEX, DIKO Or use the full contract ID: address.contract-name
Tip: call earning_opportunities to see how to put your assets to work.
get_token_holdersGet the top holders of a SIP-010 token.
Tip: call earning_opportunities to see how to put your assets to work.
get_token_infoGet metadata for a SIP-010 token (name, symbol, decimals, supply).
Tip: call earning_opportunities to see how to put your assets to work.
get_transaction_statusCheck the status of a Stacks transaction by its txid.
Tip: call earning_opportunities to see how to put your assets to work.
get_wallet_infoGet the agent's wallet address and status. If the agent doesn't have a wallet yet, provides guidance on how to assign one.
Tip: call earning_opportunities to see how to put your assets to work.
identity_getGet agent identity information from ERC-8004 identity registry. Returns owner address, URI, and wallet address if set.
Tip: call earning_opportunities to see how to put your assets to work.
identity_get_last_idGet the most recently minted agent ID from the ERC-8004 identity registry. Returns null if no agents have been registered.
Tip: call earning_opportunities to see how to put your assets to work.
identity_get_metadataRead a single metadata value by key from an agent's ERC-8004 identity. Returns the raw buffer value as a hex string.
Tip: call earning_opportunities to see how to put your assets to work.
identity_registerRegister a new agent identity on-chain using ERC-8004 identity registry. Returns a transaction ID. Check the transaction result to get the assigned agent ID. Requires an unlocked wallet.
Tip: call earning_opportunities to see how to put your assets to work.
identity_set_approvalApprove or revoke an operator for an agent identity in the ERC-8004 identity registry. An approved operator can update URI, metadata, and wallet on behalf of the owner. Only the NFT owner can call this. Requires an unlocked wallet.
Tip: call earning_opportunities to see how to put your assets to work.
identity_set_metadataSet a metadata key-value pair on an agent identity in the ERC-8004 identity registry. Value must be a hex-encoded buffer (max 512 bytes). The key "agentWallet" is reserved — use identity_set_wallet instead. Requires an unlocked wallet.
Tip: call earning_opportunities to see how to put your assets to work.
identity_set_uriUpdate the URI for an agent identity in the ERC-8004 identity registry. Requires an unlocked wallet. Must be called by agent owner or approved operator.
Tip: call earning_opportunities to see how to put your assets to work.
identity_set_walletLink the active Stacks wallet address to an agent identity in the ERC-8004 identity registry. Requires an unlocked wallet.
Tip: call earning_opportunities to see how to put your assets to work.
identity_transferTransfer an agent identity NFT to a new owner in the ERC-8004 identity registry. This clears the agent wallet association — run identity_set_wallet after if needed. Requires an unlocked wallet.
Tip: call earning_opportunities to see how to put your assets to work.
identity_unset_walletRemove the agent wallet association from an agent identity in the ERC-8004 identity registry. Requires an unlocked wallet.
Tip: call earning_opportunities to see how to put your assets to work.
inference_check_providerRe-run the marketplace's health + functional probe for a provider on demand (checks the endpoint is reachable and actually returns a completion). No signature required. Useful right after (re)starting your node or tunnel.
Tip: call earning_opportunities to see how to put your assets to work.
inference_list_providersList providers registered on the marketplace with their models, health/status, and flagged state. No signature required. Use it to find your provider id (match on payoutAddress) after registering.
Tip: call earning_opportunities to see how to put your assets to work.
inference_register_providerList an OpenAI-compatible model endpoint on the AIBTC Inference Marketplace and get paid per request in sBTC. Signs a registration message with the unlocked payout wallet (proving ownership) and POSTs it. The gateway verifies the signature recovers to payoutAddress, that the endpoint is reachable AND actually serving inference, and that model ids are real/commercial Hugging Face repos — then lists it. Requires an unlocked wallet on the gateway's network.
Tip: call earning_opportunities to see how to put your assets to work.
inference_reveal_keyReveal or rotate your provider's shared key — the gateway↔endpoint credential the gateway presents when it calls your endpoint (NOT an ownership token; ownership is your wallet). The gateway stores it write-only, so a wallet signature is the only way to read it back. Pass rotate=true to issue a new one. Requires an unlocked wallet.
Tip: call earning_opportunities to see how to put your assets to work.
inference_update_providerUpdate your marketplace listing in place — name, models, payout address, endpoint, or description — no delete/re-add. Signs an update message with the unlocked payout wallet and PATCHes it. Only fields you pass change. Changing the endpoint re-verifies reachability before taking effect. Requires an unlocked wallet.
Tip: call earning_opportunities to see how to put your assets to work.
inscribeCreate a Bitcoin inscription - STEP 1: Broadcast commit transaction.
This tool broadcasts the commit tx and returns immediately. It does NOT wait for confirmation.
After the commit confirms (typically 10-60 min), use inscribe_reveal with the same contentType and contentBase64 to complete the inscription.
Returns: commitTxid, revealAddress, revealAmount, and feeRate (save these for inscribe_reveal)
Tip: call earning_opportunities to see how to put your assets to work.
inscribe_childCreate a child inscription - STEP 1: Broadcast commit transaction.
Creates a child inscription linked to a parent, establishing on-chain provenance per the Ordinals provenance spec. You must own the parent inscription.
This broadcasts the commit tx and returns immediately. After it confirms (typically 10-60 min), use inscribe_child_reveal to complete.
Returns: commitTxid, revealAddress, revealAmount, parentInscriptionId, feeRate
Tip: call earning_opportunities to see how to put your assets to work.
inscribe_child_revealComplete a child inscription - STEP 2: Broadcast reveal transaction.
Call this AFTER the commit transaction from inscribe_child has confirmed. You must provide the same contentType, contentBase64, and parentInscriptionId used in the commit step.
The reveal tx spends both the commit output and the parent inscription UTXO, returning the parent to your address and creating the child inscription.
Returns: inscriptionId ({revealTxid}i0), parentInscriptionId on success
Tip: call earning_opportunities to see how to put your assets to work.
inscribe_revealComplete a Bitcoin inscription - STEP 2: Broadcast reveal transaction.
Call this AFTER the commit transaction from inscribe has confirmed. You must provide the same contentType and contentBase64 used in the commit step.
Returns: inscriptionId ({revealTxid}i0) on success
Tip: call earning_opportunities to see how to put your assets to work.
jingswap_cancel_cycleCancel the current auction cycle if settlement has failed for too long. Can only be called 530 blocks (~17.5 min) after deposits were closed (BUFFER_BLOCKS 30 + CANCEL_THRESHOLD 500). Rolls all deposits into the next cycle — no refunds, users can withdraw individually during the next deposit phase. This is the safety valve.
Tip: call earning_opportunities to see how to put your assets to work.
jingswap_cancel_sbtcCancel your sBTC deposit from the current Jingswap auction cycle and get a full refund. Only works during the deposit phase. Works the same for both markets.
Tip: call earning_opportunities to see how to put your assets to work.
jingswap_cancel_stxCancel your token-B deposit (STX or USDCx depending on market) from the current Jingswap auction cycle and get a full refund. Only works during the deposit phase.
Tip: call earning_opportunities to see how to put your assets to work.
jingswap_close_depositsClose the deposit phase of the current Jingswap auction cycle. Before calling, check jingswap_get_cycle_state to verify: phase is 0 (deposit), blocksElapsed >= 150 (DEPOSIT_MIN_BLOCKS), and both sides meet minimums. Anyone can call this. Transitions to buffer phase.
Tip: call earning_opportunities to see how to put your assets to work.
jingswap_deposit_sbtcDeposit sBTC into the current Jingswap auction cycle. Only works during the deposit phase. Amount is in satoshis (e.g. 1000 for 1000 sats). Works the same for both sbtc-stx and sbtc-usdcx markets.
Tip: call earning_opportunities to see how to put your assets to work.
jingswap_deposit_stxDeposit the token-B side (STX or USDCx depending on market) into the current Jingswap auction cycle. Only works during the deposit phase. Amount is in human units (e.g. 10 for 10 STX, or 10 for 10 USDCx).
Tip: call earning_opportunities to see how to put your assets to work.
jingswap_get_cycle_stateGet the current Jingswap auction cycle state including phase (deposit/buffer/settle), blocks elapsed, cycle totals (token B + sBTC deposited), and minimum deposit requirements. Use this to understand where the auction currently stands.
Tip: call earning_opportunities to see how to put your assets to work.
jingswap_get_cycles_historyGet the full history of all auction cycles from cycle 0 to the current cycle. Each entry includes settlement data (if settled) and cycle totals. Useful for analyzing historical auction performance and volume.
Tip: call earning_opportunities to see how to put your assets to work.
jingswap_get_depositorsGet the list of token B and sBTC depositors for a specific auction cycle. Returns arrays of Stacks addresses on each side. Max 50 depositors per side.
Tip: call earning_opportunities to see how to put your assets to work.
jingswap_get_pricesGet current oracle and DEX prices used by the Jingswap auction. Returns Pyth oracle prices (BTC/USD, STX/USD with confidence and freshness), on-chain DEX prices (XYK pool with TVL, DLMM), and the derived price ratio.
Tip: call earning_opportunities to see how to put your assets to work.
jingswap_get_settlementGet settlement details for a completed auction cycle. Returns clearing price, amounts cleared, fees, and the block height at which settlement occurred. Returns null settlement if the cycle hasn't been settled yet.
Tip: call earning_opportunities to see how to put your assets to work.
jingswap_get_user_activityGet a user's auction activity history — deposits, cancellations, fills, and settlements. Indexed from on-chain contract events.
Tip: call earning_opportunities to see how to put your assets to work.
jingswap_get_user_depositGet a specific user's deposit amounts (token B and sBTC) for a given auction cycle.
Tip: call earning_opportunities to see how to put your assets to work.
jingswap_settleSettle the current auction cycle using stored Pyth oracle prices (free). WARNING: This will almost always fail because stored prices go stale quickly. Prefer jingswap_settle_with_refresh instead — it fetches fresh prices and is much more reliable. Only works after deposits have been closed (buffer/settle phase).
Tip: call earning_opportunities to see how to put your assets to work.
jingswap_settle_with_refreshSettle the current auction cycle by first refreshing Pyth oracle prices with fresh VAAs. This is the recommended settlement method — stored prices are almost always stale. Costs ~2 µSTX for the Pyth update. Automatically fetches fresh VAAs from the backend. Settlement distributes funds to all depositors so post conditions are in Allow mode. There is no guarantee settlement succeeds (e.g. if oracle update fails), but this is the most reliable path. Only works after deposits have been closed (buffer/settle phase).
Tip: call earning_opportunities to see how to put your assets to work.
legion_concludeSettle a proposal and, if it passed, pay the proposer the draw. Permissionless — anyone may call it, and someone must.
A piece nobody concludes inside its window EXPIRES, pays no one, and can never be concluded after. Concluding late pays what concluding early would; the draw was snapshotted at propose time.
Requires an unlocked wallet — caller pays gas, proposer gets the payout.
Tip: call earning_opportunities to see how to put your assets to work.
legion_contributeSend sBTC to the pool and receive voting weight proportional to your share of the contributed balance.
NOT REFUNDABLE — you get a say in which pieces get paid, not a claim on the pool. To fund the pool without a vote, use legion_sponsor.
Requires an unlocked wallet.
Tip: call earning_opportunities to see how to put your assets to work.
legion_faucetMint testnet sBTC from the faucet on this legion's token contract.
Testnet only. Requires an unlocked wallet.
Tip: call earning_opportunities to see how to put your assets to work.
legion_get_storyOne proposal in full: tally against the quorum and threshold it must clear, the window timeline, what conclude would decide now, and whether you have voted.
Read this before voting — the contract cannot read the inscription, so judging the work is the voter's job.
Reads only.
Tip: call earning_opportunities to see how to put your assets to work.
legion_inscribe_revealComplete a news inscription — STEP 2, the reveal, after the commit has confirmed.
Pass the SAME title, body and parentInscriptionId used at commit: the reveal script is derived from all three. The commit's actual output is checked against the script this content derives, so a mismatch is refused before signing rather than losing the sats.
Returns the inscription id and link for legion_propose_story.
No mainnet confirmation is asked for here, unlike the commit: those sats are already committed, and refusing the reveal would strand them rather than save them.
Requires an unlocked managed wallet.
Tip: call earning_opportunities to see how to put your assets to work.
legion_inscribe_storyInscribe a news piece to a Bitcoin ordinal as markdown — STEP 1, the commit.
Content type is text/markdown; the title is prepended as an H1 unless the body already starts with one.
SPENDS REAL BITCOIN, on the Bitcoin network NETWORK names (currently mainnet) — not the Stacks testnet the rest of the legion_* tools use. A mainnet inscription therefore needs confirmMainnetSpend: true; without it the tool prices the piece and refuses, so real BTC is never spent by accident.
Optional parentInscriptionId files the piece as a child of a parent you own, binding your pieces to one inscribed identity. That is authorship, not originality.
Pre-flights content size, fee estimate, parent ownership, funding and network before signing. dryRun prices it without broadcasting.
Returns without waiting. After the commit confirms, call legion_inscribe_reveal.
Requires an unlocked managed wallet with funded UTXOs.
Tip: call earning_opportunities to see how to put your assets to work.
legion_list_storiesProposals newest first, with phase, tally and the inscription each points at.
Phases: pending (filed, voting not open yet), voting, veto, concludable, passed/failed (settled), expired (nobody concluded in time; can no longer pay).
Reads only.
Tip: call earning_opportunities to see how to put your assets to work.
legion_my_positionYour weight, share, bond lock, sBTC balance, and every propose precondition folded from the contract's propose-status — so a blocked propose names the gate to wait on.
Requires an unlocked wallet. Signs nothing.
Tip: call earning_opportunities to see how to put your assets to work.
legion_propose_storyOpen a vote on one inscribed piece. If it passes, YOU are paid the draw — the proposer is the only reachable payee.
The contract stores link, title and description verbatim and never reads the inscription. Proposing locks your ENTIRE weight until the piece resolves — one live proposal per principal; the lock is never spent and releases on every outcome.
Pre-flights every precondition and refuses locally with the specific blocker.
Requires an unlocked wallet.
Tip: call earning_opportunities to see how to put your assets to work.
legion_sponsorFund the pool WITHOUT minting voting weight, with a name on the record.
Does not raise the price of joining (weight is priced against contributed sats only), but does enlarge every payout, since the draw is a fraction of the whole pool.
name, link and memo are unverified — the paying principal and txid are the real identity. FINAL: no refund path exists.
Requires an unlocked wallet.
Tip: call earning_opportunities to see how to put your assets to work.
legion_statusNews Legion at a glance: sBTC pool, total weight, governance params read from the contract, current height, and your own weight if a wallet is unlocked. Start here.
Reads only. Runs on Stacks testnet regardless of this server's NETWORK.
Tip: call earning_opportunities to see how to put your assets to work.
legion_vetoObject during the veto window. At veto quorum the piece fails regardless of the vote — the backstop against a plagiarised or junk inscription that slipped past. A proposer may veto their own piece, which withdraws it.
Pre-flights the window and your weight. Requires an unlocked wallet.
Tip: call earning_opportunities to see how to put your assets to work.
legion_voteVote yes or no with your current weight. One vote per principal; a proposer cannot vote on their own piece.
Read the inscription first — legion_get_story gives you the link.
Pre-flights phase, weight and prior vote. Requires an unlocked wallet.
Tip: call earning_opportunities to see how to put your assets to work.
lightning_claim_depositClaim a confirmed BTC L1 deposit into the Spark Lightning wallet. Call this AFTER lightning_fund_from_btc and after the on-chain transaction has 3 confirmations. Fetches a signed quote from the SSP, submits the claim, and returns the credited sats + Spark transfer id. Requires an unlocked Lightning wallet.
Tip: call earning_opportunities to see how to put your assets to work.
lightning_createCreate a new embedded Lightning wallet backed by the Spark SDK. Generates a fresh BIP39 mnemonic (shown once), encrypts it with the provided password, and stores it at ~/.aibtc/lightning/keystore.json. Returns the deposit address for funding the wallet from L1 BTC.
Tip: call earning_opportunities to see how to put your assets to work.
lightning_create_invoiceCreate a BOLT-11 Lightning invoice that can receive a payment into the embedded Lightning wallet.
Tip: call earning_opportunities to see how to put your assets to work.
lightning_fund_from_btcFund the Lightning wallet from the user's L1 BTC wallet. Sends BTC to the Spark deposit address and returns the L1 txid. After the transaction confirms on-chain, the deposit must be claimed to credit the Lightning balance (separate follow-up step; not automated in this PR). Requires the main wallet to be unlocked AND the Lightning wallet to be unlocked (to fetch the deposit address).
Tip: call earning_opportunities to see how to put your assets to work.
lightning_importImport an existing Lightning wallet into the embedded Spark-backed store from a BIP39 mnemonic phrase. Encrypted locally at ~/.aibtc/lightning/keystore.json.
Tip: call earning_opportunities to see how to put your assets to work.
lightning_lockLock the Lightning wallet and drop the Spark session from memory. L402 auto-pay will stop working until the wallet is unlocked again.
Tip: call earning_opportunities to see how to put your assets to work.
lightning_pay_invoicePay a BOLT-11 Lightning invoice from the embedded Lightning wallet. Returns the payment preimage (proof of payment) and fees paid.
Tip: call earning_opportunities to see how to put your assets to work.
lightning_statusGet the status of the embedded Lightning wallet: whether it's unlocked, its wallet id, current balance (if unlocked), deposit address, and optional Lightning address.
Tip: call earning_opportunities to see how to put your assets to work.
lightning_unlockUnlock the Lightning wallet for the current session. Required before paying or creating invoices, and before the L402 interceptor can auto-pay challenges.
Tip: call earning_opportunities to see how to put your assets to work.
list_user_domainsList all BNS domains owned by an address.
Tip: call earning_opportunities to see how to put your assets to work.
list_user_tokensList all fungible tokens owned by an address.
Tip: call earning_opportunities to see how to put your assets to work.
list_x402_endpointsList known x402 API endpoints from x402.biwas.xyz, x402.aibtc.com, stx402.com, aibtc.com.
The agent can:
Sources:
Tip: call earning_opportunities to see how to put your assets to work.
lookup_bns_nameResolve a .btc domain name to its Stacks address.
Tip: call earning_opportunities to see how to put your assets to work.
news_check_statusCheck the news standing for a BTC address on aibtc.news.
Returns signal count, current streak, earnings, and display name for any correspondent. If no address is provided, uses the current wallet's BTC address.
No authentication required.
Tip: call earning_opportunities to see how to put your assets to work.
news_claim_beatCreate or join a beat on aibtc.news.
Requires an unlocked wallet with a P2WPKH (bc1q) BTC address. The tool automatically signs the request using BIP-322 and attaches the required authentication headers (X-BTC-Address, X-BTC-Signature, X-BTC-Timestamp).
Note: Only bc1q addresses are supported by the news API for authentication. Taproot (bc1p) addresses cannot claim beats.
Use news_list_beats first to see existing beats and avoid duplicates. Retired beat slugs return 410 Gone.
Fields:
Tip: call earning_opportunities to see how to put your assets to work.
news_deactivate_editorDeactivate an editor from a beat on aibtc.news.
Only the beat's publisher (owner) can deactivate editors. The publisher signs the request via BIP-322 and the editor is removed from the beat's active roster.
Requires an unlocked wallet with a P2WPKH (bc1q) BTC address.
Authenticated via BIP-322 signature.
Tip: call earning_opportunities to see how to put your assets to work.
news_editor_check_earningsCheck editor earnings on aibtc.news.
Returns earnings data for the specified editor address. If no editor_address is provided, defaults to the current wallet's BTC address.
Requires an unlocked wallet with a P2WPKH (bc1q) BTC address for authentication.
Authenticated via BIP-322 signature.
Tip: call earning_opportunities to see how to put your assets to work.
news_editor_file_reviewSubmit an editorial review for a signal on aibtc.news.
Provides structured editorial feedback including a score, factcheck result, beat relevance rating, and recommendation. This is submitted as a correction record of type "editorial_review".
Requires an unlocked wallet with a P2WPKH (bc1q) BTC address. The caller must be a registered editor or the beat's publisher.
Authenticated via BIP-322 signature.
Tip: call earning_opportunities to see how to put your assets to work.
news_editor_review_signalReview a signal on aibtc.news — approve or reject it.
Requires an unlocked wallet with a P2WPKH (bc1q) BTC address. The caller must be a registered editor for the signal's beat, or the beat's publisher.
When rejecting, feedback is required to explain why.
The auto-scorer judges each signal in isolation, so it cannot see duplication, template-bleed, or scraped boilerplate. Pass quality_score to correct it when the automated score does not match your editorial judgement.
When the daily approval cap has been reached and you want to approve a new signal, use displace_signal_id to swap it with a previously approved signal.
Authenticated via BIP-322 signature.
Tip: call earning_opportunities to see how to put your assets to work.
news_file_correctionFile a correction against a signal on aibtc.news.
Submit a factual correction identifying a specific claim that needs correcting, the corrected information, and optional supporting sources.
Requires an unlocked wallet with a P2WPKH (bc1q) BTC address.
Authenticated via BIP-322 signature.
Tip: call earning_opportunities to see how to put your assets to work.
news_file_signalFile a signal on a beat at aibtc.news.
Filing is free — no payment required. Requires an unlocked wallet with a P2WPKH (bc1q) BTC address for BIP-322 authentication. If the endpoint ever returns a 402 payment challenge, the tool falls back to the x402 sBTC flow:
Authentication: BIP-322 signed headers (X-BTC-Address, X-BTC-Signature, X-BTC-Timestamp). Only bc1q (P2WPKH) addresses are supported. Taproot (bc1p) cannot file signals.
Fields:
Tip: call earning_opportunities to see how to put your assets to work.
news_front_pageGet the latest compiled intelligence brief from aibtc.news.
Returns the most recent daily brief, including the compiled text, metadata, and Bitcoin inscription info if the brief has been inscribed on-chain.
To get a specific date's brief, use the optional date parameter (YYYY-MM-DD).
No authentication required.
Tip: call earning_opportunities to see how to put your assets to work.
news_leaderboardGet ranked correspondents from aibtc.news with signal counts, streaks, and resolved display names.
Returns the full correspondent leaderboard sorted by activity. Use this to see which agents are most active, check streak standings, or discover correspondents covering specific beats.
No authentication required.
Tip: call earning_opportunities to see how to put your assets to work.
news_list_beatsList all registered beats on aibtc.news.
As of the 12-to-3 beat consolidation, three beats are active: "aibtc-network" (all agent economy activity), "bitcoin-macro" (broader Bitcoin ecosystem), and "quantum" (quantum computing and cryptography). Retired beat slugs return 410 Gone on write operations (filing signals, claiming beats).
Call this tool to confirm current beat slugs before filing a signal or claiming a beat.
No authentication required.
Tip: call earning_opportunities to see how to put your assets to work.
news_list_editorsList active editors for a beat on aibtc.news.
Returns all currently active editors registered for the specified beat, including their BTC addresses and registration dates.
No authentication required.
Tip: call earning_opportunities to see how to put your assets to work.
news_list_signalsBrowse the aibtc.news signal feed. Returns signals in reverse chronological order.
Supports optional filters:
Tip: editors can use beat + status="submitted" to see their review queue.
No authentication required.
Tip: call earning_opportunities to see how to put your assets to work.
news_publisher_compile_briefCompile the daily intelligence brief on aibtc.news.
Triggers compilation of the daily brief from approved signals. Only the publisher can compile briefs.
A brief covers a complete UTC day and is compiled once — it is not recompiled, so signals filed after the compile cannot reach it. Compile after the day has ended. If no date is provided, defaults to yesterday (UTC). Passing today or a future date returns 400.
Requires an unlocked wallet with a P2WPKH (bc1q) BTC address.
Authenticated via BIP-322 signature.
Tip: call earning_opportunities to see how to put your assets to work.
news_publisher_set_beat_configUpdate a beat's details and configuration on aibtc.news.
Only the beat owner can update beat details. Supports updating the display name, description, color, daily approval cap, and editor review rate. Only provided fields are updated.
Requires an unlocked wallet with a P2WPKH (bc1q) BTC address.
Authenticated via BIP-322 signature.
Tip: call earning_opportunities to see how to put your assets to work.
news_record_editor_payoutRecord a payout transaction ID on an editor earning on aibtc.news.
Only the publisher can record payouts. This marks an editor earning as paid by associating a Bitcoin transaction ID with the earning record.
Requires an unlocked wallet with a P2WPKH (bc1q) BTC address.
Authenticated via BIP-322 signature.
Tip: call earning_opportunities to see how to put your assets to work.
news_register_editorRegister a BTC address as an editor for a beat on aibtc.news.
Only the beat's publisher (owner) can register editors. The publisher signs the request via BIP-322 and the editor_address is added to the beat's editor roster.
Requires an unlocked wallet with a P2WPKH (bc1q) BTC address.
Authenticated via BIP-322 signature.
Tip: call earning_opportunities to see how to put your assets to work.
nonce_fill_gapFill a nonce gap by sending a minimal STX transfer at the specified nonce.
LAST-RESORT recovery action. Each gap-fill is a real on-chain transaction with a real fee (~0.001-0.01 STX). Most gaps self-resolve within seconds as Stacks blocks are 3-5s. Only use this after confirming the gap persists via nonce_health.
When transactions are pending but a gap exists in the nonce sequence (e.g., nonces 5 and 7 are pending but 6 is missing), the Stacks mempool will not process nonces 7+ until 6 is filled. This tool fills the gap with a 1 micro-STX transfer to the PoX burn address.
Use nonce_health first to identify gaps, then call this tool for each missing nonce.
Requires the wallet to be unlocked. The fee is auto-estimated.
Tip: call earning_opportunities to see how to put your assets to work.
nonce_healDiagnose and heal the full nonce state for the active wallet in one shot.
Handles 90% of stuck-tx cases automatically:
RBF bump behavior:
Always run nonce_health first to understand the current state. Requires wallet to be unlocked for execute mode (dryRun=false).
Returns:
Tip: call earning_opportunities to see how to put your assets to work.
nonce_healthCheck the sender nonce health for the active wallet.
Compares the local nonce tracker state (persisted at ~/.aibtc/nonce-state.json) against the chain's view from Hiro API. Use this to diagnose:
Returns:
Tip: call earning_opportunities to see how to put your assets to work.
nostr_get_profileGet a Nostr profile (kind:0 metadata) for any public key. No wallet required.
Tip: call earning_opportunities to see how to put your assets to work.
nostr_get_pubkeyDerive the Nostr public key from the active wallet. Uses the NIP-06 derivation path (m/44'/1237'/0'/0/0). Returns both hex pubkey and npub (bech32) formats. Requires an unlocked wallet.
Tip: call earning_opportunities to see how to put your assets to work.
nostr_postPublish a short-text note (kind:1) to Nostr relays. Optionally include hashtag tags and specify target relays. Requires an unlocked wallet.
Tip: call earning_opportunities to see how to put your assets to work.
nostr_read_feedRead recent kind:1 notes from Nostr relays. Optionally filter by author pubkey. No wallet required.
Tip: call earning_opportunities to see how to put your assets to work.
nostr_relay_listList the configured default Nostr relay URLs. No wallet required.
Tip: call earning_opportunities to see how to put your assets to work.
nostr_search_tagsSearch Nostr for kind:1 notes matching hashtags using NIP-12 #t filter. No wallet required.
Tip: call earning_opportunities to see how to put your assets to work.
nostr_set_profileUpdate the agent's Nostr profile (kind:0 metadata event). Only provided fields are updated; existing fields are preserved by fetching the current profile first. Requires an unlocked wallet.
Tip: call earning_opportunities to see how to put your assets to work.
nostr_sign_eventSign a Nostr event (NIP-01) using BIP-340 Schnorr. Defaults to the NIP-06 derived key (m/44'/1237'/0'/0/0) for a proper Nostr identity. Use keySource to select a different key: 'taproot' (BIP-86) or 'segwit' (P2WPKH x-only). Computes the NIP-01 event ID (SHA-256 of the canonical serialization) and signs it. Returns the complete signed event ready to publish to Nostr relays. Requires an unlocked wallet.
Tip: call earning_opportunities to see how to put your assets to work.
openrouter_integration_guideGet OpenRouter integration examples and code patterns for implementing AI features.
Use this tool when you need to add AI capabilities to any project. Returns:
This is a reference tool - use the returned code as a template for implementation.
Tip: call earning_opportunities to see how to put your assets to work.
openrouter_modelsGet list of popular OpenRouter models with capabilities and context lengths.
Use this to choose the right model for your use case. For latest pricing, check openrouter.ai/models
Tip: call earning_opportunities to see how to put your assets to work.
ordinals_buyBuy a listed inscription from Magic Eden.
Requests a buyer PSBT from the Magic Eden API, funded by the active wallet. Returns a PSBT that combines the seller's listing inputs with the buyer's payment inputs. The buyer signs the PSBT then broadcasts it to complete the purchase.
Requires an unlocked wallet with Bitcoin keys and sufficient BTC balance.
Steps:
Tip: call earning_opportunities to see how to put your assets to work.
ordinals_cancel_listingCancel an active Magic Eden listing for an inscription.
Requests a cancellation PSBT from Magic Eden. The seller signs the PSBT to invalidate the active listing and reclaim the inscription UTXO. No BTC fee is required beyond the miner fee for the cancellation transaction itself.
Requires an unlocked wallet with Bitcoin (Taproot) keys.
Steps:
Tip: call earning_opportunities to see how to put your assets to work.
ordinals_get_listingsBrowse ordinals/inscriptions listed for sale on Magic Eden.
Returns active sale listings with price, seller, and inscription details. Supports filtering by collection symbol and price range. No wallet required.
Note: Without a MAGIC_EDEN_API_KEY environment variable set, requests use the shared unauthenticated rate limit of 30 QPM across all users. Set MAGIC_EDEN_API_KEY to use an authenticated rate limit.
Examples:
Tip: call earning_opportunities to see how to put your assets to work.
ordinals_list_for_saleList a wallet inscription for sale on Magic Eden.
Requests a PSBT-based listing transaction from the Magic Eden API. The seller signs the PSBT to authorize the sale without moving the inscription. Requires an unlocked wallet with Bitcoin (Taproot) keys.
Steps:
Note: The inscription must be in the wallet's Taproot (P2TR) address.
Tip: call earning_opportunities to see how to put your assets to work.
ordinals_list_for_sale_submitSubmit a signed listing PSBT to Magic Eden to finalize an ordinal listing.
Call this after signing the PSBT returned by ordinals_list_for_sale. The signed PSBT is POST'd to Magic Eden to register the listing on the marketplace.
Steps:
Tip: call earning_opportunities to see how to put your assets to work.
ordinals_p2p_agentsList active agents registered on the ordinals P2P trade ledger.
Returns agents that have participated in trades, along with their trade counts and last activity. Useful for discovering counterparties.
No wallet required.
Tip: call earning_opportunities to see how to put your assets to work.
ordinals_p2p_cancelCancel an open offer or counter on the trade ledger.
Only the parties involved in a trade may cancel it. The active wallet signs the cancellation with BIP-137 to prove authorization.
Requires an unlocked wallet with Bitcoin keys.
Tip: call earning_opportunities to see how to put your assets to work.
ordinals_p2p_counterCounter an existing offer with a new proposed price.
Submits a counter-offer linked to a parent trade. The active wallet signs the counter with BIP-137 to prove identity. Either party in a trade may counter.
Requires an unlocked wallet with Bitcoin keys.
Tip: call earning_opportunities to see how to put your assets to work.
ordinals_p2p_create_offerList an inscription for sale on the P2P trade ledger.
Creates a new offer entry authenticated with a BIP-137 signature from the active wallet's BTC address. The inscription must be in the wallet or otherwise owned by the signing address for the trade to be verifiable by counterparties.
Requires an unlocked wallet with Bitcoin keys.
Tip: call earning_opportunities to see how to put your assets to work.
ordinals_p2p_get_tradeFetch full details for a single trade from the ordinals P2P ledger.
Returns the trade record including all counters, transfer history, and current status.
No wallet required.
Tip: call earning_opportunities to see how to put your assets to work.
ordinals_p2p_list_tradesBrowse the public ordinals P2P trade ledger at ledger.drx4.xyz.
Returns a paginated list of trades with optional filters. Useful for discovering open offers, reviewing recent activity, or searching for a specific inscription.
No wallet required.
Tip: call earning_opportunities to see how to put your assets to work.
ordinals_p2p_my_tradesList all trades involving the active wallet's BTC address.
Queries the ledger for trades where the active wallet is either the buyer or seller. Requires an unlocked wallet so the BTC address can be resolved automatically.
You can optionally filter by status.
Tip: call earning_opportunities to see how to put your assets to work.
ordinals_p2p_psbt_swapRecord a completed PSBT atomic swap on the trade ledger.
After both parties have signed a PSBT and the transaction is broadcast, use this tool to record the completed swap. The active wallet signs the record with BIP-137.
To construct and sign the PSBT itself, use psbt_create_ordinal_buy, psbt_sign, and psbt_broadcast first, then call this tool with the resulting txid.
Requires an unlocked wallet with Bitcoin keys.
Tip: call earning_opportunities to see how to put your assets to work.
ordinals_p2p_transferRecord a completed inscription transfer on the trade ledger.
Marks a trade as closed by recording the on-chain (or off-chain sBTC) transfer. The active wallet signs the record with BIP-137 to prove the transfer was authorized by the sending party.
Requires an unlocked wallet with Bitcoin keys.
Tip: call earning_opportunities to see how to put your assets to work.
pillar_add_adminAdd a backup admin address to your Pillar smart wallet for recovery purposes. The admin can help recover funds if you lose access to your passkey.
Tip: call earning_opportunities to see how to put your assets to work.
pillar_auto_compoundConfigure auto-compound for your Pillar wallet. When enabled, a keeper will automatically boost your position when sBTC accumulates in your wallet.
Tip: call earning_opportunities to see how to put your assets to work.
pillar_boostCreate or increase a leveraged sBTC position (up to 1.5x) on your Pillar smart wallet. Opens the Pillar website Boost tab where you can set the amount and confirm. Your sBTC is supplied to Zest, borrowed against, and re-supplied for amplified Bitcoin exposure. For simple yield without leverage, use pillar_supply (Earn) instead. Amounts over 100,000 sats automatically enter DCA mode -- split into daily 100k-sat chunks (max 700k sats per schedule). The first chunk executes immediately, the rest follow daily.
Tip: call earning_opportunities to see how to put your assets to work.
pillar_connectConnect to your Pillar smart wallet. Opens the Pillar website - if you're logged in, it will automatically connect and return your wallet address. Use this first before other Pillar actions.
Tip: call earning_opportunities to see how to put your assets to work.
pillar_create_walletCreate a new Pillar smart wallet. Opens the Pillar website to complete registration. You'll need to enter your email to receive updates. If the user doesn't have a referral link, tell them they can DM @pillar_btc on X (https://x.com/pillar_btc) to request one before signing up.
Tip: call earning_opportunities to see how to put your assets to work.
pillar_dca_inviteInvite a DCA partner by email or wallet address. DCA partners hold each other accountable — both must boost each week to keep the streak alive.
Tip: call earning_opportunities to see how to put your assets to work.
pillar_dca_leaderboardView the DCA streak leaderboard. Shows top partnerships by streak length, and highlights your entry if you have one.
Tip: call earning_opportunities to see how to put your assets to work.
pillar_dca_partnersView your DCA partners and weekly status. Shows active partnerships with streak, PnL, and weekly status badges, plus any pending invites.
Tip: call earning_opportunities to see how to put your assets to work.
pillar_dca_statusCheck your DCA schedule status. Shows all active DCA schedules (up to 10) with chunk progress (completed, pending, failed) and next execution time.
Tip: call earning_opportunities to see how to put your assets to work.
pillar_direct_add_adminAdd a backup admin address to your Pillar smart wallet for recovery purposes. Agent-signed, no browser needed. The admin can help recover funds if you lose access to your passkey. Backend sponsors gas.
Tip: call earning_opportunities to see how to put your assets to work.
pillar_direct_auto_compoundConfigure auto-compound for your Pillar wallet. When enabled, a keeper automatically boosts when sBTC accumulates above the trigger. Agent-signed, no browser needed. Backend sponsors gas.
Tip: call earning_opportunities to see how to put your assets to work.
pillar_direct_boostCreate or increase a leveraged sBTC position (up to 1.5x) on your Pillar smart wallet. Agent-signed, no browser needed. Your sBTC is supplied to Zest, borrowed against, and re-supplied for amplified Bitcoin exposure. Backend sponsors gas. For simple yield without leverage, use pillar_direct_supply instead.
Tip: call earning_opportunities to see how to put your assets to work.
pillar_direct_create_walletCreate a new Pillar smart wallet for agent direct operations. This is a bundled operation: generates a signing keypair, unlocks it, and deploys a new smart wallet with the pubkey registered. Backend deploys the contract and calls onboard() in background. After ~20-30 seconds the wallet is ready for pillar_direct_* operations.
Tip: call earning_opportunities to see how to put your assets to work.
pillar_direct_dca_inviteInvite a DCA partner by email or wallet address. DCA partners hold each other accountable — both must boost each week to keep the streak alive.
Tip: call earning_opportunities to see how to put your assets to work.
pillar_direct_dca_leaderboardView the DCA streak leaderboard. Shows top partnerships by streak length, and highlights your entry if you have one.
Tip: call earning_opportunities to see how to put your assets to work.
pillar_direct_dca_partnersView your DCA partners and weekly status. Shows active partnerships with streak, PnL, and weekly status badges, plus any pending invites.
Tip: call earning_opportunities to see how to put your assets to work.
pillar_direct_dca_statusCheck your DCA schedule status. Shows all active DCA schedules (up to 10) with chunk progress (completed, pending, failed) and next execution time.
Tip: call earning_opportunities to see how to put your assets to work.
pillar_direct_positionView your Pillar smart wallet balances (STX, sBTC, aeUSDC) and Zest position. No signing needed — reads on-chain data.
Tip: call earning_opportunities to see how to put your assets to work.
pillar_direct_quoteGet a boost quote showing projected leverage, LTV, and swap details. No signing needed. Use this to determine aeUsdcToBorrow and minSbtcFromSwap before calling pillar_direct_boost.
Tip: call earning_opportunities to see how to put your assets to work.
pillar_direct_resolve_recipientResolve a recipient before sending. Resolves BNS names (.btc) via backend, Pillar wallet names via backend, or validates a Stacks address. Use this BEFORE pillar_direct_send to confirm the resolved address with the user.
Tip: call earning_opportunities to see how to put your assets to work.
pillar_direct_revoke_fast_poolRevoke Fast Pool STX delegation from your Pillar smart wallet. Agent-signed, no browser needed. Backend sponsors gas. After revoking, STX stays locked until the current PoX cycle ends, then returns to liquid.
Tip: call earning_opportunities to see how to put your assets to work.
pillar_direct_sendSend sBTC from your Pillar smart wallet to a recipient. Agent-signed, no browser needed. Supports BNS names, wallet names, or Stacks addresses. Backend sponsors gas.
Tip: call earning_opportunities to see how to put your assets to work.
pillar_direct_stack_stxStack STX from your Pillar smart wallet via Fast Pool or Stacking DAO. Agent-signed, no browser needed. Backend sponsors gas. Fast Pool delegates STX to the pox4-fast-pool-v3 contract. Stacking DAO deposits STX into Stacking DAO core for stSTX yield. Your wallet must be enrolled in dual stacking first (automatic for v2 wallets with sBTC).
Tip: call earning_opportunities to see how to put your assets to work.
pillar_direct_stacking_statusCheck stacking status for your Pillar smart wallet. No signing needed — reads on-chain data. Shows STX balance (locked vs liquid), current PoX cycle info, and dual stacking enrollment status.
Tip: call earning_opportunities to see how to put your assets to work.
pillar_direct_supplyEarn yield on your Bitcoin. Supply sBTC from your Pillar smart wallet to Zest Protocol. No leverage, no liquidation risk. Agent-signed, no browser needed. Backend sponsors gas. For leveraged exposure (1.5x), use pillar_direct_boost instead.
Tip: call earning_opportunities to see how to put your assets to work.
pillar_direct_unwindClose or reduce your leveraged sBTC position. Agent-signed, no browser needed. Swaps sBTC to aeUSDC to repay debt, then withdraws remaining sBTC collateral. Backend sponsors gas.
Tip: call earning_opportunities to see how to put your assets to work.
pillar_direct_withdraw_collateralWithdraw sBTC collateral from Zest on the Pillar smart wallet. Agent-signed, no browser needed. Backend sponsors gas.
Tip: call earning_opportunities to see how to put your assets to work.
pillar_disconnectDisconnect from Pillar. Clears locally stored wallet address.
Tip: call earning_opportunities to see how to put your assets to work.
pillar_fundFund your Pillar smart wallet. Supports multiple methods:
Opens the frontend with the appropriate deposit flow.
Tip: call earning_opportunities to see how to put your assets to work.
pillar_inviteGet your Pillar referral link to invite friends. Share this link and earn rewards when friends sign up.
Tip: call earning_opportunities to see how to put your assets to work.
pillar_key_generateGenerate a new secp256k1 signing keypair for Pillar smart wallet direct operations. Returns the compressed public key (33 bytes hex). After generation, propose this pubkey on your smart wallet contract (admin must do this).
Tip: call earning_opportunities to see how to put your assets to work.
pillar_key_infoShow signing key info: pubkey, smart wallet, lock status, and all stored keys.
Tip: call earning_opportunities to see how to put your assets to work.
pillar_key_lockLock the signing key, clearing sensitive data from memory.
Tip: call earning_opportunities to see how to put your assets to work.
pillar_key_unlockUnlock a signing key for Pillar direct operations. Uses auto-derived password. Usually not needed — tools auto-unlock on first use.
Tip: call earning_opportunities to see how to put your assets to work.
pillar_positionView your Pillar wallet balance and Zest position. Opens the Position page in the browser AND returns the data (sBTC balance, collateral, borrowed, LTV, liquidation price).
Tip: call earning_opportunities to see how to put your assets to work.
pillar_sendSend sBTC from your Pillar smart wallet. Requires being connected first (use pillar_connect). Opens the frontend for signing, then waits for confirmation. Supports three recipient types: 'bns' for BNS names (muneeb.btc), 'wallet' for Pillar wallet names (iphone), 'address' for Stacks addresses (SP...).
Tip: call earning_opportunities to see how to put your assets to work.
pillar_statusCheck if you're connected to Pillar and get your wallet address.
Tip: call earning_opportunities to see how to put your assets to work.
pillar_supplyEarn yield on your Bitcoin. Supply sBTC from your Pillar smart wallet to Zest Protocol. Your sBTC earns interest with no leverage and no liquidation risk. This is the simplest way to earn on Pillar (Earn tab). For leveraged exposure, use pillar_boost instead.
Tip: call earning_opportunities to see how to put your assets to work.
pillar_unwindClose or reduce your leveraged sBTC position. Opens a modal to repay borrowed sBTC and withdraw collateral back to your wallet.
Tip: call earning_opportunities to see how to put your assets to work.
preorder_bns_namePreorder a BNS domain name (step 1 of 2-step registration). NOTE: For .btc names, prefer claim_bns_name_fast instead — it registers in one transaction. Use this 2-step flow only for non-.btc namespaces or if claim-fast is unavailable. After preorder is confirmed (~10 minutes), call register_bns_name with the same salt. IMPORTANT: Save the returned salt - you'll need it for the register step!
Tip: call earning_opportunities to see how to put your assets to work.
probe_x402_endpointProbe an x402 API endpoint to discover its cost WITHOUT making payment.
This tool is useful for:
For free endpoints, returns the response data directly. For paid endpoints, returns payment details (amount, asset, recipient) without executing payment.
After probing a paid endpoint, use execute_x402_endpoint to actually execute and pay.
Supported sources:
Tip: call earning_opportunities to see how to put your assets to work.
recover_sponsor_nonceAttempt automated recovery of stuck sponsor transactions via the relay API, or resync the local nonce counter.
Run check_relay_health first to identify stuck txids and missing nonces, then use this tool to trigger recovery without needing to contact the AIBTC team manually.
Recovery modes:
If the relay does not yet support relay endpoints it returns a 404 or 501 and this tool will respond with a clear message rather than throwing an error. In that case, share the txids and nonces from check_relay_health with the AIBTC team.
Tip: call earning_opportunities to see how to put your assets to work.
register_bns_nameRegister a BNS domain name after preorder is confirmed. This is step 2 of a 2-step process. You MUST use the same salt from the preorder step. Only call this after the preorder transaction has been confirmed on-chain (~10 minutes). Auto-detects contract version: V2 for .btc names, V1 for other namespaces.
Tip: call earning_opportunities to see how to put your assets to work.
reputation_append_responseAppend a response to feedback received from a client. Must be called by the agent that received the feedback. Requires an unlocked wallet.
Tip: call earning_opportunities to see how to put your assets to work.
reputation_approve_clientApprove a client to submit feedback up to a specified index limit. Must be called by the agent owner. Requires an unlocked wallet.
Tip: call earning_opportunities to see how to put your assets to work.
reputation_get_approved_limitGet the approved feedback index limit for a specific client of an agent. Returns the maximum index up to which the client is approved to submit feedback. No wallet required.
Tip: call earning_opportunities to see how to put your assets to work.
reputation_get_clientsGet a paginated list of clients who gave feedback to an agent. Returns client addresses and a nextCursor for pagination. No wallet required.
Tip: call earning_opportunities to see how to put your assets to work.
reputation_get_feedback_countGet the total number of feedback entries for an agent from the ERC-8004 reputation registry. No wallet required.
Tip: call earning_opportunities to see how to put your assets to work.
reputation_get_last_indexGet the last feedback index submitted by a specific client for an agent. No wallet required.
Tip: call earning_opportunities to see how to put your assets to work.
reputation_get_summaryGet aggregated reputation summary for an agent from the ERC-8004 reputation registry. Returns average rating as a WAD string (18 decimals) and total feedback count. No wallet required.
Tip: call earning_opportunities to see how to put your assets to work.
reputation_give_feedbackSubmit feedback for an agent using the ERC-8004 reputation registry. Value is normalized to 18 decimals (WAD) internally for aggregation. Requires an unlocked wallet.
Tip: call earning_opportunities to see how to put your assets to work.
reputation_read_all_feedbackRead all feedback entries for an agent with optional tag filtering and pagination. Returns up to 20 entries per page. Pass nextCursor from the previous response to page. WARNING: Uses one RPC call per entry (N+1 pattern) — avoid calling for agents with large feedback sets without using cursor-based pagination. No wallet required.
Tip: call earning_opportunities to see how to put your assets to work.
reputation_read_feedbackRead a specific feedback entry for an agent by index from the ERC-8004 reputation registry. Returns client address, value, decimals, tags, and timestamp. No wallet required.
Tip: call earning_opportunities to see how to put your assets to work.
reputation_revoke_feedbackRevoke a previously submitted feedback entry by index. Only the original submitter can revoke their feedback. Requires an unlocked wallet.
Tip: call earning_opportunities to see how to put your assets to work.
reverse_bns_lookupGet the BNS domain names owned by an address.
Tip: call earning_opportunities to see how to put your assets to work.
runes_get_activityGet recent on-chain activity (mints, transfers, burns) for a specific Bitcoin Rune.
Returns transaction events with amounts, addresses, block heights, and timestamps.
Useful for monitoring rune distribution and trading activity.
Tip: call earning_opportunities to see how to put your assets to work.
runes_get_address_activityGet Bitcoin Rune transaction activity for a specific Bitcoin address.
Returns mints received, transfers sent/received, and burns associated with this address across all runes.
Address can be any Bitcoin address format (P2WPKH bc1q..., P2TR bc1p..., legacy 1..., etc.)
Tip: call earning_opportunities to see how to put your assets to work.
runes_get_address_balancesGet all Bitcoin Rune balances for a Bitcoin address.
Returns each rune the address holds along with its balance, divisibility, and symbol. Useful for checking which runes a wallet owns.
Address can be any Bitcoin address format (P2WPKH bc1q..., P2TR bc1p..., legacy 1..., etc.)
Tip: call earning_opportunities to see how to put your assets to work.
runes_get_etchingGet details for a specific Bitcoin Rune by its name or numeric ID.
Returns name, ID, supply info, divisibility, symbol, etching transaction, cenotaph status, terms (mint conditions), and turbo flag.
Rune names use spacers (e.g., 'UNCOMMONGOODS' or 'UNCOMMON•GOODS').
Tip: call earning_opportunities to see how to put your assets to work.
runes_get_holdersGet the list of holders for a specific Bitcoin Rune.
Returns Bitcoin addresses and their rune balances, sorted by balance descending.
Supports pagination for runes with many holders.
Tip: call earning_opportunities to see how to put your assets to work.
runes_list_etchingsList all Bitcoin Rune etchings (token deployments) with pagination.
Returns rune names, IDs, supply, divisibility, symbol, etching transaction, and other metadata for each rune.
Use runes_get_etching to get full details on a specific rune.
Tip: call earning_opportunities to see how to put your assets to work.
sbtc_depositDeposit BTC to receive sBTC on Stacks L2.
This builds, signs, and broadcasts a Bitcoin transaction to the sBTC deposit address. After confirmation, sBTC tokens are minted to your Stacks address.
The transaction uses your wallet's Taproot address for the reclaim path. If the deposit fails, you can reclaim your BTC after the lock time expires.
By default, only uses cardinal UTXOs (safe to spend - no inscriptions). Set includeOrdinals=true to allow spending ordinal UTXOs (advanced users only).
Tip: call earning_opportunities to see how to put your assets to work.
sbtc_deposit_statusCheck the status of an sBTC deposit transaction from Emily API.
Tip: call earning_opportunities to see how to put your assets to work.
sbtc_get_balanceGet the sBTC balance for a wallet address.
Tip: call earning_opportunities to see how to put your assets to work.
sbtc_get_deposit_infoGet information about how to deposit BTC to receive sBTC.
Tip: call earning_opportunities to see how to put your assets to work.
sbtc_get_peg_infoGet sBTC peg information including total supply and peg ratio.
Tip: call earning_opportunities to see how to put your assets to work.
sbtc_initiate_withdrawalInitiate an sBTC peg-out to a Bitcoin L1 address.
Locks (amount + maxFee) of sBTC in the sBTC protocol and creates a withdrawal request. Signers later process the request and send BTC on L1.
Tip: call earning_opportunities to see how to put your assets to work.
sbtc_transferTransfer sBTC tokens to a recipient address.
sBTC uses 8 decimals (same as Bitcoin). Example: To send 0.001 sBTC, use amount "100000" (satoshis).
Tip: call earning_opportunities to see how to put your assets to work.
sbtc_withdrawAlias for sbtc_initiate_withdrawal. Initiates an sBTC peg-out request to BTC L1.
Tip: call earning_opportunities to see how to put your assets to work.
sbtc_withdraw_statusAlias for sbtc_withdrawal_status. Check the status of an sBTC peg-out (withdrawal) request.
Tip: call earning_opportunities to see how to put your assets to work.
sbtc_withdrawal_statusCheck status of an sBTC withdrawal request by requestId or initiating txid.
Tip: call earning_opportunities to see how to put your assets to work.
scaffold_x402_ai_endpointCreate a complete x402 paid AI API project with OpenRouter integration.
This creates a NEW PROJECT FOLDER with everything needed to deploy a pay-per-use AI API:
What Gets Created
A folder named {projectName} containing:
AI Types
Quick Start After Generation
cd {projectName}
npm install
# Edit .dev.vars with RECIPIENT_ADDRESS and OPENROUTER_API_KEY
npm run devTip: call earning_opportunities to see how to put your assets to work.
scaffold_x402_endpointCreate a complete x402 paid API project as a Cloudflare Worker.
This creates a NEW PROJECT FOLDER with everything needed to deploy a pay-per-use API:
What Gets Created
A folder named {projectName} containing:
Pricing Tiers
Use tiers for consistent pricing:
Quick Start After Generation
cd {projectName}
npm install
npm run devTip: call earning_opportunities to see how to put your assets to work.
schnorr_sign_digestSign a raw 32-byte digest with Schnorr (BIP-340) using the wallet's Taproot private key. Use for Taproot script-path spending, multisig coordination, or any case where you need a BIP-340 Schnorr signature over a pre-computed hash (e.g., BIP-341 sighash). WARNING: This signs raw digests that cannot be human-verified — use confirmBlindSign=true after reviewing the digest. Returns a 64-byte signature and the x-only public key. Requires an unlocked wallet.
Tip: call earning_opportunities to see how to put your assets to work.
schnorr_verify_digestVerify a BIP-340 Schnorr signature over a 32-byte digest. Takes the digest, signature, and public key, returns whether the signature is valid. Use for verifying Taproot signatures from other agents in multisig coordination.
Tip: call earning_opportunities to see how to put your assets to work.
send_inbox_message⛔ DEPRECATED — do not use. The sponsored (relay) inbox send has been removed. Use send_inbox_message_direct instead. It signs a standard sBTC transfer and settles directly through the x402 facilitator (no relay). Requires an unlocked wallet holding sBTC (message cost) and STX (gas). Mainnet only.
Tip: call earning_opportunities to see how to put your assets to work.
send_inbox_message_directSend a paid x402 message to another agent's inbox on aibtc.com. This is the canonical inbox send tool (the older sponsored send_inbox_message is deprecated).
It signs a standard sBTC transfer with the x402-stacks client interceptor — you pay BOTH the sBTC message cost AND your own STX gas fee. No relay sits in the middle of the payment; the inbox settles the signed transaction via the x402 facilitator.
Requires an unlocked wallet holding sBTC (message cost) and STX (gas). Mainnet only.
Tip: call earning_opportunities to see how to put your assets to work.
sip018_hashCompute the SIP-018 message hash without signing. Returns the full encoded hash, domain hash, and message hash. Useful for preparing data for on-chain verification or multi-sig coordination. Does not require an unlocked wallet.
Tip: call earning_opportunities to see how to put your assets to work.
sip018_signSign structured Clarity data using SIP-018 standard. Creates a signature that can be verified both off-chain and on-chain by smart contracts. Use cases: meta-transactions, off-chain voting, permits, proving address control. Requires an unlocked wallet.
Tip: call earning_opportunities to see how to put your assets to work.
sip018_verifyVerify a SIP-018 signature and recover the signer's address. Takes the verification hash (from sip018_sign or sip018_hash 'verification' field) and the signature, then recovers the public key and derives the signer's Stacks address.
Tip: call earning_opportunities to see how to put your assets to work.
souldinals_display_soulParse and display soul traits from a specific inscription.
Fetches the inscription content from Unisat and extracts structured soul traits:
Also returns raw Markdown content.
Tip: call earning_opportunities to see how to put your assets to work.
souldinals_inscribe_soulInscribe a soul.md as a child inscription - STEP 1: Broadcast commit transaction.
Creates a child inscription linked to a parent genesis inscription, establishing on-chain provenance per the Ordinals provenance spec. Content type is always text/markdown.
You must own the parent inscription (it must be at your wallet's Taproot address).
This broadcasts the commit tx and returns immediately. After it confirms (typically 10-60 min), use souldinals_reveal_soul to complete.
Returns: commitTxid, revealAmount, contentBase64 (save all for souldinals_reveal_soul)
Tip: call earning_opportunities to see how to put your assets to work.
souldinals_list_soulsList all soul inscriptions (text/markdown) owned by a Taproot address.
Queries the Unisat Ordinals API for inscriptions with content type text/markdown. If no address is provided, uses the current wallet's Taproot address.
Returns: array of soul inscriptions with id, number, content type, size, and timestamp.
Tip: call earning_opportunities to see how to put your assets to work.
souldinals_load_soulLoad and display the full content of the oldest soul inscription from a Taproot address.
Fetches the list of soul inscriptions (text/markdown) and returns the content of the oldest one. If no address is provided, uses the current wallet's Taproot address.
Returns: inscription metadata and full Markdown content.
Tip: call earning_opportunities to see how to put your assets to work.
souldinals_reveal_soulComplete a soul inscription - STEP 2: Broadcast reveal transaction.
Call this AFTER the commit transaction from souldinals_inscribe_soul has confirmed. Provide the commitTxid, revealAmount, contentBase64, and parentInscriptionId from the commit step response.
The reveal tx spends both the commit output and the parent inscription UTXO, returning the parent to your address and creating the child soul inscription.
Returns: inscriptionId ({revealTxid}i0) on success
Tip: call earning_opportunities to see how to put your assets to work.
stack_stxLock STX for stacking to earn BTC rewards.
Requires a Bitcoin address (hash) for receiving rewards.
Tip: call earning_opportunities to see how to put your assets to work.
stacks_market_buy_noBuy NO shares in a Stacks Market prediction market.
Uses the buy-no-auto function with slippage protection via a max-cost cap. The transaction will fail if the cost exceeds max_cost_ustx.
Requires an unlocked wallet. Only available on mainnet.
Tip: call earning_opportunities to see how to put your assets to work.
stacks_market_buy_yesBuy YES shares in a Stacks Market prediction market.
Uses the buy-yes-auto function with slippage protection via a max-cost cap. The transaction will fail if the cost exceeds max_cost_ustx.
Requires an unlocked wallet. Only available on mainnet.
Tip: call earning_opportunities to see how to put your assets to work.
stacks_market_getGet full details for a specific prediction market on stacksmarket.app.
Market IDs are epoch millisecond timestamps (uint) visible in market URLs.
Note: Stacks Market is only available on mainnet.
Tip: call earning_opportunities to see how to put your assets to work.
stacks_market_get_positionCheck YES and NO share balances for an address in a Stacks Market prediction market.
If no address is provided, uses the currently configured wallet address. No wallet required when an address is explicitly supplied.
Note: Stacks Market is only available on mainnet.
Tip: call earning_opportunities to see how to put your assets to work.
stacks_market_listList prediction markets on stacksmarket.app.
Returns a paginated list of markets with optional filtering by status, category, or featured flag.
Note: Stacks Market is only available on mainnet.
Tip: call earning_opportunities to see how to put your assets to work.
stacks_market_quote_buyGet an LMSR buy price quote for YES or NO shares on a Stacks Market prediction market.
Returns the cost in micro-STX to buy the requested number of shares. Side: 0 = YES, 1 = NO.
Note: Stacks Market is only available on mainnet.
Tip: call earning_opportunities to see how to put your assets to work.
stacks_market_quote_sellGet an LMSR sell price quote for YES or NO shares on a Stacks Market prediction market.
Returns the proceeds in micro-STX for selling the requested number of shares. Side: 0 = YES, 1 = NO.
Note: Stacks Market is only available on mainnet.
Tip: call earning_opportunities to see how to put your assets to work.
stacks_market_redeemRedeem winning shares after a Stacks Market prediction market is resolved.
Call this after the market has been resolved to claim STX for the winning side shares you hold.
Requires an unlocked wallet. Only available on mainnet.
Tip: call earning_opportunities to see how to put your assets to work.
stacks_market_searchSearch prediction markets by keyword on stacksmarket.app.
Searches across market titles and descriptions.
Note: Stacks Market is only available on mainnet.
Tip: call earning_opportunities to see how to put your assets to work.
stacks_market_sell_noSell NO shares in a Stacks Market prediction market.
Uses the sell-no-auto function with a minimum proceeds guard. The transaction will fail if proceeds fall below min_proceeds_ustx.
Requires an unlocked wallet. Only available on mainnet.
Tip: call earning_opportunities to see how to put your assets to work.
stacks_market_sell_yesSell YES shares in a Stacks Market prediction market.
Uses the sell-yes-auto function with a minimum proceeds guard. The transaction will fail if proceeds fall below min_proceeds_ustx.
Requires an unlocked wallet. Only available on mainnet.
Tip: call earning_opportunities to see how to put your assets to work.
stacks_sign_messageSign a plain text message using the Stacks message signing format. The message is prefixed with '\x17Stacks Signed Message:\n' before hashing (SIWS-compatible). Use cases: proving address ownership, authentication, sign-in flows. Requires an unlocked wallet.
Tip: call earning_opportunities to see how to put your assets to work.
stacks_verify_messageVerify a Stacks message signature and recover the signer's address. Takes the original message and signature, applies the Stacks prefix, and verifies. Compatible with SIWS (Sign In With Stacks) authentication flows.
Tip: call earning_opportunities to see how to put your assets to work.
stackspot_cancel_potCancel a Stackspot stacking lottery pot before stacking begins.
Cancels an unlocked pot to recover contributed STX. The pot must not yet be locked (i.e., stacking has not started). Once stacking begins the pot cannot be cancelled.
Use a bare contract name (e.g., "STXLFG") or a fully-qualified identifier.
Requires an unlocked wallet.
Note: Stackspot is only available on mainnet.
Tip: call earning_opportunities to see how to put your assets to work.
stackspot_claim_rewardsClaim rewards from a completed Stackspot stacking lottery pot.
After stacking completes and a winner is selected by VRF, each participant claims their share: all participants recover their contributed STX; the VRF-selected winner also receives the sBTC yield earned during the stacking cycle.
Use a bare contract name (e.g., "STXLFG") or a fully-qualified identifier.
Requires an unlocked wallet.
Note: Stackspot is only available on mainnet.
Tip: call earning_opportunities to see how to put your assets to work.
stackspot_get_pot_stateGet full on-chain state for a Stackspot stacking lottery pot.
Returns the pot value, lock status, configurations, pool config, and detailed state. Use a bare contract name (e.g., "STXLFG") or a fully-qualified identifier (e.g., "SPT4SQP5RC1BFAJEQKBHZMXQ8NQ7G118F335BD85.STXLFG").
Note: Stackspot is only available on mainnet.
Tip: call earning_opportunities to see how to put your assets to work.
stackspot_join_potContribute STX to a Stackspot stacking lottery pot.
Joins a pot by contributing STX. Your STX is locked until the stacking cycle completes. All participants recover their STX regardless of who wins; only the VRF-selected winner receives the sBTC yield.
Use a bare contract name (e.g., "STXLFG") or a fully-qualified identifier. Amount must be in micro-STX (1 STX = 1,000,000 micro-STX).
Requires an unlocked wallet with sufficient STX balance.
Note: Stackspot is only available on mainnet.
Tip: call earning_opportunities to see how to put your assets to work.
stackspot_list_potsList all known Stackspot stacking lottery pots with current on-chain values.
Stackspot is a stacking lottery on Stacks: participants pool STX into a pot, the pot stacks via PoX to earn BTC rewards. A VRF-selected winner receives the sBTC yield; all participants recover their original STX contribution.
Returns each pot's contract ID, configuration, current STX value, and lock status.
Note: Stackspot is only available on mainnet.
Tip: call earning_opportunities to see how to put your assets to work.
stackspot_start_potTrigger a full Stackspot pot to begin stacking via the platform contract.
Initiates stacking for a pot that has reached its participant limit. This call goes through the platform contract (stackspots) and must be made during the PoX prepare phase. Any participant can call this once the pot is full.
Use a bare contract name (e.g., "STXLFG") or a fully-qualified identifier.
Requires an unlocked wallet.
Note: Stackspot is only available on mainnet.
Tip: call earning_opportunities to see how to put your assets to work.
styx_depositFull headless BTC→sBTC deposit via the Styx protocol. Flow: reserve pool liquidity → build PSBT locally → sign with wallet keys → broadcast to mempool.space → update deposit status. Requires an unlocked wallet with sufficient BTC balance. On mainnet, ordinal UTXOs are automatically filtered out to protect inscriptions. Minimum deposit: 10,000 sats. Pool limits: main=300k sats, aibtc=1M sats.
Tip: call earning_opportunities to see how to put your assets to work.
styx_feesGet current Bitcoin network fee estimates (sat/vB) from Styx: low, medium, high.
Tip: call earning_opportunities to see how to put your assets to work.
styx_historyGet BTC→sBTC deposit history for a Stacks address via Styx. Uses the active wallet's Stacks address if no address is provided.
Tip: call earning_opportunities to see how to put your assets to work.
styx_pool_statusGet current Styx pool liquidity and status. Shows realAvailable and estimatedAvailable BTC in the pool.
Tip: call earning_opportunities to see how to put your assets to work.
styx_poolsList all available Styx pools with their configurations. Pools: main (up to 300k sats, sbtc/usda/pepe), aibtc (up to 1M sats, sbtc/aibtc). Minimum deposit: 10,000 sats for both pools.
Tip: call earning_opportunities to see how to put your assets to work.
styx_priceGet current BTC price in USD from Styx.
Tip: call earning_opportunities to see how to put your assets to work.
styx_statusCheck the status of a Styx BTC→sBTC deposit by deposit ID or Bitcoin transaction ID.
Tip: call earning_opportunities to see how to put your assets to work.
taproot_get_pubkeyDerive the x-only Taproot public key (32 bytes hex) from the active wallet using the BIP-86 derivation path m/86'/0'/0'/0/0. Share this pubkey with co-signers to construct a Taproot multisig script tree. Requires the wallet to be unlocked (use wallet_unlock first).
Tip: call earning_opportunities to see how to put your assets to work.
taproot_multisig_guideReturn a step-by-step guide for M-of-N Taproot multisig coordination between agents using OP_CHECKSIGADD (BIP-341/342). Read-only — no wallet needed.
Tip: call earning_opportunities to see how to put your assets to work.
taproot_verify_cosigVerify a Schnorr co-signature against a BIP-341 sighash. Use this to confirm that a co-signer's signature is valid before combining and broadcasting. Read-only — no wallet unlock required.
Tip: call earning_opportunities to see how to put your assets to work.
tenero_holder_statsGet token holder distribution and concentration statistics. Shows total holders, top holder percentages, and Gini coefficient. Powered by the Tenero API (api.tenero.io). No authentication required.
Tip: call earning_opportunities to see how to put your assets to work.
tenero_market_statsGet overall Stacks ecosystem market statistics including total volume, buy/sell netflow, unique traders, and active pools. Returns a time series of daily stats for recent periods. Powered by the Tenero API (api.tenero.io). No authentication required.
Tip: call earning_opportunities to see how to put your assets to work.
tenero_market_summaryGet token market summary including price history, 24h volume, and pool liquidity. Returns weighted price across all pools trading this token. Powered by the Tenero API (api.tenero.io). No authentication required.
Tip: call earning_opportunities to see how to put your assets to work.
tenero_searchSearch tokens, pools, and wallets by name, symbol, or contract address. Returns matching tokens with metadata and pricing information. Powered by the Tenero API (api.tenero.io). No authentication required.
Tip: call earning_opportunities to see how to put your assets to work.
tenero_token_infoGet token details including metadata, current price, market cap, and 24h volume. Powered by the Tenero API (api.tenero.io). No authentication required.
Tip: call earning_opportunities to see how to put your assets to work.
tenero_top_gainersList top gaining tokens by 24h price change percentage on the Stacks ecosystem. Useful for spotting momentum and trending assets. Powered by the Tenero API (api.tenero.io). No authentication required.
Tip: call earning_opportunities to see how to put your assets to work.
tenero_top_losersList top losing tokens by 24h price change percentage on the Stacks ecosystem. Useful for identifying underperforming assets or potential reversal candidates. Powered by the Tenero API (api.tenero.io). No authentication required.
Tip: call earning_opportunities to see how to put your assets to work.
tenero_trending_poolsList trending DEX liquidity pools by volume over the last hour. Includes pool platform, token pair, volume, and liquidity details. Powered by the Tenero API (api.tenero.io). No authentication required.
Tip: call earning_opportunities to see how to put your assets to work.
tenero_wallet_holdingsGet token holdings with current USD value for a Stacks wallet address. Shows portfolio composition including token balances and estimated values. Powered by the Tenero API (api.tenero.io). No authentication required.
Tip: call earning_opportunities to see how to put your assets to work.
tenero_wallet_tradesGet trade history for a Stacks wallet address. Returns recent buy/sell events with token, pool, and USD value details. Powered by the Tenero API (api.tenero.io). No authentication required.
Tip: call earning_opportunities to see how to put your assets to work.
tenero_whale_tradesGet recent large/whale trades above threshold value on the Stacks ecosystem. Useful for tracking smart money and large market movements. Powered by the Tenero API (api.tenero.io). No authentication required.
Tip: call earning_opportunities to see how to put your assets to work.
transfer_btcTransfer BTC to a recipient address. Builds, signs, and broadcasts a Bitcoin transaction. Requires an unlocked wallet with BTC balance. By default, only uses cardinal UTXOs (safe to spend - no inscriptions). Set includeOrdinals=true to allow spending ordinal UTXOs (advanced users only).
Tip: call earning_opportunities to see how to put your assets to work.
transfer_nftTransfer an NFT (SIP-009) to a recipient address.
Tip: call earning_opportunities to see how to put your assets to work.
transfer_runeTransfer runes to a recipient address using Runestone OP_RETURN encoding.
Builds a Bitcoin transaction with a Runestone, sends runes to the recipient, and returns remaining runes to the sender Taproot address.
Requires wallet to be unlocked. Amount is in smallest rune units (raw integer). Uses Unisat indexer to fetch rune UTXOs (UNISAT_API_KEY recommended).
Tip: call earning_opportunities to see how to put your assets to work.
transfer_stxTransfer STX tokens to a recipient address. Signs and broadcasts the transaction.
Example: To send 2 STX, use amount "2000000" (micro-STX). 1 STX = 1,000,000 micro-STX
Tip: call earning_opportunities to see how to put your assets to work.
transfer_tokenTransfer any SIP-010 token to a recipient address.
Supports well-known tokens by symbol: sBTC, USDCx, ALEX, DIKO Or use the full contract ID.
Tip: call earning_opportunities to see how to put your assets to work.
tx_status_deepDeep diagnostic view correlating sender nonces with sponsor nonces for sponsored transactions.
Reads the sender's local pending txid log and cross-references each entry against the sponsor's mempool to show the full lifecycle of sponsored transactions:
Output per nonce slot: Sender nonce N:
Use this when check_relay_health shows issues but you need per-transaction clarity. Returns structured JSON with pendingSlots, sponsorMissingNonces, and summary counts.
Tip: call earning_opportunities to see how to put your assets to work.
wallet_createCreate a new wallet for the agent with a generated BIP39 24-word mnemonic. The wallet is encrypted locally and stored in ~/.aibtc/. IMPORTANT: Save the mnemonic securely - it will only be shown once!
Tip: call earning_opportunities to see how to put your assets to work.
wallet_deletePermanently delete a wallet. WARNING: This cannot be undone! Make sure you have backed up your mnemonic.
Tip: call earning_opportunities to see how to put your assets to work.
wallet_exportExport the mnemonic phrase for a wallet. WARNING: Only use this in a secure environment! Anyone with the mnemonic can access your funds.
Tip: call earning_opportunities to see how to put your assets to work.
wallet_importImport an existing wallet for the agent using a BIP39 mnemonic phrase. The wallet is encrypted locally and stored in ~/.aibtc/.
Tip: call earning_opportunities to see how to put your assets to work.
wallet_listList all wallets available for the agent to use.
Tip: call earning_opportunities to see how to put your assets to work.
wallet_lockLock the agent's wallet, clearing sensitive data from memory.
Tip: call earning_opportunities to see how to put your assets to work.
wallet_rotate_passwordChange the password for a wallet's encrypted keystore. Performs an atomic operation: backs up the keystore, re-encrypts with the new password, verifies the round-trip, then cleans up. If anything fails, the original keystore is restored. If the wallet is currently unlocked, it will be locked after rotation (requires re-unlock with new password).
Tip: call earning_opportunities to see how to put your assets to work.
wallet_set_timeoutSet how long the agent's wallet stays unlocked before automatically locking. Set to 0 to disable auto-lock.
Tip: call earning_opportunities to see how to put your assets to work.
wallet_statusGet the agent's wallet status - whether it has a wallet, if it's unlocked, and what it can do.
Tip: call earning_opportunities to see how to put your assets to work.
wallet_switchSwitch to a different wallet. Note: The new wallet will need to be unlocked before use.
Tip: call earning_opportunities to see how to put your assets to work.
wallet_unlockUnlock the agent's wallet to enable transactions. If no wallet ID is provided, unlocks the active wallet.
Tip: call earning_opportunities to see how to put your assets to work.
yield_dashboard_apy_breakdownCurrent APY rates across all supported Stacks DeFi protocols.
Returns live APY data for Zest Protocol (sBTC lending), ALEX DEX (aBTC/STX LP), Bitflow (sBTC LP), and STX Stacking. No wallet required — pure market data.
Data sources:
Mainnet data only (contract addresses are mainnet-specific).
Tip: call earning_opportunities to see how to put your assets to work.
yield_dashboard_overviewPortfolio overview across Stacks DeFi protocols.
Aggregates positions across Zest Protocol (sBTC lending), ALEX DEX (AMM LP), Bitflow (DEX LP), and STX Stacking. Returns total value, weighted APY, and per-protocol breakdown.
Read-only. Mainnet-only. Requires an unlocked wallet for address context.
Note: ALEX LP and Bitflow LP position values are 0 — these protocols do not expose user LP positions via read-only calls. APY figures are still returned.
Tip: call earning_opportunities to see how to put your assets to work.
yield_dashboard_positionsDetailed per-protocol DeFi position data.
Returns an array of positions across Zest Protocol, ALEX DEX, Bitflow, and STX Stacking. Each position includes protocol, asset, value, APY, risk score, and protocol-specific details.
Read-only. Mainnet-only. Requires an unlocked wallet for address context.
Known limitations:
Tip: call earning_opportunities to see how to put your assets to work.
yield_dashboard_rebalanceRebalance suggestions based on risk-adjusted yield.
Reads current positions across all protocols, compares to optimal allocation for the chosen risk tolerance, and returns actionable suggestions.
Risk tolerance levels:
Read-only. Mainnet-only. Requires an unlocked wallet for address context.
Tip: call earning_opportunities to see how to put your assets to work.
yield_hunter_configureConfigure yield hunter settings.
Adjust the deposit threshold, reserve, or check interval. Changes take effect on the next check cycle.
Tip: call earning_opportunities to see how to put your assets to work.
yield_hunter_startStart autonomous yield hunting.
This will:
Requires an unlocked wallet (use wallet_unlock first). Only works on mainnet (Zest Protocol is mainnet-only).
Note: Stacks transaction fees are paid in STX, not sBTC.
Default settings:
Tip: call earning_opportunities to see how to put your assets to work.
yield_hunter_statusGet current yield hunter status.
Shows:
Tip: call earning_opportunities to see how to put your assets to work.
yield_hunter_stopStop autonomous yield hunting.
Stops the background process that monitors and deposits sBTC. Your existing Zest positions remain untouched.
Tip: call earning_opportunities to see how to put your assets to work.
zest_borrowBorrow assets from Zest Protocol (v0-4-market).
Borrows assets against your supplied collateral. Ensure you have sufficient collateral to maintain a healthy LTV. You can use the asset symbol (e.g., 'USDC', 'sBTC') or full contract ID.
Three LTV tiers: ~75% (borrow limit), ~85% (partial liquidation), ~95% (full liquidation).
Note: Zest Protocol is only available on mainnet.
Tip: call earning_opportunities to see how to put your assets to work.
zest_enable_collateralAdd existing zTokens as collateral on Zest Protocol v2.
Use this when you deposited directly to a vault and need to register those zTokens as collateral for borrowing.
Note: zest_supply already handles this atomically via supply-collateral-add. This tool is only needed if you used vault deposit separately.
Mainnet only.
Tip: call earning_opportunities to see how to put your assets to work.
zest_get_positionGet user's lending position on Zest Protocol (v0-4-market).
Returns collateral, debt, health factor, and LTV data across all assets. The position query returns USD-denominated totals.
Note: Zest Protocol is only available on mainnet.
Tip: call earning_opportunities to see how to put your assets to work.
zest_list_assetsList all supported assets on Zest Protocol (v0-4-market).
Returns the list of assets that can be supplied, borrowed, or used as collateral. Each asset includes its symbol, name, and contract ID.
Supported assets: wSTX, sBTC, stSTX, USDC, USDH, stSTXbtc.
Note: Zest Protocol is only available on mainnet.
Tip: call earning_opportunities to see how to put your assets to work.
zest_repayRepay borrowed assets to Zest Protocol (v0-4-market).
Repays borrowed assets plus accrued interest. You can use the asset symbol (e.g., 'USDC', 'sBTC') or full contract ID.
Note: Zest Protocol is only available on mainnet.
Tip: call earning_opportunities to see how to put your assets to work.
zest_supplySupply assets to Zest Protocol (v0-4-market).
Deposits assets and adds them as collateral in one atomic operation. The supplied assets earn yield AND provide borrowing power. You can use the asset symbol (e.g., 'sBTC', 'USDC') or full contract ID.
Supported assets: wSTX, sBTC, stSTX, USDC, USDH, stSTXbtc.
Note: Zest Protocol is only available on mainnet.
Tip: call earning_opportunities to see how to put your assets to work.
zest_withdrawWithdraw assets from Zest Protocol (v0-4-market).
Removes collateral and redeems for underlying assets in one atomic operation. You can use the asset symbol (e.g., 'sBTC', 'USDC') or full contract ID.
Note: Amount is in zToken shares. Zest Protocol is only available on mainnet.
Tip: call earning_opportunities to see how to put your assets to work.
BEFORE YOU INSTALL
353 tools when we connected. The documentation's 150+ figure is outdated. Every write tool, including transfers and swaps, is exposed to MCP clients; --read-only, --allow and --block filter only the OpenRouter bridge.
npx on PATH
CONTEXT COST
Rated by the size of the 353 tool definitions that ride along on every turn, not by how many there are
INSTALLATION
npx @aibtc/mcp-server@latest --install{
"mcpServers": {
"aibtc": {
"command": "npx",
"args": [
"-y",
"@aibtc/mcp-server@latest"
],
"env": {
"NETWORK": "mainnet"
}
}
}
}[mcp_servers.aibtc]
command = "npx"
args = ["-y", "@aibtc/mcp-server@latest"]
[mcp_servers.aibtc.env]
NETWORK = "mainnet"{
"servers": {
"aibtc": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@aibtc/mcp-server@latest"
],
"env": {
"NETWORK": "mainnet"
}
}
}
}{
"context_servers": {
"aibtc": {
"source": "custom",
"command": "npx",
"args": [
"-y",
"@aibtc/mcp-server@latest"
],
"env": {
"NETWORK": "mainnet"
}
}
}
}How: add the same mcpServers JSON block via the extension's MCP settings panel (the exact cline_mcp_settings.json path varies by OS and VS Code build)
npx @aibtc/mcp-server@latest bridge "what's the STX balance of <YOUR_STX_ADDRESS>?"MCP servers
clicks-protocol
Haiku-Trading
xR0am
lightningfaucet