# UXUS — Agent Services

> Pay-per-call tools for AI agents, paid with USDC on Base via x402 (no account, no API key). Headline: one call, one verdict: PROCEED / CAUTION / BLOCK with the reasons attached, for any EVM wallet or token ($0.02). Also search, scrape, extract, embeddings and LLM at $0.01.

## Why
An agent with a USDC wallet can use every service here immediately. No provider accounts to create, no keys to rotate, no subscriptions. Payment is authentication.

## Storefront
GET https://uxus.finance/api/catalog  (FREE)
Returns every service, price, and parameter in one call.

## Services

### LLM inference — $0.01
POST /api/llm
Body: { "prompt": "..." }  or  { "messages": [...] }
Optional: model, max_tokens (max 2000)
Returns: { model, content, usage, latency_ms }

### Scrape — $0.01
GET /api/scrape?url=https://example.com&format=markdown
format: markdown | text | html. Optional max_chars.
Returns: { url, title, description, content, chars }

### Extract — $0.01
POST /api/extract
Body: { "schema": { "title": "string", "price": "number" }, "url": "..." }  (or "text")
Returns: { data, model }

### Embeddings — $0.01
POST /api/embed
Body: { "input": "text" }  or  { "input": ["a","b"] }  (max 64)
Returns: { embeddings, dimensions, count }

### Search — $0.01
GET /api/search?q=your+query&count=10&country=us&language=en&page=1
Optional: country (2-letter, Google gl), language (2+ letter, Google hl), page
(1-based), device (forwarded upstream if set, not confirmed to change results
on every provider).
Returns: { query, results: [{title, url, description, score}], ads,
people_also_ask, related_searches, knowledge_graph, answer_box, shopping,
ai_overview, provider }
score: 1.0 for the top result, descending toward 0.1 — rank or threshold on it.
The structured blocks (ads/People Also Ask/related searches/knowledge graph/
answer box/shopping/AI Overview) are populated when the Google-backed provider
(Serper) answers a request; they come back empty/null on fallback to Brave or
DuckDuckGo — check `provider` to know which one served you.

### Risk verdict — $0.02 (one call, one verdict)
GET /api/risk/pro?address=0x...&chain=base&type=wallet
Checks OFAC sanctions, 3,000+ scam/phishing addresses, honeypot and rug signals.
Returns, in this order: { verdict: PROCEED|CAUTION|BLOCK, summary: one sentence why, reasons: [{code, severity, detail, source}] strongest first, risk_score, risk_level, flags, degraded, signals, sources }
PROCEED = no sanctions, scam-list or risk signal. CAUTION = a warning sign (such as owner or issuer controls on a token), or a source could not be checked. BLOCK = sanctioned, scam-listed or a hard red flag; do not send funds. Admin powers alone are never BLOCK: USDC, EURC, RLUSD and other regulated stablecoins return CAUTION with the reason "issuer can freeze or upgrade; normal for regulated stablecoins".
degraded:true = a verdict input was unavailable (wallet-history explorer failed,
or the token-security provider returned nothing) AND there was no list hit. The
verdict is then CAUTION ("not fully assessed"), never PROCEED, with a
HISTORY_UNAVAILABLE / TOKEN_CHECK_UNAVAILABLE flag. Retry before acting.
OFAC + scam lists are refreshed daily by a cron (guarded — a 0-address upstream
response aborts rather than wiping the table).

### Risk (free demo) — $0.00
GET /api/risk?address=0x...&chain=base

### Universal lookup (free) — $0.00
GET /api/lookup?address=<any address, any chain>
No chain parameter — EVM and XRPL are auto-detected from the address format.
Optional ?chain=ethereum hint (EVM only; default base).
Returns: { address, chain, chain_detected, exists, risk_score, risk_level, verdict, flags, entity, upgrade }
Same field names for every chain. exists / risk_score / risk_level / verdict are
null when the chain RPC could not be reached (XRPL) — with degraded:true and a
note. null means "not checked", never "clean".

### Entity attribution (free) — $0.00
GET /api/entity?address=0x...&chain=base|ethereum   (default base)
What IS this address — not who owns it.
Returns: { address, chain, is_known, label, category }
category: sanctioned | mixer | exchange | bridge | dex_router | scam | drainer | phishing | flagged | token_contract | protocol | unknown
"sanctioned" is asserted ONLY when the address is on the OFAC SDN list (the same
list /api/risk uses) — one source of truth, and the only category Shield hard-blocks.
"flagged" = named by a non-OFAC blocklist; informational, allowlistable.
Sources: OFAC (SDN list), ScamSniffer, MEW darklist, eth-labels, curated Base/Tornado sets. Never guesses.

### Name resolution (free) — $0.00
GET /api/resolve?q=<name or address>
Bidirectional. ENS (name.eth) and Basenames (name.base.eth), forward and reverse,
via public RPC + the resolver contracts directly. Reverse records are forward-verified
against the input address (anti-spoofing). Auto-detects direction from the query.
Returns: { query, kind, namespace, chain, resolved, address, name, sources, lookup }
XRPL .xrp names are detected but return resolved:false — no canonical registry.

### Wallet caller ID (free) — $0.00
GET /api/callerid?address=0x...&chain=base|ethereum   (default base)
Should this wallet be answered? Wallet messaging (XMTP, Push) has no spam filter.
Composes entity attribution + risk score + on-chain history + verified name into one answer.
Returns: { address, chain, name, entity, exists, risk_score, risk_level, verdict, risk_degraded, recommendation, confidence, reasons, checked_at }
recommendation: ANSWER | SCREEN | BLOCK
confidence: high (entity + a fully-assessed risk both resolved) | low (an input was
missing, or the risk read was degraded — treat as "unchecked", not "clean")
reasons[] names exactly what drove the call. SCREEN is the default for unknown addresses, not a failure.
BLOCK: sanctioned | drainer | phishing | scam | mixer, or risk verdict BLOCK.
ANSWER: known exchange/dex_router/protocol, or a forward-verified ENS/Basename — each with risk verdict PROCEED.

### Wallet blocklist — Shield (free) — $0.00
Per-user PRIVATE blocklist. Your block never affects anyone else's results — no shared
reputation, no aggregate scoring. First stateful product in the store.

Ownership is proved by signature, not an API key:
1. GET /api/shield/nonce?owner=0x...            -> { nonce, expires_at }  (10 min, single-use)
2. Sign the returned message with the owner key (EIP-191 / personal_sign).
   v1 verifies EOA (ECDSA) signatures only — ERC-1271 / Safe wallets are not supported yet.
3. POST /api/shield/session { owner, signature } -> { token }   (bearer, 60 min, for reads)

Writes (fresh nonce + signature each, the message binds the action and target):
POST /api/shield/block   { owner, signature, address, chain?, reason? }
POST /api/shield/unblock { owner, signature, address }
POST /api/shield/allow   { owner, signature, address, reason? }   ("I vouch for this address")
POST /api/shield/unallow { owner, signature, address }

Reads (Authorization: Bearer <token>):
GET /api/shield/list                              -> { blocks[], allows[] }
GET /api/shield/check?address=0x...&chain=base    -> { blocked, source, recommendation, reasons[], entity, name }
GET /api/shield/stats                             -> 7d / 30d / 90d counts by action and entity category

/check precedence: OFAC-sanctioned entity (hard stop, cannot be allowlisted — decided
solely by the OFAC SDN list) > your allowlist > your manual block > auto-BLOCK from
caller ID > the caller-ID recommendation (ANSWER|SCREEN|BLOCK). A "flagged" (non-OFAC
blocklist) address is NOT a hard stop — you can allowlist it.
Every /check is logged so /stats is real. shield_events are pruned by a daily job
(and opportunistically on /nonce) — nothing older than 90 days is retained. 90-day
retention, stated not buried.

## Payment
x402 protocol. Network: Base (eip155:8453). Asset: USDC.
Discovery: https://uxus.finance/.well-known/x402.json
MCP endpoint: https://uxus.finance/api/mcp