Every example with a Run button sends a real request to the live engine and shows exactly what comes back.
Quick start
Specula is an HTTP API. There is no sign-up and no key. Ask for a feed by its id and you get a signed answer.
GET/v1/feeds/chain.price?symbol=ETH
The full list of feeds, with parameters and prices, is one request away. The catalog page is drawn from the same list.
GET/v1/catalog
In code, the SDK does the asking, the paying and the checking:
npm install @specula/sdk viem
import { Specula } from"@specula/sdk";
import { privateKeyToAccount } from"viem/accounts";
const specula = new Specula({
// the agent's own wallet
account: privateKeyToAccount(process.env.AGENT_KEY),
// never pay more than this for one answer
maxPricePerCall: "0.05",
// stop after this much
budget: "2.00",
});
const nvda = await specula.price("NVDA");
console.log(nvda.data.price, nvda.source);
console.log(nvda.meta.price.amount);
// 8-K events, decodedconst events = await specula.events("TSLA");
// up to an hour old, a fifth of the priceconst cheap = await specula.economy({ fresh: "delayed" });
The answer
Every feed answers in the same shape, whatever its source.
data the answer itself.
source which source answered, and meta.tried every source that was tried on the way.
collectedAt when the data was collected, in unix seconds. meta.ageSeconds says how old it was when served.
meta.price what was charged, and meta.paidBy how: free allowance, x402 or credits.
proof the engine's address, the digest of the answer and the signature over it.
The signature covers the feed, the parameters, the data, the source and the collection time together, so none of them can be changed afterwards.
Paying
Payment uses x402, the HTTP way of paying for a request. When a call needs payment the engine answers 402 and says exactly what it wants:
The agent signs a one-time transfer of exactly that amount to that address (EIP-3009, transferWithAuthorization) and sends the request again with the signature in an X-PAYMENT header. The signature can move that amount once, to that address, before it expires. It cannot be reused or changed.
The engine checks the payment, collects the answer, and only then settles the payment on chain. If no source can answer, nothing is settled and the reply says "charged": false.
What a call costs right now, for you:
GET/v1/quote/chain.price
Prices and levels
Each feed has a price for a live answer. Add fresh=recent to accept an answer up to five minutes old for half the price, or fresh=delayed for one up to an hour old at a fifth.
Wallets that buy more pay less. What a wallet paid over the last 30 days sets its level: 10 USDG gives 10% off, 100 gives 20%, 1,000 gives 30%.
Allowance, budgets, credits
Every wallet gets 100 free calls a day, and a caller without a wallet gets 25. A wallet identifies itself by signing one readable line, which the SDK does for you:
Authorization: Specula <address>.<expiry>.<signature>
// the signed line reads: "Specula access for 0xabc... until 1794900000"
GET /v1/account shows the allowance used, the level, credits and spend.
POST /v1/budget with {"daily": "2.50"} sets a daily limit. A call that would pass it is refused before anything is charged.
POST /v1/credits/topup?amount=5 prepays credits with one payment. Calls are then paid from the balance with no round trip.
GET /v1/receipts lists a signed receipt for every payment, with its transaction.
@specula/sdk is a small TypeScript client. It signs in, answers a 402 with a signed payment, refuses to pay more than you allow, and checks every answer's signature before returning it.
@specula/mcp gives any MCP client one tool per feed, each with its price in the description, plus tools to see the account and to ask a question. Without a key it uses the free allowance.
// claude_desktop_config.json, Cursor, or any MCP client// SPECULA_AGENT_KEY is optional: it pays past the free allowance
{
"mcpServers": {
"specula": {
"command": "npx",
"args": ["-y", "@specula/mcp"],
"env": {
"SPECULA_AGENT_KEY": "0x...",
"SPECULA_MAX_PRICE": "0.05",
"SPECULA_BUDGET": "2.00"
}
}
}
}
Agent frameworks
The same feeds as ready tools. Each tool's description carries its price, so a model can weigh cost before it calls.
Vercel AI SDK
import { generateText } from"ai";
import { speculaTools } from"@specula/ai-sdk";
const { text } = await generateText({
model, // any model the AI SDK supports // one tool per feed, priced
tools: await speculaTools({ account }),
maxSteps: 6,
prompt:
"Did any NVDA insider sell this month, and what is the stock at?",
});
A websocket at /v1/stream pushes events as they happen. The requests channel is open. prices, trades, launches and signals are metered by the minute: each minute uses one free call, then 0.0005 USDG from credits. A channel that cannot pay is paused and says why.
Signals are rules over the data. The built-in ones are public with their track record on the signals page. A wallet can keep its own rules, written in plain words. Try a sentence:
POST/v1/signals/parse
const rule = await specula.addSignal("a buy over $10k on the DEX");
specula.stream(["signals"], (e) => console.log(e.data));
Ask the data
One feed takes a question instead of parameters. It picks the feeds that can answer, collects them, and writes an answer in which every sentence cites the signed answer it came from.
To check an answer yourself: write feed, params, data, source, collectedAt as JSON with keys sorted and no spaces, hash it with keccak256, and recover the signer of that hash from the signature (an Ethereum signed message). It must be the engine's address.
Each hour, everything the engine signed is sealed into one Merkle root. Ask for the proof of any answer by its digest:
Specula computes its own indexes from on-chain prices. Any index or price is also available as a signed report that a smart contract can check by itself: whoever carries the report on chain does not need to be trusted.
GET/v1/oracle/index:ai
// Solidity, with the oracle contract
int256 value = oracle.read(bytes32("index:ai"), 1 hours); // reverts if older than an hour
Selling data
Any wallet can list a feed on the marketplace: a public https endpoint that returns JSON, with a price per call. Buyers pay the seller's wallet directly; a seller's feed has no free allowance. If the endpoint fails, the buyer is not charged.
await specula.listFeed({ slug: "weather", title: "City weather now",
summary: "Temperature and wind for a city, from a station network.",
price: "0.25", url: "https://api.example.com/weather",
params: [{ name: "city", required: true }] });
await specula.myFeeds(); // paid calls and what was earned
Add allow: [wallets] and the feed is private: it exists only for those wallets. To ask for data nobody sells yet, post a bounty with specula.postBounty() and fund it in the escrow contract.
GET/v1/market
Archive and lab
The archive keeps answers as they were collected, each with its original signature. archive.at returns what a feed said at a moment; archive.range replays a stretch of time.
A team is one owner, many agent wallets and one shared daily budget. A wallet joins only by accepting an invite with its own signature, and can leave at any time. A call that would take the team past its budget is refused before anything is charged, and the owner gets one report of who spent what.
const team = await specula.createTeam("Desk one", "5.00"); // 5 USDG a day, sharedawait specula.addToTeam(team.id, "0x...agent"); // an inviteawait agentClient.joinTeam(team.id); // the agent's own wallet accepts it
console.log(await specula.team());
A live price can also be put on any page as a widget: <iframe src="https://speculaagents.fun/embed/price/NVDA">.
Recipes
Three small agents in the repository, each a single file you can run:
Launch watcher. Streams new launches, reads the first buyers and the deployer's history, and writes a short note on each.
Filing reader. Watches a list of companies for new 8-K events and insider trades, and summarises each with links to the paragraph.
Morning desk. Once a day, spends a fixed budget on the price board, the economy snapshot and the briefing, and prints one page.
cd packages && npm install && cd recipes
SPECULA_URL=http://localhost:4100 npx tsx launch-watcher.ts
Errors
Errors are JSON with a short error code and a plain message.
Status
Code
Meaning
400
missing_param, bad_param
The request is wrong. The message says which parameter.
402
free_allowance_used
Pay the amount in accepts[0] and ask again.
402
amount_too_low, bad_signature, ...
The payment was not accepted. Nothing was charged.
403
budget_reached
The wallet's own daily budget would be passed.
404
unknown_feed, unknown_symbol, ...
There is no such thing to ask about.
409
indexing
The engine is reading history for this request. Ask again shortly.