# RadixScan Agent Layer — full reference

> Detailed, machine-oriented description of the RadixScan agent layer for Radix.
> Status: live on mainnet and stokenet. The Read+Build MCP server described below
> is deployed at mcp.ai.radixscan.io, with non-custodial, human-in-the-loop
> signing. Tool names and shapes are stable.

## What this is

A focused set of tools that let AI agents read the Radix ledger, build and
simulate transaction manifests, and hand a transaction to a human for
signing. It reuses the same battle-tested manifest engine that powers the
RadixScan developer console, so an agent builds exactly the manifests a human
tool would.

## Why Radix is structurally agent-friendly

- Transactions are expressed as readable, typed "manifests", so an agent can
  parse, verify and explain intent.
- Manifests can be statically analyzed (worktop simulation, type checks) before
  signing.
- The Gateway offers a free transaction preview: fee estimate, balance changes,
  success/failure — an agent never acts blind.
- Tokens are native ledger resources, not bespoke contracts — fewer edge cases.

## Interface

- Protocol: MCP (Model Context Protocol) over Streamable HTTP, with SSE as a
  legacy transport.
- Endpoints: https://mcp.ai.radixscan.io/mcp (Streamable HTTP) and
  https://mcp.ai.radixscan.io/sse (SSE)
- Auth: none for read & build (keyless). Signing is a non-custodial,
  human-in-the-loop handoff to the Radix Wallet — keys never reach the agent.

## Conventions (all tools)

- Every response includes a `network` field (mainnet | stokenet). Mainnet
  responses carry a `risk`/`warning` field.
- `response_format`: `concise` (default) | `detailed`. Granular opt-in flags
  where useful (e.g. `include_events` on radix_get_transaction).
- Responses are structured JSON of hard facts — not prose. The consuming agent
  writes any natural-language summary itself. The one exception is
  radix_explain_manifest, whose job is a plain-language explanation.
- Lists are paginated (cursor/limit) with a truncation hint.
- Errors are structured with a cause AND an actionable next step.

## Read tools

- radix_resolve_address — any address -> type (account/resource/component/
  validator/package/…) + core metadata. Components additionally return their
  blueprint origin (package + blueprint name) as the bridge to
  radix_get_blueprint_interface / radix_get_component_state; pools return
  their pool unit and pooled amounts; internal vaults resolve to their owner
  (the entity they belong to). The network is inferred from the address.
- radix_get_account — balances, fungibles, NFTs of an account. Zero-balance
  entries are hidden by default (hide_zero).
- radix_get_resource — token/NFT metadata, supply, divisibility, plus its
  authorities: who may mint/burn/freeze/recall it (with the gating badge) and
  neutral factual flags (supply_fixed, mintable, freezable, recallable,
  rules_locked) — objective ledger facts, not a safety verdict. Pool units
  additionally report the pool they redeem from and the per-unit redemption.
- radix_get_transaction — structured "data triptych": core metadata
  (status, timestamp, fee, manifest classification) + aggregated net
  account-level balance changes + the decompiled (readable) manifest.
  Events are opt-in via include_events; resolve_symbols adds a `resources`
  side-table ({symbol, name}) for the balance changes. Committed transactions
  are immutable, so results are cached permanently.
- radix_list_transactions — recent committed transactions, newest first:
  network-wide, or scoped to one entity via `address`. Filters mirror the
  RadixScan dashboard: transaction type (manifest class), withdrawn-from /
  deposited-to accounts, badges presented, referenced resources, affected
  entities — plus an optional ISO-8601 time window (`from`/`to`, e.g. "all
  transactions of this component in the last 24h"). Returns a compact summary
  per transaction; fetch details with radix_get_transaction. Paginated via an
  opaque next_cursor — pages are pinned to one ledger state, so they never
  shift between reads (`to` and `cursor` are mutually exclusive: the cursor
  already pins its window). With resolve_symbols, a `resources` side-table
  maps each resource in the balance changes to its {symbol, name}.
- radix_get_validator — registration, effective fee, total staked XRD,
  uptime, website and LSU/claim-NFT resources. response_format "detailed"
  adds description, icon and the owner (the account or component currently
  holding the validator owner badge — the entity in control of the validator).
- radix_get_validator_list — the active validator set for a network, with rank,
  fee percentage and uptime — for picking or comparing validators.
- radix_get_blueprint_interface — the callable interface ("ABI") of a package
  or component: every function and method of its blueprint(s) with a rendered
  signature and the access requirement per entry (`access`: public vs
  role-protected with the required role names — i.e. which calls need a badge
  proof), plus the blueprint's defined roles. By default concise (signature +
  access, no structured type trees — the bulk of the payload); request
  response_format:"detailed" for the full structured parameter/return type
  trees needed to build a typed call, optionally scoped with functions:[…] so
  the heavy trees are fetched only for the method(s) you will call. Components
  (accounts, validators, pools included) resolve to their blueprint
  automatically; optional `blueprint` filter for multi-blueprint packages.
  Interfaces are immutable per package, so results are cached permanently. Use
  it before radix_build_manifest to know which CALL_METHOD / CALL_FUNCTION
  calls a component supports — and which of them the caller can actually invoke.
- radix_get_component_state — the stored twin of the blueprint interface:
  the current on-ledger state of a component, SBOR-decoded with field names
  (e.g. the prices inside an oracle, a dApp component's configuration, an
  account's deposit rules). Works for component_, pool_, validator_,
  account_ and accesscontroller_ addresses; pools additionally return their
  pooled resource amounts and the pool unit. Also returns role_assignments —
  who holds each role (with the gating badge) — so, paired with the role names
  from radix_get_blueprint_interface, you can tell which calls are actually
  permitted (a role_protected method whose role resolves to AllowAll is open).
  States larger than 64 KB are reduced to their top-level field names with
  `truncated: true`. Short-lived cache (state is mutable); `live` forces a
  fresh read. Fields stored in KeyValueStores are surfaced as references under
  `key_value_stores` — read their entries with radix_get_key_value_store.
- radix_get_key_value_store — the entries of a Scrypto KeyValueStore (the
  storage behind a component's internal_keyvaluestore_ references, e.g. an
  oracle's actual prices). Without `keys`: one page of entries, paginated via
  next_cursor (pinned to one ledger state). With `keys`: targeted lookups —
  pass a Radix address for address-keyed stores or a plain string for
  string-keyed ones. Values come SBOR-decoded; oversized values are marked
  `value_truncated`. Uncached (KV stores are the most mutable ledger state).
- radix_get_nft — non-fungibles of a resource. Without `ids`: one page of the
  collection's local ids plus total_count, paginated via next_cursor (pinned
  to one ledger state). With `ids`: the SBOR-decoded data of those NFTs, and
  with include_holder the account/component that currently owns each. For a
  single account's holdings use radix_get_account. Uncached (NFT data and
  ownership are mutable).
- radix_get_resource_holders — the holders of a resource, sorted by holding
  descending, so the first page is the top holders. The reverse of
  radix_get_account. Works for fungibles (each holder's amount) and
  non-fungibles (each holder's NFT count); reports total_holders and a
  next_cursor to page deeper. Backed by an optional gateway extension — a
  gateway that has it disabled returns a structured error.
- radix_find_entities_by_badge — the on-ledger entities a badge controls: given
  a badge resource (optionally a specific NFT local id), every component,
  resource, pool or locker that names it as a role requirement, each with its
  kind and (where available) blueprint and name. The reverse of an entity's role
  assignments. Reports total_controlled and a next_cursor. Same optional gateway
  extension caveat as radix_get_resource_holders.

Note: an RNS/domain entry-point search (radix_search) is deferred until Radix
Name Service data is available on-ledger.

## Build tools (keyless)

- radix_build_transfer — goal-oriented: build a token-transfer manifest
  (lock_fee, withdraw, deposit) for fungibles and/or NFTs in one call.
- radix_build_manifest — takes a strict typed step array (no raw text) and
  returns a canonical, RET-validated manifest + diagnostics. The backend
  generates the syntax, so the agent never hand-writes manifest text.
- radix_validate_manifest — parse + static checks of a given (possibly
  external) manifest via the Radix Engine Toolkit. Accepts raw text, read-only.
- radix_preview_transaction — real Gateway preview (free, no signing): fee
  estimate, net balance changes, success/failure. Carries a `simulated_at`
  timestamp and epoch validity window.
- radix_explain_manifest — manifest -> plain-language, step-by-step reading;
  the one prose tool, the basis for a human signature confirmation.

## Manifest documentation tools

A self-describing manual for writing manifests, also exposed as radix://manifest/*
resources (same content).

- radix_manifest_workflow — orientation: networks, address structure, the
  build -> validate -> preview -> sign -> submit lifecycle.
- radix_manifest_instructions — list every manifest instruction with a summary.
- radix_manifest_instruction — one instruction in depth (syntax, args, examples).
- radix_manifest_templates — ready-made templates (transfer, stake, unstake,
  claim, mint, burn, swap) plus the placeholder convention.
- radix_manifest_template — one template body with {PLACEHOLDER} slots.

## Ecosystem discovery

- radix_list_ecosystem_services — directory of other agent-facing Radix services
  (e.g. DEX-aggregator MCP servers) for capabilities this server does not cover,
  such as resolving a token swap. Each entry lists the networks it supports;
  optionally filter by category and/or network. Informational only — a listing
  is not an endorsement. Also exposed as radix://ecosystem/* resources.
- radix_lookup_entity — curated name/symbol → canonical address for well-known
  Radix entities (tokens, dApp components): the inverse of radix_resolve_address,
  for when you have a name but not an address. Takes an explicit network (a name
  carries none) and returns all matching candidates. Informational and curated —
  not an endorsement or a safety verdict; confirm the address with
  radix_resolve_address before putting it in a manifest. Also exposed as
  radix://ecosystem/addresses/{network}.

## Resources

- radix://manifest/workflow, radix://manifest/instructions,
  radix://manifest/instruction/{name}, radix://manifest/templates,
  radix://manifest/template/{name}
- radix://ecosystem/services, radix://ecosystem/service/{slug}
- radix://ecosystem/addresses/{network} — same data as radix_lookup_entity
- radix://blueprint/{address} — same data as radix_get_blueprint_interface

## Signing (live, non-custodial, human-in-the-loop)

- radix_request_signature — returns a short URL; the sign page shows a
  plain-language summary plus a QR / wallet deep link, and the human reviews and
  signs in their Radix Wallet. Any account lock_fee is stripped automatically
  (the wallet adds its own network fee). Keys never reach the agent. Works on
  stokenet and mainnet (mainnet only when enabled on the deployment).
- radix_signature_status — poll the outcome by id: pending, committed (with the
  transaction intent hash), rejected or expired. On committed, the transaction is
  warmed into the cache so radix_get_transaction is immediate.

## Operational notes

- Requests are rate-limited per client with cost-based budgets: pure reads are
  cheap, Gateway-backed calls (previews, uncached lookups) cost more. A 429 is
  a structured JSON-RPC error — back off and retry later.
- Request bodies are capped at 256 KB.
- Committed transactions are cached server-side; repeat lookups are instant.

## Human-facing deep links

When handing a result to a human, link the RadixScan explorer instead of
pasting raw JSON:

- Transaction: https://dashboard.radixscan.io/transaction/{intent_hash}
- Account: https://dashboard.radixscan.io/account/{address}
- Resource: https://dashboard.radixscan.io/resource/{address}
- Validator: https://dashboard.radixscan.io/validator/{address}

The full URL-pattern list is in https://dashboard.radixscan.io/llms.txt.

## Companion (build-time knowledge)

This server is runtime infrastructure: it reads the live ledger and builds,
validates and previews transaction manifests over MCP. It is not a source of
build-time coding knowledge — it does not teach you how to write Scrypto or a
dApp. If your agent is also *writing* Radix software, pair it with a knowledge
skill that lives on disk:

- radix-skills (https://github.com/xstelea/radix-skills) — a community Agent
  Skill with reference guides for Scrypto, transaction manifests, Gateway flows
  and wallet / ROLA flows, grounded in the radixdlt-scrypto and radix-web3.js
  source. Install: `npx skills add xstelea/radix-skills --skill radix`

The two are complementary, not overlapping: live data + transaction building
over the wire here; local coding knowledge on disk there. radix-skills is
maintained independently and is not affiliated with or maintained by RadixScan.

## Source

- RadixScan: https://radixscan.io