@stableyard/mppx-stableyard 0.1.0

package/README.md

@@ -0,0 +1,301 @@
+# mppx-stableyard
+
+A new payment method for [MPP](https://mpp.dev) that lets any agent pay from any chain, and any merchant receive on any chain — powered by [Stableyard](https://stableyard.fi).
+
+```
+tempo()      → Tempo chain only
+stripe()     → cards only
+stableyard() → Base, Polygon, Arbitrum, Ethereum, Solana (+ Tempo, Movement soon) + fiat to bank
+```
+
+## The Problem
+
+MPP launched with two payment methods:
+- `tempo()` — works only on Tempo chain
+- `stripe()` — works only with cards
+
+If an agent has USDC on Base and the server only accepts `tempo()`, the agent can't pay. Wrong chain. Stuck.
+
+## The Solution
+
+`stableyard()` — a new payment method that plugs into mppx:
+
+```typescript
+import { stableyard } from 'mppx-stableyard/server'
+
+const mppx = Mppx.create({
+  methods: [
+    tempo.charge({ ... }),      // Tempo chain
+    stableyard({                // ANY chain
+      apiKey: 'sy_secret_...',
+      destination: 'merchant@stableyard',
+    }),
+  ],
+})
+```
+
+One line added. The server now accepts payments from Base, Arbitrum, Polygon, Ethereum, and Solana — with Tempo and Movement coming soon.
+
+## Supported Chains
+
+| Chain | Chain ID | sourceChain value | Provider | Settlement Time | Status |
+|-------|----------|-------------------|----------|-----------------|--------|
+| Base | 8453 | `base` | direct_transfer | ~1s | Live |
+| Polygon | 137 | `polygon` | gasyard | ~15s | Live |
+| Arbitrum | 42161 | `arbitrum` | gasyard | ~15s | Live |
+| Ethereum | 1 | `ethereum` | gasyard | ~15s | Live |
+| Solana | 103 | `solana` | near_intents | ~22s | Live |
+| Tempo | 4217 | `tempo` | relay | ~15s | Coming soon |
+| Movement | 2 | `movement` | gasyard_v2 | ~3s | Coming soon |
+
+Agent specifies the chain when creating the client:
+
+```typescript
+stableyard({ apiKey: '...', chain: 'base' })     // pay from Base
+stableyard({ apiKey: '...', chain: 'polygon' })   // pay from Polygon
+stableyard({ apiKey: '...', chain: 'solana' })     // pay from Solana
+stableyard({ apiKey: '...', chain: 'tempo' })      // pay from Tempo (coming soon)
+stableyard({ apiKey: '...', chain: 'movement' })   // pay from Movement (coming soon)
+```
+
+Merchant receives on their preferred chain regardless of where the agent paid from. Configure once in the Stableyard dashboard.
+
+## How It Works
+
+```
+Agent calls API
+  ↓
+402 Payment Required
+  WWW-Authenticate: Payment method="stableyard"
+  { amount: "100000", currency: "USDC", destination: "merchant@stableyard" }
+  ↓
+Agent (mppx-stableyard client):
+  1. POST /v2/sessions { amount, destination, sourceChain: "base" }
+     → Gets deposit address on Base (inline, one API call)
+  2. Sends 0.10 USDC to deposit address
+  3. POST /submit-tx { txHash }
+     → Stableyard detects payment
+  4. Polls → settled
+  ↓
+Agent retries with credential { sessionId }
+  ↓
+Server calls POST /v2/sessions/:id/verify
+  → { verified: true }
+  ↓
+200 OK + data + Payment-Receipt
+```
+
+### Cross-Chain Example (Polygon → Base)
+
+Agent has USDC on Polygon. Merchant wants settlement on Base.
+
+```
+Agent: POST /v2/sessions { destination: "merchant@stableyard", sourceChain: "polygon" }
+  → Returns gasyard gateway calldata (approve + deposit txs)
+  → Agent executes gateway transactions on Polygon
+  → Stableyard routes Polygon → Base via solver network
+  → Merchant receives USDC on Base in ~15 seconds
+```
+
+### Same-Chain Example (Base → Base)
+
+```
+Agent: POST /v2/sessions { destination: "merchant@stableyard", sourceChain: "base" }
+  → Returns direct_transfer deposit address
+  → Agent sends USDC to address on Base
+  → Settled in ~1 second
+```
+
+## Proved with Real Money
+
+```
+Session:   ses_b6afc57b153e2ae1f8fb1025
+Tx:        0xbeaf32d41f8f7573e02653a79e02bf56a73ae667dca203acb9e5c181116914a9
+Chain:     Base (mainnet)
+Amount:    0.10 USDC
+Submit tx: → status: pending
+Poll:      → settled in 9 seconds
+Verify:    → { verified: true }
+Basescan:  https://basescan.org/tx/0xbeaf32d41f8f7573e02653a79e02bf56a73ae667dca203acb9e5c181116914a9
+```
+
+## Install
+
+```bash
+npm i mppx-stableyard mppx
+```
+
+## Server
+
+Accept MPP payments via Stableyard. Settle to any chain or fiat.
+
+```typescript
+import { Mppx, tempo } from 'mppx/server'
+import { stableyard } from 'mppx-stableyard/server'
+
+const mppx = Mppx.create({
+  methods: [
+    tempo.charge({ currency: USDC, recipient: '0x...' }),
+    stableyard({
+      apiKey: 'sy_secret_...',
+      destination: 'merchant@stableyard',
+    }),
+  ],
+})
+
+app.get('/api/data', async (req) => {
+  const result = await mppx['stableyard/charge']({
+    amount: '100000',
+    description: 'Premium data',
+  })(req)
+
+  if (result.status === 402) return result.challenge
+  return result.withReceipt(Response.json({ data: '...' }))
+})
+```
+
+The 402 response includes a `WWW-Authenticate: Payment method="stableyard"` challenge. The server verifies payment via Stableyard's `/v2/sessions/:id/verify` endpoint.
+
+## Client
+
+Agent automatically handles 402 → pay via Stableyard → retry.
+
+```typescript
+import { Mppx } from 'mppx/client'
+import { stableyard } from 'mppx-stableyard/client'
+
+Mppx.create({
+  methods: [
+    stableyard({
+      apiKey: 'sy_secret_...',
+      chain: 'base',        // or 'polygon', 'arbitrum', 'ethereum', 'solana'
+      sendPayment: async (deposit) => {
+        // Send USDC to deposit address
+        return await sendERC20(deposit.address, deposit.amount.raw)
+      },
+    }),
+  ],
+})
+
+// fetch auto-handles 402 → pay via Stableyard → retry
+const res = await fetch('https://api.example.com/data')
+```
+
+## What stableyard() Adds to MPP
+
+| Feature | tempo() | stableyard() |
+|---------|---------|-------------|
+| Tempo chain | Yes | Coming soon |
+| Base | | Yes |
+| Polygon | | Yes |
+| Arbitrum | | Yes |
+| Ethereum | | Yes |
+| Solana | | Yes |
+| Movement | | Coming soon |
+| Fiat settlement (bank) | | Yes |
+| Named identity (@stableyard) | | Yes |
+| Gasless payments (vault) | | Yes |
+| Merchant dashboard | | Yes |
+| Cross-chain routing | | Yes |
+
+## Architecture
+
+```
+                     MPP Protocol
+                         |
+           +-------------+-------------+
+           |             |             |
+       tempo()      stripe()    stableyard()
+       Tempo chain   Cards      Any chain -> Any chain
+                                Powered by Stableyard
+                                    |
+                                    |-- Base (direct_transfer, ~1s)
+                                    |-- Polygon (gasyard, ~15s)
+                                    |-- Arbitrum (gasyard, ~15s)
+                                    |-- Ethereum (gasyard, ~15s)
+                                    |-- Solana (near_intents, ~22s)
+                                    |-- Tempo (relay, coming soon)
+                                    |-- Movement (gasyard_v2, coming soon)
+                                    |
+                                    |-- Gasless vault payments (EIP-712)
+                                    |-- Fiat settlement (KYC)
+                                    +-- x402+ backward compatible
+```
+
+Stableyard sits alongside Tempo and Stripe as a payment rail in MPP. Not competing — extending.
+
+## What's Inside
+
+```
+mppx-stableyard/
+  src/method.ts          — Method.from() definition (stableyard/charge)
+  src/server.ts          — Method.toServer() — generates 402 challenges, verifies via Stableyard API
+  src/client.ts          — Method.toClient() — creates session, gets deposit addr, pays, polls
+  src/stableyard-api.ts  — Stableyard API client (sessions, quote, verify, submit-tx, poll)
+  specs/                 — draft-stableyard-charge-00.md (IETF-style protocol spec)
+  demo/server.ts         — Working MPP server with tempo() + stableyard() methods
+  demo/agent.ts          — Agent that auto-pays via Stableyard
+```
+
+## Configuration
+
+### Server
+
+```typescript
+stableyard({
+  apiKey: 'sy_secret_...',            // Stableyard API key
+  destination: 'merchant@stableyard', // Where payments settle
+  currency: 'USDC',                   // Default: 'USDC'
+  decimals: 6,                        // Default: 6
+  verifyTimeoutMs: 30000,             // Default: 30s
+})
+```
+
+### Client
+
+```typescript
+stableyard({
+  apiKey: 'sy_secret_...',            // Stableyard API key
+  chain: 'base',                      // Agent's payment chain
+  settlementTimeoutMs: 60000,         // Default: 60s
+  sendPayment: async (deposit) => {   // Your wallet logic
+    return txHash
+  },
+})
+```
+
+## Try It
+
+```bash
+git clone https://github.com/stableyardfi/mppx-stableyard
+cd mppx-stableyard
+npm install
+
+# Start server
+cp demo/.env.example .env
+npx tsx demo/server.ts
+
+# Test 402 response
+curl -D- http://localhost:3000/api/market-data
+
+# See the MPP challenge with method="stableyard"
+```
+
+## Also Built
+
+- **Protocol spec**: `draft-stableyard-charge-00.md` — IETF-style spec following Lightning/Tempo format
+- **Service registry PR**: Adding Stableyard to [MPP service directory](https://github.com/tempoxyz/mpp) alongside Alchemy, OpenAI, fal.ai
+- **x402+ compatibility**: Same Stableyard backend powers both [x402+](https://github.com/stableyardfi/x402plus) and mppx-stableyard
+
+## Links
+
+- [Stableyard](https://stableyard.fi) — Cross-chain stablecoin payments
+- [MPP](https://mpp.dev) — Machine Payments Protocol
+- [mppx](https://github.com/wevm/mppx) — TypeScript SDK for MPP
+- [x402+](https://github.com/stableyardfi/x402plus) — Stableyard's x402 protocol
+- [Stableyard API](https://api.stableyard.fi/sdk.json) — OpenAPI spec
+- [Basescan proof](https://basescan.org/tx/0xbeaf32d41f8f7573e02653a79e02bf56a73ae667dca203acb9e5c181116914a9) — Real money settlement tx
+
+## License
+
+MIT

package/demo/.env.example

@@ -0,0 +1,11 @@
+# Stableyard API credentials
+STABLEYARD_API_KEY=sy_test_secret_9b64d9a0e65a9acd99081a6e2360410db53a52e778ac4b51
+STABLEYARD_DESTINATION=test@stableyard
+
+# MPP server config
+MPP_SECRET_KEY=somerandomstring
+TEMPO_RECIPIENT=0xB2903d2f1fbe8B4475AfED1DA9a4DE1bA547Bb65
+
+# Agent config
+CHAIN=base
+SERVER_URL=http://localhost:3000

package/demo/agent.ts

@@ -0,0 +1,75 @@
+/**
+ * Demo MPP agent that pays via Stableyard.
+ *
+ * This agent calls the demo server's paid endpoints and automatically
+ * handles 402 → pay via Stableyard → retry.
+ *
+ * Usage:
+ *   STABLEYARD_API_KEY=sy_secret_... tsx demo/agent.ts
+ */
+
+import 'dotenv/config'
+import { Mppx } from 'mppx/client'
+import { stableyard } from '../src/client.ts'
+
+const stableyardApiKey = process.env.STABLEYARD_API_KEY
+
+if (!stableyardApiKey) {
+  console.error('Missing STABLEYARD_API_KEY env var')
+  process.exit(1)
+}
+
+const SERVER_URL = process.env.SERVER_URL ?? 'http://localhost:3000'
+
+// ─── Setup MPP client with Stableyard method ────────────────────────────────
+
+const mppx = Mppx.create({
+  methods: [
+    stableyard({
+      apiKey: stableyardApiKey,
+      chain: process.env.CHAIN ?? 'base',
+    }),
+  ],
+  polyfill: false,
+})
+
+// ─── Agent logic ────────────────────────────────────────────────────────────
+
+async function callEndpoint(path: string, description: string) {
+  console.log(`\n→ Calling ${path} (${description})...`)
+
+  try {
+    const res = await mppx.fetch(`${SERVER_URL}${path}`)
+
+    if (res.ok) {
+      const data = await res.json()
+      console.log(`← 200 OK ✓`)
+      console.log(`  Data:`, JSON.stringify(data, null, 2).split('\n').map(l => `  ${l}`).join('\n'))
+    } else {
+      console.log(`← ${res.status} ${res.statusText}`)
+    }
+  } catch (err) {
+    console.error(`← Error: ${err instanceof Error ? err.message : err}`)
+  }
+}
+
+async function main() {
+  console.log(`
+╔══════════════════════════════════════════════════════════════╗
+║  mppx-stableyard Demo Agent                                 ║
+╠══════════════════════════════════════════════════════════════╣
+║  Server: ${SERVER_URL.padEnd(50)}║
+║  Chain: ${(process.env.CHAIN ?? 'base').padEnd(51)}║
+║  Method: stableyard (cross-chain via Stableyard)             ║
+╚══════════════════════════════════════════════════════════════╝
+`)
+
+  // Call each paid endpoint
+  await callEndpoint('/api/market-data', 'Market data — $0.01')
+  await callEndpoint('/api/analysis', 'AI analysis — $0.05')
+  await callEndpoint('/api/premium-image', 'Premium image — $0.10')
+
+  console.log('\n✓ All endpoints called. Check Stableyard dashboard for settlement details.')
+}
+
+main().catch(console.error)

package/demo/server.ts

@@ -0,0 +1,158 @@
+/**
+ * Demo MPP server using both tempo() and stableyard() payment methods.
+ *
+ * Shows how adding stableyard() gives merchants cross-chain settlement
+ * with zero code changes to the agent side.
+ *
+ * Usage:
+ *   STABLEYARD_API_KEY=sy_secret_... STABLEYARD_DESTINATION=merchant@stableyard tsx demo/server.ts
+ */
+
+import 'dotenv/config'
+import { Hono } from 'hono'
+import { serve } from '@hono/node-server'
+import { Mppx, tempo } from 'mppx/server'
+import { stableyard } from '../src/server.ts'
+
+const TEMPO_CURRENCY = '0x20c0000000000000000000000000000000000000' // pathUSD
+const TEMPO_RECIPIENT = process.env.TEMPO_RECIPIENT ?? '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266'
+
+const stableyardApiKey = process.env.STABLEYARD_API_KEY
+const stableyardDestination = process.env.STABLEYARD_DESTINATION
+
+if (!stableyardApiKey || !stableyardDestination) {
+  console.error('Missing STABLEYARD_API_KEY or STABLEYARD_DESTINATION env vars')
+  process.exit(1)
+}
+
+// ─── Create MPP handler with BOTH methods ───────────────────────────────────
+
+const mppx = Mppx.create({
+  methods: [
+    tempo.charge({
+      currency: TEMPO_CURRENCY,
+      recipient: TEMPO_RECIPIENT,
+    }),
+    stableyard({
+      apiKey: stableyardApiKey,
+      destination: stableyardDestination,
+    }),
+  ],
+  secretKey: process.env.MPP_SECRET_KEY ?? 'demo-secret-key',
+})
+
+// ─── App ────────────────────────────────────────────────────────────────────
+
+const app = new Hono()
+
+// Health check
+app.get('/health', (c) => c.json({ ok: true, methods: ['tempo', 'stableyard'] }))
+
+// ─── Paid endpoint: Market Data ($0.01) ─────────────────────────────────────
+
+app.get('/api/market-data', async (c) => {
+  // Use stableyard method only for clean demo
+  const result = await mppx['stableyard/charge']({
+    amount: '100000',
+    description: 'Market data feed',
+  })(c.req.raw)
+
+  if (result.status === 402) return result.challenge
+
+  return result.withReceipt(
+    Response.json({
+      data: {
+        btc: { price: 98450.23, change24h: 2.1 },
+        eth: { price: 3842.67, change24h: -0.5 },
+        sol: { price: 187.42, change24h: 4.3 },
+      },
+      timestamp: new Date().toISOString(),
+      source: 'stableyard-demo',
+    }),
+  )
+})
+
+// ─── Paid endpoint: AI Analysis ($0.05) ─────────────────────────────────────
+
+app.get('/api/analysis', async (c) => {
+  const result = await mppx['stableyard/charge']({
+    amount: '500000',
+    description: 'AI-powered market analysis',
+  })(c.req.raw)
+
+  if (result.status === 402) return result.challenge
+
+  return result.withReceipt(
+    Response.json({
+      analysis: {
+        summary: 'BTC showing bullish momentum with strong support at $96k. ETH consolidating ahead of upcoming network upgrade.',
+        sentiment: 'bullish',
+        confidence: 0.78,
+        signals: ['RSI oversold bounce', 'Volume spike on support', 'Whale accumulation detected'],
+      },
+      timestamp: new Date().toISOString(),
+    }),
+  )
+})
+
+// ─── Paid endpoint: Premium Image ($0.10) ───────────────────────────────────
+
+app.get('/api/premium-image', async (c) => {
+  const result = await mppx['stableyard/charge']({
+    amount: '1000000',
+    description: 'Premium stock photo',
+  })(c.req.raw)
+
+  if (result.status === 402) return result.challenge
+
+  const imageRes = await fetch('https://picsum.photos/1024/1024')
+  return result.withReceipt(
+    Response.json({
+      imageUrl: imageRes.url,
+      resolution: '1024x1024',
+      license: 'commercial',
+    }),
+  )
+})
+
+// ─── Multi-method endpoint: shows both tempo + stableyard ───────────────────
+
+app.get('/api/multi', async (c) => {
+  const result = await Mppx.compose(
+    mppx['tempo/charge']({ amount: '10000' }),
+    mppx['stableyard/charge']({ amount: '10000', description: 'Multi-method demo' }),
+  )(c.req.raw)
+
+  if (result.status === 402) return result.challenge
+
+  return result.withReceipt(
+    Response.json({ message: 'Paid via tempo OR stableyard!', timestamp: new Date().toISOString() }),
+  )
+})
+
+// ─── Start ──────────────────────────────────────────────────────────────────
+
+const port = Number(process.env.PORT ?? 3000)
+
+serve({ fetch: app.fetch, port }, () => {
+  console.log(`
+╔══════════════════════════════════════════════════════════════╗
+║  mppx-stableyard Demo Server                                ║
+╠══════════════════════════════════════════════════════════════╣
+║                                                              ║
+║  URL: http://localhost:${String(port).padEnd(43)}║
+║  Destination: ${(stableyardDestination ?? '').padEnd(43)}║
+║                                                              ║
+║  Payment Methods:                                            ║
+║    • tempo     → Tempo chain only                            ║
+║    • stableyard → 7 chains + Solana + Movement + fiat        ║
+║                                                              ║
+║  Endpoints:                                                  ║
+║    GET /api/market-data      $0.10  (stableyard only)        ║
+║    GET /api/analysis         $0.50  (stableyard only)        ║
+║    GET /api/premium-image    $1.00  (stableyard only)        ║
+║    GET /api/multi            $0.10  (tempo + stableyard)     ║
+║                                                              ║
+╚══════════════════════════════════════════════════════════════╝
+`)
+})

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@stableyard/mppx-stableyard",
+  "version": "0.1.0",
+  "description": "Stableyard payment method for the Machine Payments Protocol (MPP). Any chain in, any chain out, fiat settlement.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "default": "./dist/server.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "default": "./dist/client.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "demo:server": "tsx demo/server.ts",
+    "demo:agent": "tsx demo/agent.ts"
+  },
+  "keywords": [
+    "mpp",
+    "mppx",
+    "stableyard",
+    "machine-payments",
+    "cross-chain",
+    "stablecoin",
+    "402",
+    "payment-protocol",
+    "agent-payments"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "mppx": "^0.4.7",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "tsx": "^4.19.0",
+    "hono": "^4.7.0",
+    "@hono/node-server": "^1.13.0",
+    "dotenv": "^16.4.0"
+  }
+}