UXUS Agent Services: wallet lookup, entity labels, caller ID

Official7 tools

by Dcroyalty · TypeScript

Free wallet lookup, ENS, labels, caller ID. Paid x402: search, scrape, XRP yield and lending grades

io.github.Dcroyalty/uxus MCP Server

The MCP server provides free wallet lookup capabilities, including ENS resolution, entity labeling, and caller ID. It also supports a paid workflow for x402 web search and scraping. The server is identified by the slug io-github-dcroyalty-uxus and includes the name io.github.Dcroyalty/uxus.

🛠️ Key Features

Free wallet lookup
ENS resolve
Entity labels
Caller ID
Paid x402 web search and scrape

🚀 Use Cases

Retrieve wallet information via lookup
Resolve ENS names
Obtain labels for entities
Map or identify caller IDs
Perform x402 web search and scraping when required

⚡ Developer Benefits

Consolidates wallet lookup, ENS resolution, labeling, and caller ID into one server
Adds an optional paid capability for x402 search and scraping

⚠️ Limitations

Paid x402 web search and scraping is not part of the free feature set

Captured live from the server via tools/list.

search_web

Live web search: ranked results plus Google's answer box, knowledge graph, people-also-ask and related searches when the Google-backed provider answers. This is a PAID x402 call: $0.01 USDC on Base at GET /api/search. This tool returns the payment resource to call; it does not run the search. Params: query (string, required); count (integer 1-20, default 10); country/language/page/device (optional).

Parameters6

query	string	required	Search query. Required.
count	integer	optional	Number of results, 1-20. Default 10.
country	string	optional	2-letter country code. Optional.
language	string	optional	2+ letter language code. Optional.
page	integer	optional	1-based result page. Optional.
device	string	optional	Forwarded to the upstream provider if set; not confirmed to change results on every provider. Optional.

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Search query. Required."
    },
    "count": {
      "type": "integer",
      "minimum": 1,
      "maximum": 20,
      "default": 10,
      "description": "Number of results, 1-20. Default 10."
    },
    "country": {
      "type": "string",
      "description": "2-letter country code. Optional."
    },
    "language": {
      "type": "string",
      "description": "2+ letter language code. Optional."
    },
    "page": {
      "type": "integer",
      "minimum": 1,
      "description": "1-based result page. Optional."
    },
    "device": {
      "type": "string",
      "description": "Forwarded to the upstream provider if set; not confirmed to change results on every provider. Optional."
    }
  },
  "required": [
    "query"
  ],
  "additionalProperties": false
}

scrape_url

Any web page as clean, LLM-ready markdown, text or html. This is a PAID x402 call: $0.01 USDC on Base at GET /api/scrape. This tool returns the payment resource to call; it does not fetch the page. Params: url (absolute http/https URL, required); format (markdown | text | html, default markdown); max_chars (integer, default 40000, max 120000).

Parameters3

url	string	required	Absolute http/https URL to fetch. Required.
format	string	optional	Output format. Default markdown.
max_chars	integer	optional	Truncation limit. Default 40000, max 120000.

Raw schema

{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "description": "Absolute http/https URL to fetch. Required."
    },
    "format": {
      "type": "string",
      "enum": [
        "markdown",
        "text",
        "html"
      ],
      "default": "markdown",
      "description": "Output format. Default markdown."
    },
    "max_chars": {
      "type": "integer",
      "default": 40000,
      "maximum": 120000,
      "description": "Truncation limit. Default 40000, max 120000."
    }
  },
  "required": [
    "url"
  ],
  "additionalProperties": false
}

lookup_wallet

Universal address lookup — any address, any chain, auto-detected. Params: address (EVM 0x address or XRPL classic r-address, required); chain (optional EVM history hint: base default, or ethereum). Detects EVM vs XRPL from the format. Returns one normalized envelope: { address, chain, chain_detected, exists, risk_score, risk_level, verdict, flags, entity, name }. Free. For a fast first-pass check on a counterparty wallet.

Parameters2

address	string	required	EVM 0x address or XRPL classic r-address. Required.
chain	string	optional	Optional EVM history hint. Default base.

Raw schema

{
  "type": "object",
  "properties": {
    "address": {
      "type": "string",
      "description": "EVM 0x address or XRPL classic r-address. Required."
    },
    "chain": {
      "type": "string",
      "enum": [
        "base",
        "ethereum"
      ],
      "description": "Optional EVM history hint. Default base."
    }
  },
  "required": [
    "address"
  ],
  "additionalProperties": false
}

resolve_name

Bidirectional name <-> address resolution for ENS (name.eth) and Basenames (name.base.eth). Param: q (an ENS/Basename name, an EVM 0x address, or an XRPL r-address, required). Auto-detects direction. Reverse records are forward-verified against the address to stop name spoofing. Returns { query, kind, namespace, chain, resolved, address, name, sources }. XRPL .xrp names are detected but resolved:false (no canonical registry). Free.

Parameters1

string

required

An ENS/Basename name, an EVM 0x address, or an XRPL classic r-address. Required.

Raw schema

{
  "type": "object",
  "properties": {
    "q": {
      "type": "string",
      "description": "An ENS/Basename name, an EVM 0x address, or an XRPL classic r-address. Required."
    }
  },
  "required": [
    "q"
  ],
  "additionalProperties": false
}

check_entity

Entity attribution — what IS this address, not who owns it. Params: address (0x EVM address, required); chain (base default, or ethereum). Returns { address, chain, is_known, label, category }. category is one of sanctioned, mixer, exchange, bridge, dex_router, scam, drainer, phishing, flagged, token_contract, protocol, unknown. "sanctioned" is set only when the address is on the OFAC SDN list (the same source /api/risk uses); a non-OFAC blocklist hit is "flagged". Sourced from OFAC, ScamSniffer, MEW, eth-labels and curated Base/Tornado sets. Never guesses. Free.

Parameters2

address	string	required	0x EVM address. Required.
chain	string	optional	Default base.

Raw schema

{
  "type": "object",
  "properties": {
    "address": {
      "type": "string",
      "description": "0x EVM address. Required."
    },
    "chain": {
      "type": "string",
      "enum": [
        "base",
        "ethereum"
      ],
      "description": "Default base."
    }
  },
  "required": [
    "address"
  ],
  "additionalProperties": false
}

caller_id

Should this wallet be answered? For wallet messaging (XMTP, Push), which has no spam filter. Params: address (0x EVM address, required); chain (base default, or ethereum). Composes entity attribution + risk score + on-chain history + forward-verified name into ANSWER | SCREEN | BLOCK with reasons[] and a confidence flag. BLOCK on sanctioned/drainer/phishing/scam/mixer or risk verdict BLOCK; SCREEN is the default for unknown addresses. Free.

Parameters2

address	string	required	0x EVM address. Required.
chain	string	optional	Default base.

Raw schema

{
  "type": "object",
  "properties": {
    "address": {
      "type": "string",
      "description": "0x EVM address. Required."
    },
    "chain": {
      "type": "string",
      "enum": [
        "base",
        "ethereum"
      ],
      "description": "Default base."
    }
  },
  "required": [
    "address"
  ],
  "additionalProperties": false
}

health

Service health check. No parameters. Returns { ok, service, time, upstream } — confirms the uxus.finance API is reachable. Free.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

README.md3 KBView on GitHub

UXUS — Agent Services

Pay-per-call primitives for AI agents, live at uxus.finance. Paid in USDC on Base via the x402 protocol — no accounts, no API keys, no signup. A funded wallet is the whole integration.

Services

Endpoint	Price	What you get
`POST /api/llm`	$0.01	LLM completion, 5-model fallback chain
`GET /api/scrape`	$0.01	URL → clean markdown/text/html
`POST /api/extract`	$0.01	messy text/URL → JSON in your schema
`POST /api/embed`	$0.01	text → 1024-dim vectors (jina-embeddings-v3)
`GET /api/search`	$0.01	live web search
`GET /api/risk/pro`	$0.02	one call, one verdict: PROCEED / CAUTION / BLOCK + summary + reasons
`GET /api/risk/live/pro`	$0.02	one-call verdict on a token's owner powers (can it still be paused, upgraded or rugged?) + reasons
`GET /api/risk` · `/api/risk/live`	free	risk score + verdict (no reasons/signals)
`GET /api/lookup`	free	universal address lookup, EVM + XRPL, chain auto-detected
`GET /api/entity`	free	entity attribution — what is this address
`GET /api/resolve`	free	ENS / Basenames, forward + reverse (forward-verified)
`GET /api/callerid`	free	should this wallet be answered? (for XMTP/Push)
`/api/shield/*`	free	per-user private wallet blocklist (signature-auth)
`GET /api/catalog` · `/openapi.json` · `/llms.txt` · `/.well-known/x402.json`	free	discovery
`POST /api/mcp`	free	MCP server (Streamable HTTP) over the free tools

Every risk/verdict response carries a disclaimer: this is developer-grade screening from public data (OFAC SDN list, community scam registries, on-chain reads), not legal or compliance advice.

Data

Sanctions come from one place: the OFAC SDN list in bad_addresses (source='ofac'), refreshed daily by /api/cron/refresh-lists (guarded — a 0-address upstream response aborts rather than wiping the table). lib/entity.ts is the only place that joins it. A non-OFAC blocklist hit is category flagged, not sanctioned, and is allowlistable.
Scoring fails open: if a data source needed for a verdict is unavailable and there's no list hit, the response is degraded:true / verdict CAUTION, never PROCEED.

Development

bash

npm install
npm run dev        # http://localhost:3000
npm run build

Env (Vercel project settings):

var	required	purpose
`DATABASE_URL`	yes	Neon Postgres
`CRON_SECRET`	yes	gates `/api/cron/*`; Vercel Cron sends it as `Authorization: Bearer`
`OPENROUTER_API_KEY`	for `/api/llm`, `/api/extract`
`JINA_API_KEY`	for `/api/embed`
`SERPER_API_KEY` / `BRAVE_API_KEY`	optional	`/api/search` (falls back to DuckDuckGo)
`ETHERSCAN_API_KEY`	optional	wallet history (falls back to Blockscout)
`CDP_API_KEY_ID` / `CDP_API_KEY_SECRET`	for x402 settlement

Scripts: scripts/schema*.mjs (create tables), scripts/ingest*.mjs (manual list load — the scheduled path is lib/refresh-lists.ts + scripts/ingest-entity.mjs), scripts/shield-verify.mjs (live E2E), scripts/fix-sanctions.mjs (one-shot sanctions remediation, already run).

Install

Tools (7)

search_webscrape_urllookup_walletresolve_namecheck_entitycaller_idhealth

Remote endpoint

Streamable HTTP

Hosted server - connect over the network, no local install.

url

https://uxus.finance/api/mcp

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "uxus": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://uxus.finance/api/mcp"
      ]
    }
  }
}

Desktop config is stdio-only; this bridges via mcp-remote. Native remote: Settings > Connectors.

io.github.Dcroyalty/uxus MCP Server

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

search_web

scrape_url

lookup_wallet

resolve_name

check_entity

caller_id

health

UXUS — Agent Services

Services

Data

Development

Install

Remote endpoint

Related servers