Credits and billing

What a pull costs

2 credits for one answer from token_overview, today, get_sections, search_tokens, list_ecosystems, pay_attention, render_chart or render_card_html. token_series is 2 credits per token: three tokens in one call are 6 credits. explain_metric, credit_costs and get_account are free

A token's launch bundles cost what the site's bundle scan costs: 5 credits for get_sections asked for launch_bundles or for all sections, and for the bundles card from render_chart or render_card_html. A get_sections answer without the bundles (the token has none ready) is a pull, 2 credits

compare_tokens and screen_tokens answer one row of each token's latest figures, so they are priced by size: a comparison is 2 credits for the first token and 1 for each added one (12 tokens: 13), and a screen is 2 credits per 20 rows it returns (limit: 100: up to 10). The balance must cover the rows you ask for; a screen that returns fewer pays for what it returned

A pull's credits are taken from the balance when it starts, so calls made at the same time can't spend the same credits twice: each one needs its own. If the pull doesn't answer, they are given back at once: a refusal, an error and a tool that couldn't answer cost nothing. The refresh a paid pull starts behind its answer is free, and runs only for tokens Blocktronics already covers; a token it doesn't is ingested, quoted first

The site's own data feeds

The site's pages read feeds of their own, free in the browser. They aren't an API: from anywhere else, use the API, which serves the same data and more with one key (start with GET /v1/catalog)

• /api/token (a token's full read) and /api/signals/token (its signals) answer outside the site only with a key: 5 and 1 credit a call
• /api/ext/token, the browser extension's panel, is free with no account, up to 500 panels a day per address (an IPv6 address counts by its /64); past that, 2 credits a panel with a key. The token list behind the extension's search is open the same way
• The rest (every token's row, the market parts of the token list, the engine sections, the Outlook's layout) serve the site only: outside it the answer is 401 key_required, or 403 site_only with a key, naming the API tool that serves the same. The Outlook isn't served while it's greyed out on the site

The site's own pages are limited per address too, far above what a person browses

Signals and the readout

token_signals (or signals in a query) gives a token's signals: the Blocktronics read, whether it leans bullish, bearish or balanced, and every fired signal with its finding. 1 credit per token; they are free on the site

With readout: true (or readout in a query) you get the full readout: each signal's proof and how the evidence is weighed. It costs what it costs on the site, 10 credits, and the token's readout then stays open for 24 hours on the API, the MCP and the site. While it is open, asking for the token's signals or readout costs nothing more

A query

POST /v1/query costs the sum of what it runs: 2 credits per token for each of metrics, today, overview and sections, 1 per token for signals, and the readout at its own price. 5 tokens with metrics and today are 20 credits. The balance must cover every pull before anything runs; if it can't, the answer is 402 insufficient and nothing is charged. A part that fails isn't charged

Ingesting a new token

A token Blocktronics hasn't indexed is quoted first, by its age. The quote is taken from your balance when the build starts, once, and given back if the build fails. From then on it is a token like any other: 2 credits a pull. See how ingesting works.

"By its size" is a formula over the token's chain, its age and its transfers so far. No ingest costs more than 250 credits

The MCP

The same account and keys connect the Blocktronics MCP. Its data tools are the API's, at the same prices. About the MCP.

Getting credits

Credits are prepaid, with no auto-renew. Buy them on your account page with USDC or $BLOCKTRONICS, or earn them back as rebates when you swap through Blocktronics. Every key on an account draws from the same balance. See every price.

Top-ups by your agent

An agent can keep its own account topped up, paying with USDC from its own wallet. Allow it once on your account page (Keys, then Manage on the key): name the agent's wallet and two limits, the most credits a top-up and the most a day. The agent's wallet then signs once for the key (POST /v1/topup/wallet), so nobody can name a wallet they don't hold. Then the agent asks for a quote, sends exactly the quoted amount from that wallet, and the credits land on your account a few blocks after it confirms. They are final

• POST /v1/topup/quote with {"credits": 500} (and chain: base, the default, ethereum or robinhood) answers what to send: pay.amount of pay.token from pay.from to pay.to, and the same as a ready transfer, before valid_until.
• GET /v1/topup/{quote_id} answers pending or credited, with the credits and the transaction. GET /v1/topup?tx=0x… answers the same by the payment's hash
• Until the wallet has signed, a quote answers 403 wallet_unproven. POST /v1/topup/wallet with {} answers the message to sign; send it back as {"nonce", "signature"}. Naming another wallet on the site needs its own signature; new limits on the same wallet don't
• A payment counts only from the wallet you named, with the quote's exact amount: a hash alone never credits anything, and nobody can claim someone else's transfer. Over a limit, the answer is 403 over_topup_limit or 429 topup_day_limit and nothing is quoted
• One paying wallet holds at most 20 open quotes at a time, counting quotes from the last 7 days that a late payment could still pay. Past that the answer is 429 refused with refused: "too_many_quotes": pay one, or wait a few days

An agent with its own account (a key made from its wallet, see Authentication) needs no one to allow it: it tops up from that same wallet, up to 25,000 credits at a time and 100,000 a day for the whole account, however many keys it has

import os, time, requests
from eth_account.messages import encode_defunct
from web3 import Web3

API = "https://api.blocktronics.xyz/v1"
H = {"Authorization": f"Bearer {os.environ['BLOCKTRONICS_KEY']}"}
w3 = Web3(Web3.HTTPProvider(os.environ["BASE_RPC_URL"]))
agent = w3.eth.account.from_key(os.environ["AGENT_PRIVATE_KEY"])  # the wallet the key's top-ups come from

# 0. Once per wallet: the agent's wallet signs for the key, so nobody can name a wallet they don't hold.
p = requests.post(f"{API}/topup/wallet", headers=H, json={}, timeout=30).json()
if not p["proven"]:
    sig = agent.sign_message(encode_defunct(text=p["message"])).signature.hex()
    requests.post(f"{API}/topup/wallet", headers=H, json={"nonce": p["nonce"], "signature": "0x" + sig.removeprefix("0x")}, timeout=30).raise_for_status()

# 1. A quote: the exact amount to send, from the agent's wallet, credited to the account.
q = requests.post(f"{API}/topup/quote", headers=H, json={"credits": 500}, timeout=30).json()

# 2. Send exactly that: the quote's transfer, unchanged (its last digits tag the quote).
tx = {"to": q["transfer"]["to"], "data": q["transfer"]["data"], "value": 0, "from": agent.address,
      "nonce": w3.eth.get_transaction_count(agent.address), "chainId": 8453}
tx["gas"] = w3.eth.estimate_gas(tx)
tx.update({"maxFeePerGas": w3.eth.gas_price * 2, "maxPriorityFeePerGas": w3.to_wei(0.01, "gwei")})
h = w3.eth.send_raw_transaction(agent.sign_transaction(tx).raw_transaction).hex()

# 3. Follow it: credited a few blocks after it confirms.
while True:
    s = requests.get(f"{API}/topup/{q['quote_id']}", headers=H, timeout=30).json()
    if s["state"] == "credited":
        break
    time.sleep(10)
print("credited", s["credits"], "tx", h)

Check before you call

GET /v1/account answers your balance and the prices, and GET /v1/catalog each tool's price. Both are free, and every answer says what it charged.

curl "https://api.blocktronics.xyz/v1/account" \
  -H "Authorization: Bearer $BLOCKTRONICS_KEY"

Enterprise

Committed volume, custom outputs, invoiced settlement and direct support are agreed with enterprise accounts. Discuss your requirements.

Next