@selat-ai/selat-discovery
v0.28.2
Published
SELAT agent payment skill for discovering, ranking, and paying x402 / MPP services with Circle Agent Wallets.
Readme
SELAT Agent Payments
SELAT-branded agent skill for discovering, ranking, and paying x402 services without API keys or local private keys. Wallet creation, signing, spending limits, and payment execution are delegated to Circle Agent Wallets via @circle-fin/cli. Paid calls go through the selat-pay CLI (@selat-ai/selat-pay on npm). Every paid call goes through the SELAT Router: same-rail Gateway passthrough is at par (0%); cross-protocol translation keeps ~5% markup.
Demo
One pipeline, agent picks an intent in plain English, paid API call goes out, response comes back:
$ selat run "search the web for recent articles"Progress messages, while it's running (printed on the side so they don't mix into the response):
[selat-pay] probing upstream directly to detect scheme
[selat-pay] mode=routed (upstream not Gateway-batched on eip155:8453; using router https://router.selat.ai)
[selat-pay] quoteId=911f6e4b-8919-4536-bd48-fe5cbeded3ac
[selat-pay] price=$0.031500 on eip155:8453
[selat-pay] payTo=0x1E5Be7e87A876C04AF0ffd725adccf02e998c5C2
[selat-pay] signed; submitting paid request
[selat-pay] status=200Final answer: the upstream's response body (parsed JSON when applicable, raw text otherwise). It prints on its own so you can pipe it straight into jq (a command-line JSON processor — brew install jq or your package manager) or a file without the progress messages getting in the way.
No API keys, no local private keys, no scheme branching in the agent. selat run invoked the skill ranker, validated the selected selat-pay execution hint, selat-pay auto-detected the upstream as tempo-native MPP and routed via the SELAT Router, the Circle Agent Wallet signed the inbound Gateway-batched payment via MPC, the router translated to MPP for the outbound leg, response came back.
Architecture
┌─────────────────────┐ ┌────────────────────┐
│ agent / shell │ │ Circle Agent │
│ (Claude Code, │ │ Wallet (MPC) │
│ Codex, Cursor, │ │ user-controlled │
│ any runtime) │ │ 2-of-2 MPC keys │
└──────────┬──────────┘ └──────────▲─────────┘
│ │
discover + rank sign typed-data
│ │ (via Circle CLI)
▼ │
┌─────────────────────┐ ┌──────────┴─────────┐
│ scripts/rank.mjs │ ─emits→ │ selat-pay CLI │
│ scripts/discover_ │ │ (@selat-ai/ │
│ federated_catalog │ │ selat-pay) │
└─────────────────────┘ └──────────┬─────────┘
▲ │
│ ▼
federated catalog ┌─────────────────────┐
(Circle + MPP + │ SELAT Router │
Apify + pay.sh) │ (Gateway-batched │
│ inbound → │
│ erc-3009/tempo │
│ outbound) │
└──────────┬──────────┘
│
paid upstreamEvery paid call goes through the SELAT Router. Gateway-capable upstreams are same-rail passthrough at par (0%); erc-3009 / tempo-native upstreams use cross-protocol translation (~5% markup). The agent only ever signs one shape (Gateway-batched inbound).
What It Does
- Federated discovery across Circle's x402 catalog, MPP / mpp.dev, Apify, pay.sh (
@solana/pay's Solana-settled registry), and SELAT's first-party catalog. - Intent ranking with semantic, price, and source-count signals (default weights
0.65 / 0.25 / 0.10). Bazaar-only services without live-probe evidence are demoted ×0.6, graded back toward ×1 by recent facilitator usage; demo/test/staging Bazaar listings are dropped at ingestion. - Routable-now filtering (
--payable-now) — endpoints reachable viaselat-paytoday. - Single payment path through
selat run→selat-pay; every paid call uses the router. Legacyx402_client.mjsis not for new flows. - Wallet/Gateway setup wrapping Circle CLI: status, balance, budget, deposit.
Numbers
| | |
|---|---|
| Services indexed | Federated x402 / MPP — Circle, x402 Bazaar (Coinbase CDP), MPP, Apify, pay.sh, Locus, Heurist Mesh, Cambrian, SELAT first-party |
| Endpoints | Circle · MPP · Apify · pay.sh (Solana) · Locus (Base) · Heurist Mesh (Base + Solana) · Cambrian · SELAT first-party (OpenAPI) |
| Payment networks (catalog-wide) | 24 EVM (eip155) networks in aggregate, plus Tempo (EVM-adjacent — TIP-20 precompiles, MPP rail) and Solana (non-EVM — pay.sh's registry settles here, and merchants' live 402s surface it alongside EVM rails). This is the union across the whole catalog, not per-endpoint — a given endpoint typically accepts one or two networks. |
| Agent wallet custody | 2-of-2 MPC via Circle; skill never sees mnemonics or private keys |
| Routable via selat-pay (--payable-now) | checked live per query — probe is free |
| Typical call cost | $0.001 – $0.05 USDC; SELAT's 5% fee on cross-protocol paths, 0% same-rail Gateway passthrough |
| Tests | npm test · 20 trigger evals · 11 output evals |
The network list above is catalog-wide discovery and routing coverage — the union across all endpoints, not per-endpoint support, and not a claim that every chain is a Circle CLI deposit target. Inbound signing is always Gateway-batched on a Circle-supported chain; the router settles the outbound rail (passthrough at par, or cross-protocol ~5%). Gateway funding should consolidate on Arc: direct deposits lead with Arc (USDC is Arc's gas token, and Circle sponsored the deposit gas for agent wallets in testing), and Eco gasless deposits source from Base, Arbitrum or Optimism and settle into Gateway on Arc too (Circle CLI ≥1.2.1; ~$0.03 flat Eco fee). Other Circle chains remain valid direct sources when the USDC is already there.
Quick Start
Preferred path when selat-cli is installed:
selat doctor
selat initFallback direct setup:
bash scripts/install-circle-cli.sh
circle wallet login <email> --type agent
node scripts/setup.mjs create
node scripts/setup.mjs statusFor coding agents: run these in the agent shell, ask the user for their Circle email before login, then pause for the email OTP. Before funding meaningful amounts, set a spending policy — see references/setup.md § "Spending policy".
Install selat-cli globally — it bundles selat-pay as a dependency, and selat run resolves the bundled copy directly, so no second install is needed:
npm install -g @selat-ai/selat-cli@selat-ai/selat-cli is public on npm. Optionally also install selat-pay globally if you want to invoke it from your shell (outside selat run):
npm install -g @selat-ai/selat-pay # optional, for shell useThen set SELAT_ROUTER_URL and SELAT_AGENT_WALLET_ADDRESS in ~/.config/selat-pay/.env. selat init checks for this setup and prints guidance without installing dependencies for you.
Paid selat run / selat skill run require selat budget start --amount <usd> (session.json; env cannot invent a budget), hard-cap --max-amount at $1.10, and honor selat freeze as the kill switch.
Canonical Agent Flow
selat budget start --amount 1
selat run "<intent>"Discovers, ranks, picks the top match, validates that the selected execution hint
is a selat-pay command, and runs it without a shell. Every paid call goes
through the router.
For advanced inspection or custom ranking filters, use the direct ranker:
npm run runtime -- "<intent>" --picknpm run runtime is a thin shortcut for node scripts/rank.mjs, so all ranker
flags still work after --.
Common Commands
# Wallet status + balance
selat doctor
node scripts/setup.mjs status
node scripts/setup.mjs gateway-balance
# Funding
selat fund
selat fund --method eco --chain base # gasless (Base, Arbitrum or Optimism source); settles into Gateway on Arc
# Session spend (required before paid selat run)
selat budget start --amount 1
selat freeze # kill switch for fund + pay
# Discovery
node scripts/discover_federated_catalog.mjs --payable-now
npm run runtime -- "<intent>" --pick
# Catalog source: ranking/search pull catalog.selat.ai's hourly merged+enriched
# envelope (~1 MB, schemas included). SELAT_CATALOG_SOURCE=local forces the local
# 8-registry build (offline / egress-denied hosts); discover_federated_catalog.mjs
# itself defaults to local because it is the builder entrypoint (--catalog-source hosted to pull).
# Prefer selat run over raw selat-pay
selat run "<intent>"Why This Exists
Agent runtimes need to call paid APIs (data, inference, search, on-chain RPC), but the existing flows assume per-user API keys, per-service signup, and bespoke credential storage. That doesn't compose: an autonomous agent can't sign up for accounts, manage 50 keys, or handle leaked-key fallout.
The x402, MPP / Tempo, and Circle Gateway protocols solve the payment side — agents pay per-call in USDC instead of holding API keys. But three rails exist, each with its own signing, and each agent runtime would otherwise re-implement all three. This skill packages discovery + ranking + single-path payment so an agent says "find me a thing that does X" and gets a runnable command. Circle Agent Wallets keep the keys at Circle (MPC custody, hard-bounded spending policy). The SELAT Router bridges erc-3009 and MPP outbound so the agent only ever signs one shape.
Documentation
| Audience / question | Read |
|---|---|
| Agent SOP, payment policy, workflow steps, guardrails | SKILL.md |
| Wallet creation, funding, Gateway deposits, spending policy, env vars, selat-pay install | references/setup.md |
| Discovery filters, catalog shape, ranking signals, payability explanations | references/catalog-and-ranking.md |
| Per-provider call examples (router passthrough + cross-protocol) | references/request-examples.md |
| JS helper imports, preflight policy, shell-out to selat-pay in programmatic use | references/programmatic-usage.md |
| Error recovery (auth, install, balance, cache, 402 inspection, payment refusal) | references/troubleshooting.md |
| Authoring conventions for skills like this one | references/agent-skill-authoring-sop.md |
| Historical implementation notes | references/changelog.md |
Project Layout
SKILL.md— agent SOP loaded on every invocation.scripts/— discovery, ranking, wallet, and paid-call CLIs. Per-file index inSKILL.md§ Files.references/— on-demand docs; see the table above.evals/— trigger and output-quality eval definitions.test/— Node test coverage.
Development
npm ci
npm run syntax # node --check on all *.mjs
npm test # Node test runner
npm run eval:check # trigger-eval format checkCI runs npm run syntax and npm test on pull requests and pushes to main.
Validation
- Unit + integration tests:
npm test. - Trigger evals: 20 cases in
evals/trigger-evals.json; enforced bynpm run eval:check. - Output evals: 11 scenario evals in
evals/evals.json, baseline inevals/output-quality-results.md.
Third-Party Rights
Apache-2.0 applies only to this repository's code and documentation. It does not grant rights to third-party services, APIs, trademarks, logos, data, or platforms referenced by this project, including Circle, MPP, Apify, pay.sh / @solana/pay, Heurist Mesh, Cambrian, Locus / paywithlocus.com, or x402 ecosystem services. Use of those services is subject to their own terms.
