shared metadata for MCP/server consumers from cambrian/metadata
CLI commands as MCP-ready tools (same validation, defaults, and query) from cambrian/tools
The package does not bundle your API key.
The installed package does not read project-local .env files. Pass credentials with CLI flags or environment variables in the invoking process.
Best Path
Use the package in one of three ways:
Direct CLI: best when a human or agent can just run commands
Packaged skill bundle: best for Claude Code or OpenCode style agent runtimes
MCP setup helpers: best when a client supports Model Context Protocol tools
describe opencli: best for tool-aware runtimes that want a machine-readable command contract
If the goal is fast agent activation, the usual order is:
install the package
expose CAMBRIAN_API_KEY to the process that will run the agent
verify one successful query
install or print the packaged skill, configure MCP, or load describe opencli
Requires API Access
Installing the package is not enough for live reads.
You need a valid CAMBRIAN_API_KEY or --api-key <key>
Get an API key at https://console.cambrian.org/, or use cambrian pay --help
for x402 pay-per-call access without an API key
skill install only installs the packaged skill bundle; it does not provision API access
the agent or CLI process itself must see the API key in its runtime environment
Base URLs:
Solana + EVM: https://api.cambrian.org
Deep42: https://api.cambrian.org/deep42
Risk: https://api.cambrian.org/risk
Persisted API Key & Shell Completion
To avoid exporting CAMBRIAN_API_KEY in every shell, persist it once:
cambrian config status # check setup without exposing the key
cambrian config set-key <your-api-key> # writes ~/.config/cambrian/config.json (mode 0600)
cambrian config get-key # compatibility command: prints the full key
cambrian config clear # remove it
Key precedence (highest first): --api-key → CAMBRIAN_API_KEY → stored config
file. Storage honors XDG_CONFIG_HOME (and %APPDATA% on Windows). Prefer
config status for inspection. A key supplied to set-key may remain in shell
history, so use CAMBRIAN_API_KEY when persistence is not required.
Shell completion delegates to the CLI's own metadata, so it stays in sync with
the endpoint list:
# Run each append command only once; rerunning it duplicates shell configuration.
cambrian completion bash >> ~/.bashrc
cambrian completion zsh >> ~/.zshrc
cambrian completion fish > ~/.config/fish/completions/cambrian.fish
Runtime Endpoint Discovery
The installed 81-endpoint public snapshot is the offline safety fallback. After a
successful refresh, validated production OpenAPI is authoritative for the
active command group, so compatible endpoint additions, updates, and removals
appear without reinstalling cambrian or publishing another npm version.
EVM and Solana each load their chain-specific production OpenAPI document.
Either group uses the legacy combined document only when its primary is
unavailable; primary and fallback schemas are never merged.
The EVM registry is projected by chain: base is pinned to
chain_id=8453, ethereum to chain_id=1, arbitrum to chain_id=42161,
robinhood to chain_id=4663, and bnb to chain_id=56.
Each group lists only the operations that support its chain. Chains are
table-driven from EVM_CHAINS in src/cli/evm-chains.ts and audited against
the OpenAPI chain_id enums with npm run check:chains.
New chains need no CLI upgrade. Any chain id the live OpenAPI advertises is
usable immediately as cambrian chain-<id> <resource> (for example
cambrian chain-10 tokens). When the API names the chain (OpenAPI
x-enum-varnames on chain_id, or /evm/chains when an API key is set),
the CLI also serves it under that name, for example cambrian monad tokens.
chain-<id> stays a valid alias. cambrian schema chains lists every
supported chain.
The chain group selects the chain, so endpoint help does not show
--chain-id. A conflicting --chain-id exits 2 and names the command to
use. Endpoint help ends with the other chains that serve the same endpoint.
Validated results are cached for 15 minutes. Successful, failed, explicit,
unknown-resource, and concurrent attempts all share the same per-physical-URL
request floor. EVM and Solana share a fallback attempt only when both need the
same legacy document.
ETag and Last-Modified revalidation avoid unnecessary downloads after the
15-minute floor expires. Unknown resources use the current cache until then.
Shell completion is cache-only and never waits on network access. A normal
command, group help, or eligible explicit refresh populates it.
Only concrete GET operations with query parameters in the supported
primitive/array profile are exposed. Bodies, path parameters, catch-all
routes, non-GET methods, ambiguous names, and malformed schemas stay hidden.
A valid refresh atomically replaces the active registry, including changed or
removed operations. A failed or structurally invalid refresh leaves the
last-known-good cache active, then falls back to the installed snapshot when
no valid cache exists.
schema status reports operations added or changed relative to the bundle,
bundled operations removed upstream, operations hidden by llms.txt, and
cached additions changed or removed by the latest successful refresh.
When at least five compatible operations for a group are present in
llms.txt, only that documented intersection is exposed. With fewer than
five, the CLI falls back to the complete compatible OpenAPI list. This policy
applies to the whole live registry. The bundled snapshot is generated with
the same policy at release time and is not re-filtered while offline.
The cache honors XDG_CACHE_HOME (and the platform cache directory elsewhere),
uses private directory/file modes, and never stores API keys.
If a valid refresh succeeds while the cache is temporarily unwritable, that
invocation still uses the validated live metadata and reports a warning; failed
atomic writes also clean up their temporary files on a best-effort basis.
cambrian schema chains
cambrian schema status [solana|base|ethereum|arbitrum|robinhood|bnb|deep42|risk]
cambrian schema refresh [solana|base|ethereum|arbitrum|robinhood|bnb|deep42|risk]
cambrian schema clear-cache [solana|base|ethereum|arbitrum|robinhood|bnb|deep42|risk]
# Never refresh metadata for this invocation:
cambrian solana latest-block --offline
# Emergency process-wide compatibility switch:
CAMBRIAN_SCHEMA_MODE=bundled cambrian solana latest-block
schema refresh requests a refresh only after the source's 15-minute cooldown
has elapsed; it never bypasses that floor. schema clear-cache removes
last-known-good endpoint metadata but intentionally leaves the request cooldown
intact. These rules keep refresh scripts, typos, failures, and concurrent CLI
processes from turning into OpenAPI request bursts.
A package release is still required when the interpreter itself needs a new
capability, such as request bodies, another HTTP method, a new authentication
model, or a previously unsupported OpenAPI construct.
Documentation guides are indexed independently from the API schema. The CLI
reads the live ## Available Guides section, so publishing another guide there
requires no CLI release:
As an alternative to an API key, cambrian pay <group> <resource> pays for a
single call with USDC on Base via the x402 protocol. The
gateway supplies the current price and the CLI previews it before payment;
settlement is facilitator-backed, so you pay no gas. Works for every advertised
data group (solana, base, deep42, risk).
This path is opt-in and keeps the core install dependency-free, so the signing
libraries are not bundled — install them once alongside the CLI:
npm install -g @x402/core @x402/fetch @x402/evm viem
export CAMBRIAN_X402_PRIVATE_KEY=0x<base-mainnet-key-funded-with-usdc>
# Preview the price first (no spend) — then authorize with --yes:
cambrian pay deep42 social-data/alpha-tweet-detection --limit 1
cambrian pay deep42 social-data/alpha-tweet-detection --limit 1 --yes
cambrian pay base price-current --token-address 0x4200000000000000000000000000000000000006 --timeout 90000 --yes
Safeguards: every call prints a cost preview and requires --yes before
spending; --max-amount <usd> caps the price (default 0.10); --timeout <ms>
bounds both the unpaid probe and paid gateway request (default 90000); the
pay path validates endpoint params before the x402 probe and blocks identical
retries while a previous paid attempt may still be pending; the wallet key is
read only from CAMBRIAN_X402_PRIVATE_KEY at runtime and is never stored or
logged. See the live x402 guide
or docs/x402.md for the full protocol details.
Features
Solana DeFi: pool metrics for Meteora DLMM, Raydium CLMM, and Orca; token details, holders, security audits; OHLCV candles; prices (current, hourly, unix, multi); pool and token transactions; trade statistics; trader leaderboards; trending tokens; wallet balance history
EVM DeFi: pool metrics for Aerodrome v2/v3, Uniswap v3, SushiSwap v3, PancakeSwap v3, Alienbase v3, Clones v3; lending coverage for Aave, Euler, and Morpho; LP provider summaries and fee metrics; TVL rankings; DEX discovery; EVM token prices and lists
Social intelligence: alpha tweet detection with multi-dimensional scoring, influencer credibility rankings with track records, sentiment shift detection for identifying market-moving changes
Perpetual risk: risk engine simulations for position sizing and liquidation analysis
Agent-friendly CLI with clean error output, scoped subcommand help, and self-description via cambrian describe opencli
Packaged skill bundle for Claude and OpenCode installs
Typed TypeScript client from the root package export
MCP setup helpers for hosted and local npx -y cambrian-api-mcp usage
These apply to every data command (solana / base / ethereum /
arbitrum / robinhood / bnb / deep42 / risk). The
default output is unchanged (pretty JSON), so all flags are opt-in.
Flag
Effect
--output table|json|tsv
Render tabular results as an aligned table or TSV (default json; non-tabular data falls back to JSON)
--fields a,b,c
Project the response to only these columns/fields (smaller payloads for agents)
--all
Auto-paginate and merge all pages (paginated resources only). --all sets the page size, so do not combine it with --limit
--max-items <n>
Cap total rows requested with --all (default 10000). Each page asks only for the rows still needed
--retries <n>
Retry transient failures (408/429/5xx) with jittered backoff (default 0)
--json
Emit structured JSON errors on stderr; successful output is controlled by --output and already defaults to JSON
--timeout <ms>
Per-request timeout (default 90000)
--api-key <key>
API key for this call (else CAMBRIAN_API_KEY)
--offline
Do not refresh endpoint metadata; data requests still require network
Use cambrian to find trending Solana tokens and analyze the top one.
Use cambrian to detect recent high-alpha tweets and check the credibility of those influencers.
Use cambrian to find the best Aerodrome v2 pools on Base by TVL and fee generation.
Use cambrian to assess the risk of a 5x leveraged SOL perp position.
Use cambrian to check sentiment shifts and compare to on-chain trading activity.
Installing the skill bundle does not provision API access. The agent process itself still needs CAMBRIAN_API_KEY in its runtime environment.
The hosted API returns standard rate-limit headers:
X-RateLimit-Limit
X-RateLimit-Remaining
X-RateLimit-Reset
Retry-After on 429
When the CLI is throttled, it prints a clean retry message instead of a stack trace.
Package Scope
The published npm package is intentionally limited to agent-facing surfaces. Repository-specific tooling, local development workflows, and self-hosting setups live in the GitHub repository, not in the npm contract.