Recovery intelligence protocol
Documentation for agents that need evidence before action.
Root turns one public EVM address into a typed, source-backed recovery plan. It finds forgotten claims, rewards, LP positions, and planted-token risks, then stops before wallet execution.
1. Submit a public EVM address
Root accepts public addresses only. It never asks for a seed phrase, private key, wallet connection, OTP, or recovery signature.
2. Buy Root Check
Check is a low-cost claim-registry signal. It returns CANDIDATE, NO_SIGNAL, or INCONCLUSIVE; it is not a portfolio scan or recovery verdict.
3. Buy Root Recover only when Check qualifies
Recover builds the full evidence-backed root.v1 plan with source receipts, value after gas, risk findings, and policy verdicts.
4. Decide outside Root
Root prepares the plan. A user or downstream wallet agent decides whether to continue through an official action path after its own checks.
Get started
The buyer flow
CANDIDATE
BUY_ROOT_RECOVER
At least one raw registry signal exists; buy Recover only with fresh approval.
NO_SIGNAL
STOP_NO_UPSELL
All configured Check sources completed without a raw signal. This is not a clean-wallet result.
INCONCLUSIVE
RETRY_CHECK
One or more sources were incomplete and no positive signal overrode the uncertainty.
Core concepts
What Root returns
Root Check
A bounded paid triage product for raw claim-registry signal. It never returns amounts, calldata, policy verdicts, or recovery recommendations.
Root Recover
The full paid assessment. It verifies evidence, token identity, price, gas, action semantics, and official paths before producing a typed plan.
RecoveryPlan
The canonical root.v1 object. Prose is only a rendering of this machine-readable plan and its receipts.
SourceReceipt
A source-health entry for each material check, including status, latency, chain context, method, contract, evidence, and any failure code.
RecoveryIntent
An exact proposed action envelope with target, method, inputs, expected asset delta, gas, value, confidence, evidence ids, and user-confirmation requirement.
PolicyVerdict
ALLOW, REVIEW, BLOCK, or UNKNOWN. ALLOW is evidence readiness, not execution permission.
Plan states
ACTIONABLE
At least one recovery intent passed Root policy and can be explained to the user.
PROTECTED
Root found a safety issue or planted-token risk that should stop or warn the user.
CLEAN
Completed material coverage found no current recoverable action or protected risk.
PARTIAL
A useful plan exists, but material coverage is incomplete or unrelated evidence is unresolved.
INCONCLUSIVE
Root could not produce a trustworthy recovery state for this request.
Policy verdicts
ALLOW
Evidence is strong enough to describe the action. User confirmation is still mandatory.
REVIEW
Evidence exists, but a material fact needs human or downstream-agent review.
BLOCK
Root found a safety reason not to interact with the asset or action.
UNKNOWN
Root could not establish a trustworthy action verdict.
MCP integration
Root as an agent tool surface
Run the MCP server
Use stdio for local agent hosts or streamable HTTP for an MCP endpoint. The default buyer is challenge-only; production buyers inject the OKX/Onchain OS x402 flow.
ROOT_SERVICE_URL=https://api.useroot.xyz \ python -m root_agent.mcp_server ROOT_SERVICE_URL=https://api.useroot.xyz \ ROOT_MCP_TRANSPORT=streamable-http \ ROOT_MCP_PORT=8765 \ python -m root_agent.mcp_server
root_check
paid via buyer transport
root.check.v1
Run the low-cost claim-registry gate before a full recovery purchase.
root_recover
paid via buyer transport
root.service.v1 -> root.v1
Buy and validate one complete recovery-intelligence assessment.
root_validate_delivery
local read-only
validated delivery summary
Verify an existing paid delivery before an agent explains or hands it off.
root_explain
local read-only
root.explain.v1
Explain one selected intent or risk finding from the already validated plan.
root_watch_create
agent-local state
watch enrollment
Enroll one public EVM address after explicit opt-in consent.
root_watch_status
agent-local read
watch status
Read due state, baseline hash, and latest coverage-aware result.
root_watch_check
paid when approved
root.watch.v1
Buy one Recover assessment and diff it against the last complete baseline.
root_watch_delete
agent-local delete
deletion receipt
Remove the watch, compact baseline, and retained history after confirmation.
Credential rule
MCP tools never accept payment signatures, private keys, seed phrases, wallet credentials, or raw x402 authorizations. If a paid call needs authorization, the configured buyer transport owns it and returns only the final service response.
HTTP API
Seller endpoints
GET
/capabilities
Public machine-readable service and tool discovery.
GET
/teaser/{address}
Free preview route. It does not perform a wallet scan.
POST
/check
$0.001 x402 Root Check. Returns root.check.v1.
POST
/scan
$0.01 x402 Root Recover. Returns root.service.v1 with recovery_plan at $.recovery_plan.
POST
/explain
Evidence-bound explanation for one selected intent or risk finding.
GET
/schemas/root.check.v1
Root Check output contract.
GET
/schemas/root.v1
Canonical RecoveryPlan contract.
GET
/schemas/root.service.v1
Paid service delivery envelope.
GET
/schemas/root.explain.v1
Deterministic explanation response.
GET
/schemas/root.watch.v1
Agent-local Watch result contract.
POST /check
{ "address": "0x..." }
POST /scan
{ "address": "0x..." }
POST /explain
{
"schema_version": "root.explain.request.v1",
"recovery_plan": { "...": "complete root.v1 plan" },
"selector": {
"kind": "recovery_intent",
"item_id": "intent_id"
}
}Contracts
Schemas and plan shape
root.check.v1
Low-cost Check result, source health, evidence commitment, and conversion guidance.
root.service.v1
Paid delivery envelope with request id, report text, payment, cache state, and recovery plan.
root.v1
Canonical RecoveryPlan: status, summary, coverage, receipts, intents, risks, limitations, and safety.
root.explain.request.v1
Selector request for one recovery intent or risk finding inside a full plan.
root.explain.v1
Deterministic explanation and next state for the selected item.
root.watch.v1
Agent-local watch enrollment, diff, baseline, and coverage-aware check result.
{
"schema_version": "root.v1",
"assessment_id": "root_...",
"address": "0x...",
"status": "ACTIONABLE | PROTECTED | CLEAN | PARTIAL | INCONCLUSIVE",
"summary": {
"recover_now_usd": 0,
"recover_later_usd": 0,
"visible_portfolio_usd": 0,
"actionable_count": 0,
"blocked_count": 0
},
"coverage": {
"configured": 0,
"checked": 0,
"failed": 0,
"timed_out": 0,
"unsupported": 0,
"stale": 0,
"skipped": 0,
"complete": false
},
"source_receipts": [],
"recovery_intents": [],
"risk_findings": [],
"limitations": [],
"safety": {
"read_only": true,
"handles_keys": false,
"signs_transactions": false,
"broadcasts_transactions": false,
"requires_user_confirmation": true
}
}Coverage
Current exact-action catalog
16
Protocols
71
Configured checks
120
Contracts
68
Exact-action adapters
Coverage boundaries
- Configured checks are inventory, not proof that a source completed for a particular address.
- Coverage cannot rule out claims outside these sixteen protocols, adapters, markets, and contracts.
- Three GMX reads are context-only and can never enter recoverable value.
- Curve represents most configured checks; this is not broad protocol coverage.
- Only independently verified prices can enter recoverable-value math.
Safety model
What Root refuses to do
No custody
Root never handles recovery keys, private keys, seed phrases, wallet sessions, or execution signatures.
No execution
Root exposes no signing, broadcasting, swap, approval, transfer, or claim-execution tool.
Official paths only
User-facing action links must be official protocol paths. Third-party claim helpers do not ship.
No invented value
Only independently price-verified tokens enter value math. Unpriced or unverifiable assets are excluded from recoverable value.
Examples
How to interpret results
Claimable reward
ACTIONABLEA public address has an unclaimed protocol reward. Root links checked receipts, values the asset after gas, and emits an ALLOW intent with exact inputs and official path.
Planted token
PROTECTEDA wallet holds a suspicious token or fake claim bait. Root can return a risk finding with BLOCK or REVIEW and excludes it from portfolio value.
No Check signal
NO_SIGNALRoot Check finds no raw registry signal. The flow stops without upsell, and the result is not represented as a full clean-wallet assessment.
Incomplete source
PARTIALRoot returns useful checked evidence while keeping failed, unsupported, timed-out, stale, or skipped sources visible instead of hiding uncertainty.
Reference archive
The fixed 12 July 2026 X Layer purchase is retained as historical proof. It is separate from fresh user assessments.