@valeo-mcp/server 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Valeo Technology LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,145 @@
+# @valeo/mcp
+
+> Give any AI agent the ability to pay for APIs, manage wallets, get credit, and track spending.
+
+One MCP server. Every payment tool an agent needs.
+
+## Quick start
+
+1. **Install / run** — MCP clients typically spawn the server via `npx` (no global install required):
+
+   ```bash
+   npx -y @valeo/mcp
+   ```
+
+2. **Configure** — Add to Claude Desktop `claude_desktop_config.json`:
+
+   ```json
+   {
+     "mcpServers": {
+       "valeo": {
+         "command": "npx",
+         "args": ["-y", "@valeo/mcp"],
+         "env": {
+           "VALEO_PRIVATE_KEY": "0x...",
+           "VALEO_CHAIN": "base",
+           "VALEO_ACE_API_KEY": "sk_...",
+           "VALEO_SENTINEL_API_KEY": "sk_..."
+         }
+       }
+     }
+   }
+   ```
+
+3. **Use** — Ask the agent to discover paid APIs (`discover_apis`), check price (`estimate_cost`), then call them (`pay`). The server negotiates HTTP 402, signs, and settles via x402.
+
+## Tools reference
+
+| Tool | Description |
+|------|-------------|
+| `pay` | Call an x402-enabled URL; handles 402, payment, retry, receipts, and budget checks. |
+| `wallet_balance` | USDC + gas (ETH or SOL) for Base or Solana (same chain family as `VALEO_CHAIN`). |
+| `get_credit` | Request ACE credit when the wallet is short (requires `VALEO_ACE_API_KEY`). |
+| `repay_credit` | Repay an ACE loan by `loan_id` (requires ACE key). |
+| `spending_history` | Sentinel audit trail if configured; otherwise session receipts. |
+| `discover_apis` | Search the 402.md registry by query, category, chain, and max price. |
+| `set_budget` | Per-call, daily, and session limits; optional allow/block URL patterns. |
+| `estimate_cost` | GET probe for pricing without paying; compares budget and wallet. |
+
+## Configuration
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `VALEO_PRIVATE_KEY` | **Yes** | — | EVM: `0x` + 64 hex (66 chars). Solana: base58 secret (64 bytes). |
+| `VALEO_CHAIN` | No | `base` | `base`, `base-sepolia`, `solana`, `solana-devnet` |
+| `VALEO_ACE_API_KEY` | No | — | Enables `get_credit` / `repay_credit` |
+| `VALEO_SENTINEL_API_KEY` | No | — | Full `spending_history` via Sentinel |
+| `VALEO_SOLANA_RPC_URL` | No | public RPC | Custom Solana RPC |
+| `VALEO_ACE_BASE_URL` | No | `https://api.agentcreditengine.com` | ACE API base |
+| `VALEO_SENTINEL_BASE_URL` | No | `https://sentinel.valeocash.com` | Sentinel API base |
+| `VALEO_402MD_BASE_URL` | No | `https://402md.valeoprotocol.io` | 402.md registry |
+| `VALEO_FACILITATOR_URL` | No | `https://x402.org/facilitator` | Documented default facilitator |
+| `VALEO_MAX_PER_CALL` | No | `1.00` | Default max USDC per call |
+| `VALEO_DAILY_LIMIT` | No | `50.00` | Default daily USDC cap |
+| `VALEO_SESSION_LIMIT` | No | `10.00` | Default session USDC cap |
+
+Copy [`.env.example`](.env.example) as a template.
+
+## Supported chains
+
+- **Base** (mainnet) and **Base Sepolia** (testnet) — USDC via viem + `x402-fetch`.
+- **Solana** (mainnet) and **Solana devnet** — USDC SPL + `x402-solana`.
+
+You cannot mix EVM and Solana keys on one server: `wallet_balance` only allows overrides within the same family as `VALEO_CHAIN`.
+
+## How it works
+
+1. Client calls a URL. If the resource is free, you get `200` and `payment: null`.
+2. If the server responds **402** with x402 `accepts` metadata, the server checks **budget** rules, then uses a chain-specific x402 client to sign and attach payment, retrying the request.
+3. Successful spends are recorded in-memory (**receipts**) and reflected in **budget** totals. Optional **Sentinel** key adds remote audit history.
+
+## Valeo ecosystem
+
+- **ACE** — Agent Credit Engine for short-term USDC credit.
+- **Sentinel** — Payment audit trail and transaction history.
+- **402.md** — Discovery registry for x402 manifests.
+- **Stratum** — Settlement layer in the broader Valeo stack (see [valeocash.com](https://valeocash.com) / product docs).
+
+## Example conversations
+
+**1. Simple paid call**
+
+- User: “Get premium data from `https://api.example.com/v1/data`.”
+- Agent: Calls `pay` → “Here is the JSON payload. Paid **$0.01 USDC** on Base. Session budget remaining: **$9.99**.”
+
+**2. Credit flow**
+
+- User: “I need market data but I’m low on USDC.”
+- Agent: `wallet_balance` → `get_credit` → `pay` → “Borrowed USDC via ACE, fetched data, auto-repay rules apply per ACE.”
+
+**3. Discovery + budget**
+
+- User: “Find cheap weather APIs and cap me at **$2** today.”
+- Agent: `set_budget` → `discover_apis` → `estimate_cost` → “Three APIs under **$0.01**/call; roughly **200** calls within your daily cap.”
+
+## Verification
+
+```bash
+cd valeo-mcp
+npm install
+npm run build
+npm run lint
+node bin/valeo-mcp.js
+```
+
+With MCP Inspector:
+
+```bash
+VALEO_PRIVATE_KEY=0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80 \
+  VALEO_CHAIN=base-sepolia \
+  npx @modelcontextprotocol/inspector node bin/valeo-mcp.js
+```
+
+## Publish
+
+```bash
+npm login
+npm publish --access public
+```
+
+Smoke test after publish:
+
+```bash
+npx -y @valeo/mcp
+```
+
+## Important notes
+
+- **stdout is reserved** for MCP JSON-RPC. All diagnostics use **stderr** (`console.error`).
+- **Daily budget** resets at **midnight UTC**; **session** totals reset when the process restarts.
+- If both **allowlist** and **blocklist** could apply, a non-empty **allowlist** wins; blocklist is ignored until allowlist is cleared.
+- **ACE / Sentinel / 402.md** responses are parsed defensively; tools return JSON errors with `suggestion` instead of crashing the server.
+
+## License
+
+MIT — see [LICENSE](LICENSE) (Valeo Technology LLC).

package/bin/valeo-mcp.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+require("../dist/index.js");

package/dist/index.d.mts

@@ -0,0 +1,143 @@
+declare class Four02mdClient {
+    private baseUrl;
+    constructor(baseUrl: string);
+    search(options?: {
+        query?: string;
+        category?: string;
+        chain?: string;
+        maxPrice?: number;
+    }): Promise<unknown>;
+    getManifest(domain: string): Promise<unknown>;
+}
+
+declare class SentinelClient {
+    private baseUrl;
+    private apiKey;
+    constructor(baseUrl: string, apiKey: string);
+    getTransactions(options?: {
+        limit?: number;
+        since?: string;
+        endpoint?: string;
+    }): Promise<unknown>;
+}
+
+declare class ACEClient {
+    private baseUrl;
+    private apiKey;
+    constructor(baseUrl: string, apiKey: string);
+    private request;
+    requestCredit(amount: number, walletAddress: string, purpose?: string): Promise<unknown>;
+    repayLoan(loanId: string, amount?: number): Promise<unknown>;
+    getLoans(): Promise<unknown>;
+}
+
+declare class X402SolanaClient {
+    private keypair;
+    private connection;
+    private network;
+    constructor(privateKeyBase58: string, chain: "solana" | "solana-devnet", rpcUrl?: string);
+    createPaidFetch(maxUsd?: number): typeof globalThis.fetch;
+    getUsdcBalance(): Promise<string>;
+    getSolBalance(): Promise<string>;
+    getAddress(): string;
+    getChain(): string;
+}
+
+declare class X402BaseClient {
+    private walletClient;
+    private publicClient;
+    private walletAddress;
+    private chainName;
+    constructor(privateKey: string, chain: "base" | "base-sepolia");
+    createPaidFetch(maxUsd?: number): typeof globalThis.fetch;
+    getUsdcBalance(): Promise<string>;
+    getEthBalance(): Promise<string>;
+    getAddress(): string;
+    getChain(): string;
+}
+
+declare class ReceiptStore {
+    private receipts;
+    add(data: Omit<Receipt, "id" | "timestamp">): Receipt;
+    getAll(options?: {
+        limit?: number;
+        since?: string;
+        endpoint?: string;
+    }): Receipt[];
+    getTotalSpent(): number;
+    getTotalSpentToday(): number;
+}
+
+declare class BudgetManager {
+    private config;
+    private sessionSpent;
+    private dailySpent;
+    private dailyResetAt;
+    constructor(valeoConfig: ValeoConfig);
+    private getNextMidnightUTC;
+    private checkDailyReset;
+    canSpend(amount: number, endpoint: string): SpendCheck;
+    recordSpend(amount: number): void;
+    getStatus(): BudgetStatus;
+    updateConfig(updates: Partial<BudgetConfig>): void;
+    private matchWildcard;
+}
+
+interface ValeoConfig {
+    privateKey: string;
+    chain: "base" | "base-sepolia" | "solana" | "solana-devnet";
+    aceApiKey?: string;
+    aceBaseUrl: string;
+    sentinelApiKey?: string;
+    sentinelBaseUrl: string;
+    four02mdBaseUrl: string;
+    facilitatorUrl: string;
+    defaultMaxPerCall: number;
+    defaultDailyLimit: number;
+    defaultSessionLimit: number;
+}
+interface BudgetConfig {
+    maxPerCall: number;
+    dailyLimit: number;
+    sessionLimit: number;
+    blockedEndpoints: string[];
+    allowedEndpoints: string[];
+}
+interface BudgetStatus {
+    config: BudgetConfig;
+    spending: {
+        session: number;
+        today: number;
+        remainingSession: number;
+        remainingDaily: number;
+    };
+}
+interface SpendCheck {
+    allowed: boolean;
+    reason?: string;
+}
+interface Receipt {
+    id: string;
+    timestamp: string;
+    endpoint: string;
+    method: string;
+    amount: number;
+    currency: string;
+    chain: string;
+    txHash?: string;
+    status: "settled" | "failed" | "pending";
+    responseStatus: number;
+}
+interface ValeoContext {
+    config: ValeoConfig;
+    budget: BudgetManager;
+    receipts: ReceiptStore;
+    x402Client: X402BaseClient | X402SolanaClient;
+    aceClient: ACEClient | null;
+    sentinelClient: SentinelClient | null;
+    four02mdClient: Four02mdClient;
+}
+
+declare function loadConfig(): ValeoConfig;
+
+export { type ValeoConfig, type ValeoContext, loadConfig };

package/dist/index.d.ts

@@ -0,0 +1,143 @@
+declare class Four02mdClient {
+    private baseUrl;
+    constructor(baseUrl: string);
+    search(options?: {
+        query?: string;
+        category?: string;
+        chain?: string;
+        maxPrice?: number;
+    }): Promise<unknown>;
+    getManifest(domain: string): Promise<unknown>;
+}
+
+declare class SentinelClient {
+    private baseUrl;
+    private apiKey;
+    constructor(baseUrl: string, apiKey: string);
+    getTransactions(options?: {
+        limit?: number;
+        since?: string;
+        endpoint?: string;
+    }): Promise<unknown>;
+}
+
+declare class ACEClient {
+    private baseUrl;
+    private apiKey;
+    constructor(baseUrl: string, apiKey: string);
+    private request;
+    requestCredit(amount: number, walletAddress: string, purpose?: string): Promise<unknown>;
+    repayLoan(loanId: string, amount?: number): Promise<unknown>;
+    getLoans(): Promise<unknown>;
+}
+
+declare class X402SolanaClient {
+    private keypair;
+    private connection;
+    private network;
+    constructor(privateKeyBase58: string, chain: "solana" | "solana-devnet", rpcUrl?: string);
+    createPaidFetch(maxUsd?: number): typeof globalThis.fetch;
+    getUsdcBalance(): Promise<string>;
+    getSolBalance(): Promise<string>;
+    getAddress(): string;
+    getChain(): string;
+}
+
+declare class X402BaseClient {
+    private walletClient;
+    private publicClient;
+    private walletAddress;
+    private chainName;
+    constructor(privateKey: string, chain: "base" | "base-sepolia");
+    createPaidFetch(maxUsd?: number): typeof globalThis.fetch;
+    getUsdcBalance(): Promise<string>;
+    getEthBalance(): Promise<string>;
+    getAddress(): string;
+    getChain(): string;
+}
+
+declare class ReceiptStore {
+    private receipts;
+    add(data: Omit<Receipt, "id" | "timestamp">): Receipt;
+    getAll(options?: {
+        limit?: number;
+        since?: string;
+        endpoint?: string;
+    }): Receipt[];
+    getTotalSpent(): number;
+    getTotalSpentToday(): number;
+}
+
+declare class BudgetManager {
+    private config;
+    private sessionSpent;
+    private dailySpent;
+    private dailyResetAt;
+    constructor(valeoConfig: ValeoConfig);
+    private getNextMidnightUTC;
+    private checkDailyReset;
+    canSpend(amount: number, endpoint: string): SpendCheck;
+    recordSpend(amount: number): void;
+    getStatus(): BudgetStatus;
+    updateConfig(updates: Partial<BudgetConfig>): void;
+    private matchWildcard;
+}
+
+interface ValeoConfig {
+    privateKey: string;
+    chain: "base" | "base-sepolia" | "solana" | "solana-devnet";
+    aceApiKey?: string;
+    aceBaseUrl: string;
+    sentinelApiKey?: string;
+    sentinelBaseUrl: string;
+    four02mdBaseUrl: string;
+    facilitatorUrl: string;
+    defaultMaxPerCall: number;
+    defaultDailyLimit: number;
+    defaultSessionLimit: number;
+}
+interface BudgetConfig {
+    maxPerCall: number;
+    dailyLimit: number;
+    sessionLimit: number;
+    blockedEndpoints: string[];
+    allowedEndpoints: string[];
+}
+interface BudgetStatus {
+    config: BudgetConfig;
+    spending: {
+        session: number;
+        today: number;
+        remainingSession: number;
+        remainingDaily: number;
+    };
+}
+interface SpendCheck {
+    allowed: boolean;
+    reason?: string;
+}
+interface Receipt {
+    id: string;
+    timestamp: string;
+    endpoint: string;
+    method: string;
+    amount: number;
+    currency: string;
+    chain: string;
+    txHash?: string;
+    status: "settled" | "failed" | "pending";
+    responseStatus: number;
+}
+interface ValeoContext {
+    config: ValeoConfig;
+    budget: BudgetManager;
+    receipts: ReceiptStore;
+    x402Client: X402BaseClient | X402SolanaClient;
+    aceClient: ACEClient | null;
+    sentinelClient: SentinelClient | null;
+    four02mdClient: Four02mdClient;
+}
+
+declare function loadConfig(): ValeoConfig;
+
+export { type ValeoConfig, type ValeoContext, loadConfig };