x402-agent-gateway 0.1.0

package/README.md

@@ -0,0 +1,119 @@
+# x402 Agent Gateway
+
+Pay-per-call APIs for autonomous agents, settled in USDC over [x402](https://x402.org).
+No account, no API key, no subscription. An agent discovers the endpoint, gets a `402`
+with the exact amount, pays, and gets the result.
+
+Live API: `https://api.x-402.online`
+
+## Start here: the free quote
+
+Nothing below costs anything until you choose to pay. Two endpoints are free and require
+no wallet at all.
+
+```bash
+npx x402-agent-gateway capabilities                    # what can be solved
+npx x402-agent-gateway preview "summarise ethereum etf news"   # the plan and the price
+```
+
+The quote tells you which capability was chosen, why, what it costs, **and when a direct
+route would be cheaper than the gateway**. The gateway has a single price, so it overcharges
+for cheap capabilities. You should know that before you pay, not after.
+
+## The flagship product
+
+**`POST /v1/us/brief` — $0.040004**
+
+A decision-grade briefing on a US public company, from SEC EDGAR, in one call:
+
+- a summary where **every claim cites its origin**: `[identity]`, `[financials]`, `[filings]`
+- key points and the open questions the data does not settle
+- **the underlying facts alongside**: identity, three years of annual figures, recent filings
+
+Buying the three underlying routes separately costs **$0.090024**. This replaces them with a
+synthesised answer for **56% less**, and you can still verify every claim because the raw
+facts come back with it.
+
+```js
+import { Gateway } from "x402-agent-gateway";
+
+const g = new Gateway({ fetch: myX402Fetch });   // any x402-capable fetch
+const r = await g.usBrief("AAPL");
+
+r.brief.summary        // "Apple Inc. (CIK 0000320193) is a Nasdaq-listed … [identity]"
+r.brief.key_points     // each one cites its source
+r.financials.revenue   // the raw figures, to check the summary against
+r.filings              // the recent SEC filings
+```
+
+```python
+from x402_gateway import Gateway
+g = Gateway()
+r = g.us_brief("AAPL")
+print(r["brief"]["summary"], r["financials"]["revenue"])
+```
+
+Without a payment-capable fetch, `usBrief` raises `PaymentRequired` **carrying the x402
+challenge** — amount, network and address. Pay it with whatever tooling you already use.
+This SDK does not impose its own.
+
+## Capabilities behind one endpoint
+
+`POST /v1/solve` — $0.012002. Send a task in plain words, or name a capability and its
+input. The gateway resolves which capability is needed, ranks providers by expected net
+margin and observed success rate, executes, falls back to the next provider on failure, and
+returns the result with the routing it used.
+
+| capability | what it does |
+|---|---|
+| `company_brief_us` | the SEC briefing above |
+| `web_search` | ranked web results |
+| `news_search` | fresh headlines |
+| `news_brief` | headlines plus a sourced summary |
+| `llm_generate` | text generation, two providers, one engine |
+| `web_extract` | a page as clean markdown, French residential IP, real browser |
+| `web_render` | full HTML after JavaScript execution |
+
+`GET /v1/capabilities` returns the input and output schemas, and lists only what is actually
+servable right now.
+
+## Discovery, for machines
+
+| surface | what it carries |
+|---|---|
+| `/openapi.json` | the full OpenAPI description |
+| `/llms.txt` | a plain-text summary for language models |
+| `/.well-known/x402` | the x402 payment metadata |
+| `/.well-known/agent-card.json` | the A2A Agent Card, protocol 0.3.0 |
+| `/mcp` | an MCP server, 63 tools, `tools/list` over JSON-RPC |
+| `/v1/capabilities` | the gateway's capability registry |
+
+## Payment
+
+x402, `exact` scheme, USDC on Base (`eip155:8453`) and Solana. Each route has a **unique**
+amount, so every settlement is attributable on-chain by the amount alone. `/v1/us/brief`
+is `40004` micro-USDC, `/v1/solve` is `12002`.
+
+## Install
+
+```bash
+npm install x402-agent-gateway      # Node 20+
+pip install x402-agent-gateway      # Python 3.10+, no dependencies
+```
+
+Both are in this repository under `node/` and `python/`. If the published packages are not
+up yet, point the client at the API directly — the SDK is a thin, optional convenience:
+
+```bash
+curl -s -X POST https://api.x-402.online/v1/us/brief \
+  -H 'content-type: application/json' -d '{"ticker":"AAPL"}'
+# → 402 with the exact amount to pay
+```
+
+## What this is not
+
+Not investment advice. `/v1/us/brief` reports what SEC EDGAR contains and cites it; it never
+recommends buying or selling anything, and it says in `open_questions` what the filings do
+not answer rather than filling the gap with a guess.
+
+MIT licensed.

package/bin/cli.js

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+// CLI du gateway. Trois verbes, et le devis est celui qu'on tape en premier parce qu'il
+// est gratuit : on voit le plan et le prix avant de sortir un portefeuille.
+
+import { Gateway, PaymentRequired, GatewayError } from "../src/index.js";
+
+const args = process.argv.slice(2);
+const verbe = args[0];
+const reste = args.slice(1);
+
+function opt(nom, defaut) {
+  const i = reste.indexOf(`--${nom}`);
+  if (i === -1) return defaut;
+  const v = reste[i + 1];
+  reste.splice(i, 2);
+  return v;
+}
+
+const base = opt("url", process.env.GATEWAY_URL);
+const cle = opt("key", process.env.GATEWAY_API_KEY);
+const json = reste.includes("--json") && reste.splice(reste.indexOf("--json"), 1);
+const g = new Gateway({ baseUrl: base, apiKey: cle });
+
+const AIDE = `agent-gateway — une intégration pour toutes les capacités
+
+  agent-gateway capabilities              ce que le gateway sait faire (gratuit)
+  agent-gateway preview "<tâche>"         le plan et le prix, sans exécuter (gratuit)
+  agent-gateway solve   "<tâche>"         exécute et livre (x402)
+
+Options
+  --capability <nom>   impose la capacité au lieu de la deviner
+  --input '<json>'     l'entrée, quand on impose la capacité
+  --url <base>         défaut https://api.x-402.online  (ou GATEWAY_URL)
+  --key <clé>          clé interne, pour un accès sans x402  (ou GATEWAY_API_KEY)
+  --json               sortie brute, pour un script`;
+
+function demande() {
+  const cap = opt("capability", null);
+  if (cap) {
+    const brut = opt("input", "{}");
+    let input;
+    try { input = JSON.parse(brut); }
+    catch { sortir(`--input n'est pas du JSON valide : ${brut}`); }
+    return { capability: cap, input };
+  }
+  const tache = reste.filter((a) => !a.startsWith("--")).join(" ").trim();
+  if (!tache) sortir("il faut une tâche, ou --capability avec --input");
+  return { task: tache };
+}
+
+function sortir(msg, code = 1) {
+  console.error(`erreur : ${msg}`);
+  process.exit(code);
+}
+
+try {
+  if (!verbe || verbe === "help" || verbe === "--help" || verbe === "-h") {
+    console.log(AIDE);
+    process.exit(0);
+  }
+
+  if (verbe === "capabilities") {
+    const r = await g.capabilities();
+    if (json) { console.log(JSON.stringify(r, null, 2)); process.exit(0); }
+    console.log(`prix par solve : ${r.price_per_solve_usd} $ · paiement ${r.payment.protocol} ${r.payment.asset}\n`);
+    for (const c of r.capabilities) {
+      console.log(`  ${c.capability.padEnd(20)} ${String(c.providers).padStart(2)} provider(s) · ~${c.latency_ms_estimee} ms`);
+      console.log(`  ${" ".repeat(20)} ${c.description}`);
+    }
+    process.exit(0);
+  }
+
+  if (verbe === "preview") {
+    const r = await g.preview(demande());
+    if (json) { console.log(JSON.stringify(r, null, 2)); process.exit(0); }
+    const q = r.quote;
+    console.log(`capacité   ${q.capability}`);
+    console.log(`pourquoi   ${q.why_this_capability}`);
+    console.log(`entrée     ${JSON.stringify(q.normalized_input)}`);
+    console.log(`prix       ${q.price_usd} $  (${q.payment.amount_micro} micro-USDC)`);
+    console.log(`providers  ${q.providers_in_order.join(" puis ")}`);
+    console.log(`exécutera  ${q.will_execute}${q.refused_because ? ` — ${q.refused_because}` : ""}`);
+    if (q.cheaper_direct) {
+      console.log(`\nmoins cher en direct : ${q.cheaper_direct.route} à ${q.cheaper_direct.price_usd} $ (${q.cheaper_direct.you_save_usd} $ économisés)`);
+      console.log(`  ${q.cheaper_direct.note}`);
+    }
+    process.exit(0);
+  }
+
+  if (verbe === "solve") {
+    const r = await g.solve(demande());
+    if (json) { console.log(JSON.stringify(r, null, 2)); process.exit(0); }
+    console.log(`capacité ${r.capability} · ${r.routing.provider} · ${r.routing.latency_ms} ms`);
+    if (r.routing.attempts.length > 1) {
+      console.log(`tentatives : ${r.routing.attempts.map((a) => `${a.provider}${a.ok ? " ok" : " échec"}`).join(" | ")}`);
+    }
+    console.log("");
+    console.log(JSON.stringify(r.result, null, 2));
+    process.exit(0);
+  }
+
+  sortir(`verbe inconnu « ${verbe} »\n\n${AIDE}`);
+} catch (e) {
+  if (e instanceof PaymentRequired) {
+    console.error("paiement requis. Le défi x402 :");
+    for (const a of e.accepts) console.error(`  ${a.network} · ${a.amount} (micro-USDC) · vers ${a.payTo}`);
+    console.error("\nUtilise « preview » pour voir le plan sans payer, ou passe un fetch payeur au SDK.");
+    process.exit(2);
+  }
+  if (e instanceof GatewayError) {
+    console.error(`erreur : ${e.message}`);
+    if (e.body) console.error(JSON.stringify(e.body, null, 2));
+    process.exit(1);
+  }
+  throw e;
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "x402-agent-gateway",
+  "version": "0.1.0",
+  "description": "One endpoint for any agent capability: resolve a task, route it to the best provider, pay per call in USDC over x402.",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "bin": {
+    "agent-gateway": "bin/cli.js"
+  },
+  "files": [
+    "src",
+    "bin",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test test/"
+  },
+  "keywords": [
+    "x402",
+    "agent",
+    "gateway",
+    "mcp",
+    "a2a",
+    "usdc",
+    "ai",
+    "ai-agents",
+    "pay-per-call",
+    "sec-edgar",
+    "agentic-commerce"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/laurenthalbrun/x402-agent-gateway.git",
+    "directory": "node"
+  },
+  "homepage": "https://github.com/laurenthalbrun/x402-agent-gateway#readme",
+  "bugs": {
+    "url": "https://github.com/laurenthalbrun/x402-agent-gateway/issues"
+  },
+  "author": "laurenthalbrun",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.js

@@ -0,0 +1,128 @@
+// SDK Node du Universal Agent Gateway.
+//
+// Objectif : première intégration en moins de cinq minutes. Donc trois fonctions, aucune
+// dépendance obligatoire, et le paiement optionnel.
+//
+// Choix qui compte : `preview` et `capabilities` sont GRATUITS et ne demandent aucun
+// portefeuille. Un développeur doit pouvoir installer, appeler, voir le plan et le prix,
+// et décider ensuite. Un SDK qui exige une clé ou un portefeuille avant de montrer quoi
+// que ce soit se fait désinstaller.
+
+const DEFAUT = "https://api.x-402.online";
+
+export class GatewayError extends Error {
+  constructor(message, { status, body } = {}) {
+    super(message);
+    this.name = "GatewayError";
+    this.status = status;
+    this.body = body;
+  }
+}
+
+/** Levée quand la route répond 402 et qu'aucun moyen de paiement n'a été fourni.
+ *  Elle porte le défi tel quel : le montant, le réseau et l'adresse sont dedans, donc un
+ *  agent peut payer avec son propre outillage sans que ce SDK impose le sien. */
+export class PaymentRequired extends GatewayError {
+  constructor(challenge) {
+    super("payment required", { status: 402, body: challenge });
+    this.name = "PaymentRequired";
+    this.challenge = challenge;
+    this.accepts = challenge && challenge.accepts ? challenge.accepts : [];
+  }
+}
+
+export class Gateway {
+  /**
+   * @param {object} [opts]
+   * @param {string} [opts.baseUrl]   par défaut https://api.x-402.online
+   * @param {Function} [opts.fetch]   un fetch qui sait payer x402 (par ex. @x402/fetch).
+   *                                  Sans lui, `solve` lève PaymentRequired avec le défi.
+   * @param {string} [opts.apiKey]    clé interne, pour les appels qui ne passent pas par x402
+   * @param {number} [opts.timeoutMs] 60 s par défaut ; certaines capacités prennent 12 s
+   */
+  constructor(opts = {}) {
+    this.baseUrl = (opts.baseUrl || DEFAUT).replace(/\/+$/, "");
+    this.fetch = opts.fetch || globalThis.fetch;
+    this.apiKey = opts.apiKey || null;
+    this.timeoutMs = opts.timeoutMs || 60000;
+  }
+
+  async #appel(chemin, { method = "POST", body } = {}) {
+    const headers = { "content-type": "application/json" };
+    if (this.apiKey) headers["x-api-key"] = this.apiKey;
+    const r = await this.fetch(`${this.baseUrl}${chemin}`, {
+      method,
+      headers,
+      body: body === undefined ? undefined : JSON.stringify(body),
+      signal: AbortSignal.timeout(this.timeoutMs),
+    });
+    const txt = await r.text();
+    let j = null;
+    try { j = JSON.parse(txt); } catch { /* laisse j a null */ }
+    if (r.status === 402) throw new PaymentRequired(j);
+    if (!r.ok) {
+      throw new GatewayError(
+        (j && (j.error || j.erreur)) || `HTTP ${r.status}`,
+        { status: r.status, body: j ?? txt.slice(0, 400) },
+      );
+    }
+    return j;
+  }
+
+  // Les trois méthodes sont `async` pour une raison précise, trouvée par un test : sans
+  // ça, une demande malformée levait de façon SYNCHRONE pendant que tout le reste
+  // rejetait une promesse. Un appelant qui fait `.catch()` n'attrape pas un throw
+  // synchrone, et son programme s'arrête là où il croyait avoir géré l'erreur. Une API
+  // qui échoue de deux façons différentes selon l'erreur est un piège.
+
+  /** Le registre : ce que le gateway sait faire, avec les schémas et le prix. Gratuit. */
+  async capabilities() {
+    return this.#appel("/v1/capabilities", { method: "GET" });
+  }
+
+  /** Le devis : quelle capacité, quelle entrée normalisée, quel prix, et si une route
+   *  directe est moins chère. Gratuit, n'exécute rien, ne consomme aucun amont. */
+  async preview(demande) {
+    return this.#appel("/v1/solve/preview", { body: normaliser(demande) });
+  }
+
+  /** L'exécution. Sans fetch payeur, lève PaymentRequired en portant le défi x402. */
+  async solve(demande) {
+    return this.#appel("/v1/solve", { body: normaliser(demande) });
+  }
+
+  // ===== Appels directs, pour qui sait déjà ce qu'il veut =====================
+  //
+  // Le gateway devine la capacité à partir d'une tâche en mots simples, ce qui est
+  // pratique quand on ne sait pas. Quand on sait, deviner est du travail inutile et,
+  // à prix unique, le gateway coûte plus cher que la route directe. Ces méthodes
+  // appellent donc la route, et le SDK le dit plutôt que de pousser vers le gateway.
+
+  /** Identité d'une société cotée américaine, depuis SEC EDGAR. 0,02001 $. */
+  async usCompany(tickerOuCik) {
+    if (!tickerOuCik) throw new GatewayError("usCompany attend un ticker ou un CIK");
+    return this.#appel("/v1/us/company", { body: { ticker: String(tickerOuCik) } });
+  }
+
+  /** Briefing sourcé sur une société cotée américaine : synthèse dont chaque affirmation
+   *  cite son origine, plus l'identité, les comptes annuels et les dépôts récents en clair
+   *  pour vérification. 0,040004 $, contre 0,090024 $ si on achète les trois séparément. */
+  async usBrief(tickerOuCik) {
+    if (!tickerOuCik) throw new GatewayError("usBrief attend un ticker ou un CIK");
+    return this.#appel("/v1/us/brief", { body: { ticker: String(tickerOuCik) } });
+  }
+}
+
+/** Accepte `solve("une tâche")` aussi bien que `solve({ capability, input })`. */
+function normaliser(d) {
+  if (typeof d === "string") return { task: d };
+  if (d && typeof d === "object") return d;
+  throw new GatewayError("demande invalide : une chaîne ou { task } ou { capability, input }");
+}
+
+/** Raccourci sans instanciation, pour le cas le plus courant. */
+export function gateway(opts) {
+  return new Gateway(opts);
+}
+
+export default Gateway;