Hive Token Diligence

hive-token-diligence — Token Diligence

Build a provenance-aware diligence picture of one token: identity, market context, liquidity, holders, enrichment, and risk. Never answer from model memory when the conclusion depends on live data.

Task toolset and identifiers

Toolset: token_diligence. Read hive://toolsets/token_diligence before execution; it is authoritative for the current output schema, material-call budget, phases, fallback condition, and stop conditions.

• Required: chain/network plus exact token contract or provider-specific token id.
• Optional: quote token, pool address, holder wallet, time window.

If the user gives only a ticker or name, resolve the exact contract before execution. Tickers collide across chains, and scam tokens deliberately reuse well-known names — an answer keyed to the wrong contract is worse than no answer.

Before choosing endpoints, select exactly one matching entry from the exact workflow's routes[]. Follow its ordered steps, use a fallback only under that step's published condition, stop at four material calls, and preserve the selected route_id in the typed result. The broad coverageCatalog is discovery coverage, not an execution plan.

Procedure

1. Resolve chain and contract from the prompt, or ask for them.
2. Call search_tools for token metadata, market, holder, DEX liquidity, and risk capabilities matching the question.
3. Call get_api_endpoint_schema for each endpoint before calling it.
4. Call invoke_api_endpoint with schema-valid, bounded arguments.
5. Start with metadata and market/liquidity checks. Add holder distribution and enrichment only when the user needs depth, and security/risk checks when the user asks whether to trade, approve, or trust the token.
6. For supply-dilution or unlock questions, use CoinGecko supply breakdown and circulating/total supply charts when the configured plan permits them. Report a plan gate instead of substituting market-cap fields.

Bounded calls

• Limit holder lists and pool searches; do not page through everything for a quick read.
• Keep token-level data separate from pool-level data.
• Preserve provider-specific risk fields when they drive the conclusion.

Worked example

User: "Thinking about buying PEPE — contract 0x6982508145454Ce325dDbE47a25d4ec3d2311933 on Ethereum. Is it liquid and is anything sketchy in the holders?"

1. search_tools → {"query": "token metadata liquidity holders risk ethereum", "limit": 5}
2. get_api_endpoint_schema for the metadata, liquidity, and holder endpoints the search returned.
3. invoke_api_endpoint per schema — argument names come from the schema you just fetched (typically a contract address plus a network/chain field), never from memory.
4. Read each MCP response's _hive object for provider, fetched_at, observed_at, cache_age_ms, runtime_status, and receipt_id, then answer with the report template below. REST/client-adapter envelopes expose the equivalent fields under meta.

Report template

## Summary
[Token identity and overall diligence posture in one or two sentences.]

## Calls made
- Toolset: token_diligence
- Endpoint(s): [exact endpoint names]
- Identifiers: [chain, contract, pools, wallets]

## Evidence
- Metadata: [name, symbol, supply, verification]
- Market/liquidity: [price, volume, pool depth + venue]
- Holders: [concentration, notable wallets]
- Risk/enrichment: [flags, provider-specific fields]
- Provenance: [provider, fetched_at, observed_at/cache_age_ms, runtime status per call]

## Caveats
[Missing provider keys, plan gates, stale liquidity, unresolved ambiguity.]

## Next action
[Security drilldown, liquidity venue check, or holder analysis — only if needed.]

Gotchas

• A verified name/logo is not proof of safety.
• High FDV or high volume without pool depth can still be risky.
• Missing enrichment is not the same as a clean risk result.

Evidence receipt (required)

End every Hive-backed answer with a compact receipt built from the _hive object on each material tool response:

• provider, tool, fetched_at, observed_at, cache_age_ms, and runtime_status
• receipt_id, receipt_version, server/build version, and SHA-256 input/result digests when present (self-checks, not signatures)
• source, cache_status, truncated, and any warnings
• canonical chain/entity identifiers plus block, slot, transaction, or query ids present in provider data
• material provider disagreements and how they were handled
• checks that were unavailable, gated, stale, truncated, or intentionally not run
• a claims[] citation from each material statement to exact receipt IDs
• one coverage[] entry for every canonical evidence phase, with each gap explained

Never turn missing evidence into a clean result, silently merge conflicting provider values, or omit a degraded/fallback call from the receipt. observed_at is Hive's first-observation/original cache-population time, and cache_age_ms: 0 only means newly retrieved by Hive. Use provider time, block, slot, transaction, or candle close for source recency; if absent, mark it unknown. Run validate_task_result before presenting the typed workflow result; it checks structure but cannot authenticate an invented receipt.

Runtime status handling

Use Hive's runtime statuses directly: ok, invalid_input, missing_key, plan_required, rate_limited, degraded, failing. If one provider is gated (for example enrichment returns plan_required), keep the rest of the diligence report and mark that section unavailable rather than claiming diligence failed.

Hand-offs

• User is about to sign, approve, or swap → hive-security-risk.
• Pool-level depth, trades, or OHLCV → hive-dex-pool-analysis.
• Solana mint or DAS asset → hive-solana-analysis.