@selat-ai/selat-agent-payments

v0.7.0

Published

3 days ago

SELAT agent payment skill for discovering, ranking, and paying x402 / MPP services with Circle Agent Wallets.

0High
0Medium
0Low

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), which routes via the SELAT Router for non-Gateway-batched upstreams and pays direct for Gateway-batched ones.

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 papers on agentic payments"

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=200

Final 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 + Agentic            │  SELAT Router       │
        Market + MPP)               │  (Gateway-batched   │
                                    │  inbound →          │
                                    │  erc-3009/tempo     │
                                    │  outbound)          │
                                    └──────────┬──────────┘
                                               │
                                          paid upstream

Gateway-batched upstreams skip the router (selat-pay pays them direct). erc-3009 / tempo-native upstreams go through the router, which translates rails so the agent only ever signs one shape.

What It Does

Federated discovery across Circle's x402 catalog, Agentic Market, and MPP / mpp.dev.
Intent ranking with semantic, price, and source-count signals (default weights 0.65 / 0.25 / 0.10).
Routable-now filtering (--payable-now) — endpoints reachable via selat-pay today.
Single payment path through selat-pay; auto-detects scheme per call. Legacy x402_client.mjs kept for direct Gateway-batched calls.
Wallet/Gateway setup wrapping Circle CLI: status, balance, budget, deposit.

Numbers

| | | |---|---| | Services indexed | 123 across 3 catalogs (Circle 18, Agentic 50, MPP 82) | | Endpoints | 2,086 (1,632 paid) | | Chains supported | 23 EVM mainnets + testnets (Arc, Base, Ethereum, Arbitrum, Optimism, Polygon, …) | | Agent wallet custody | 2-of-2 MPC via Circle; skill never sees mnemonics or private keys | | Routable via selat-pay (--payable-now) | 121/123 services | | Typical call cost | $0.001 – $0.05 USDC; ~5% router markup on non-direct paths | | Tests | 71/71 pass · 20 trigger evals · 11 output evals |

"23 EVM mainnets + testnets" is discovery and routing coverage, not a claim that every chain is a direct Circle CLI deposit target. Direct Gateway-batched calls require the upstream to offer the selected Circle-supported chain. For erc-3009 / MPP / tempo-native upstreams, selat-pay uses a Circle-supported inbound Gateway payment and the SELAT Router settles the upstream rail. Gateway funding should consolidate on Polygon; Eco gasless deposits can source from Base, Optimism, or Arbitrum and settle into Gateway on Polygon.

Quick Start

Preferred path when selat-cli is installed:

selat doctor
selat init

Fallback direct setup:

bash scripts/install-circle-cli.sh
circle wallet login <email> --type agent
node scripts/setup.mjs create
node scripts/setup.mjs status

For 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

Optionally also install selat-pay globally if you want to invoke it directly from your shell (outside selat run):

npm install -g @selat-ai/selat-pay   # optional, for direct shell use

Pre-launch this works for SELAT-AI npm org members — both are private scoped packages.

Then 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.

Canonical Agent Flow

selat run "<intent>"

Discovers, ranks, picks the top match, validates that the selected execution hint is a selat-pay command, and runs it directly without a shell.

For advanced inspection or custom ranking filters, use the direct ranker:

npm run runtime -- "<intent>" --pick

npm 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 source: base, optimism, or arbitrum
selat fund --method eco --chain optimism   # settles into Gateway on Polygon

# Discovery
node scripts/discover_federated_catalog.mjs --payable-now
npm run runtime -- "<intent>" --pick

# Direct paid call (Gateway-batched upstreams only; selat-pay handles this automatically)
node scripts/x402_client.mjs GET "<url>" --chain base --max-amount 0.05

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 (Gateway-batched direct + MPP/erc-3009 routed) | 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 in SKILL.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 check

CI runs npm run syntax and npm test on pull requests and pushes to main.

Validation

Unit + integration tests: 71/71 pass (npm test).
Trigger evals: 20 cases in evals/trigger-evals.json; enforced by npm run eval:check.
Output evals: 11 scenario evals in evals/evals.json, baseline in evals/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, Agentic Market, MPP, or x402 ecosystem services. Use of those services is subject to their own terms.