@stableyard/mppx-stableyard 0.1.0

package/src/client.ts

@@ -0,0 +1,143 @@
+import { Credential, Method } from 'mppx'
+import { charge } from './method.js'
+import { StableyardAPI, type StableyardConfig, type Session } from './stableyard-api.js'
+
+/** Deposit info returned by Stableyard for the agent to pay */
+export type DepositInfo = {
+  /** Deposit type: "direct_transfer" (same-chain) or "gasyard" (cross-chain via gateway) */
+  type: string
+  /** Address to send funds to (for direct transfer) or gateway address */
+  address?: string
+  gatewayAddress?: string
+  /** Chain ID */
+  chainId: number
+  /** Token details */
+  token: { address: string; symbol: string; decimals: number }
+  /** Amount to send */
+  amount: { raw: string; formatted: string }
+  /** Payment methods — includes gateway calldata for cross-chain */
+  methods: Array<{
+    type: string
+    address?: string
+    gatewayAddress?: string
+    transactions?: Array<{ type: string; to: string; data: string; value: string; chainId: number }>
+    gaslessSupported?: boolean
+    gaslessEndpoint?: string
+    instructions?: string[]
+  }>
+}
+
+/**
+ * Function that executes the on-chain payment.
+ * Receives the full deposit info so the agent can choose the best method
+ * (direct transfer, gateway, or gasless).
+ */
+export type SendPaymentFn = (deposit: DepositInfo, session: Session) => Promise<string | null>
+
+export type ClientConfig = StableyardConfig & {
+  /** Preferred chain for payment (e.g., "base", "polygon", "arbitrum") */
+  chain?: string
+  /** Maximum time to wait for settlement in ms (defaults to 60000) */
+  settlementTimeoutMs?: number
+  /**
+   * Function to execute the on-chain payment.
+   * Receives deposit info with address/calldata.
+   * Returns tx hash, or null if payment was handled externally (e.g., gasless).
+   *
+   * If not provided, the client will create the session and wait
+   * for external payment (e.g., via checkoutUrl).
+   */
+  sendPayment?: SendPaymentFn
+}
+
+/**
+ * Creates a Stableyard charge method for the client side.
+ *
+ * When the client encounters a 402 with method="stableyard", it automatically:
+ * 1. Creates a Stableyard session with sourceChain → gets deposit address inline
+ * 2. Calls sendPayment to execute the transfer (if provided)
+ * 3. Submits tx hash for faster detection
+ * 4. Polls until settled
+ * 5. Returns credential with sessionId as proof
+ *
+ * @example
+ * ```ts
+ * import { Mppx } from 'mppx/client'
+ * import { stableyard } from 'mppx-stableyard/client'
+ *
+ * Mppx.create({
+ *   methods: [
+ *     stableyard({
+ *       apiKey: 'sy_secret_...',
+ *       chain: 'base',
+ *       sendPayment: async (deposit) => {
+ *         // Direct transfer: send USDC to deposit address
+ *         if (deposit.type === 'direct_transfer') {
+ *           return await sendERC20(deposit.address, deposit.amount.raw)
+ *         }
+ *         // Cross-chain: execute gateway transactions
+ *         for (const tx of deposit.methods[0].transactions) {
+ *           await walletClient.sendTransaction(tx)
+ *         }
+ *         return txHash
+ *       },
+ *     }),
+ *   ],
+ * })
+ * ```
+ */
+export function stableyard(config: ClientConfig) {
+  const api = new StableyardAPI({
+    apiKey: config.apiKey,
+    baseUrl: config.baseUrl,
+  })
+
+  const chain = config.chain ?? 'base'
+  const settlementTimeoutMs = config.settlementTimeoutMs ?? 60_000
+
+  return Method.toClient(charge, {
+    async createCredential({ challenge }) {
+      const { amount, currency, destination } = challenge.request
+
+      // 1. Create session with sourceChain → deposit address inline
+      const session = await api.createSession({
+        amount: Number(amount),
+        destination,
+        currency: (currency === 'USDC' || currency === 'USDT') ? currency : 'USDC',
+        sourceChain: chain,
+        resource: `${challenge.realm}/${challenge.intent}`,
+        metadata: {
+          mpp_challenge_id: challenge.id,
+          mpp_method: 'stableyard',
+        },
+      })
+
+      // 2. Execute payment if sendPayment provided and deposit info available
+      if (config.sendPayment && session.deposit) {
+        const txHash = await config.sendPayment(session.deposit as unknown as DepositInfo, session)
+
+        // 3. Submit tx hash for faster detection
+        if (txHash) {
+          await api.submitTx(session.id, txHash, chain).catch(() => {
+            // Non-fatal — Stableyard may detect independently
+          })
+        }
+      }
+
+      // 4. Wait for settlement
+      await api.waitForSettlement(session.id, settlementTimeoutMs)
+
+      // 5. Return credential with session ID as proof
+      return Credential.serialize(
+        Credential.from({
+          challenge,
+          payload: {
+            sessionId: session.id,
+          },
+        }),
+      )
+    },
+  })
+}
+
+export { charge } from './method.js'

package/src/index.ts

@@ -0,0 +1,3 @@
+export { charge } from './method.js'
+export { StableyardAPI } from './stableyard-api.js'
+export type { StableyardConfig, CreateSessionParams, Session, QuoteResponse, VerifyResponse } from './stableyard-api.js'

package/src/method.ts

@@ -0,0 +1,37 @@
+import { Method, z } from 'mppx'
+
+/**
+ * Stableyard charge method definition for MPP.
+ *
+ * Enables cross-chain payments via Stableyard's settlement network.
+ * Agent pays from any supported chain → Stableyard routes → merchant
+ * receives on their preferred chain/token or fiat to bank.
+ */
+export const charge = Method.from({
+  name: 'stableyard',
+  intent: 'charge',
+  schema: {
+    credential: {
+      payload: z.object({
+        /** Stableyard session ID proving payment */
+        sessionId: z.string(),
+        /** Transaction hash (optional, for faster detection) */
+        txHash: z.optional(z.string()),
+      }),
+    },
+    request: z.object({
+      /** Amount in smallest unit (e.g., "1000000" for $1 USDC with 6 decimals) */
+      amount: z.string(),
+      /** Currency identifier (e.g., "USDC", "USDT") */
+      currency: z.string(),
+      /** Number of decimal places for the currency */
+      decimals: z.number(),
+      /** Stableyard destination — username (merchant@stableyard) or wallet address */
+      destination: z.string(),
+      /** Human-readable description */
+      description: z.optional(z.string()),
+      /** External reference ID for merchant reconciliation */
+      externalId: z.optional(z.string()),
+    }),
+  },
+})

package/src/server.ts

@@ -0,0 +1,87 @@
+import { Method } from 'mppx'
+import { charge } from './method.js'
+import { StableyardAPI, type StableyardConfig } from './stableyard-api.js'
+
+export type ServerConfig = StableyardConfig & {
+  /** Stableyard destination for receiving payments (e.g., "merchant@stableyard" or wallet address) */
+  destination: string
+  /** Default currency (defaults to "USDC") */
+  currency?: string
+  /** Number of decimal places (defaults to 6 for USDC) */
+  decimals?: number
+  /** Maximum time to wait for settlement verification in ms (defaults to 30000) */
+  verifyTimeoutMs?: number
+}
+
+/**
+ * Creates a Stableyard charge method for the server side.
+ *
+ * Accepts payments from any chain supported by Stableyard (Base, Arbitrum,
+ * Polygon, BNB, Ethereum, Solana, Movement) and settles to the merchant's
+ * preferred chain/token/fiat.
+ *
+ * @example
+ * ```ts
+ * import { Mppx } from 'mppx/server'
+ * import { stableyard } from 'mppx-stableyard/server'
+ *
+ * const mppx = Mppx.create({
+ *   methods: [
+ *     stableyard({
+ *       apiKey: 'sy_secret_...',
+ *       destination: 'merchant@stableyard',
+ *     }),
+ *   ],
+ * })
+ * ```
+ */
+export function stableyard(config: ServerConfig) {
+  const api = new StableyardAPI({
+    apiKey: config.apiKey,
+    baseUrl: config.baseUrl,
+  })
+
+  const currency = config.currency ?? 'USDC'
+  const decimals = config.decimals ?? 6
+  const verifyTimeoutMs = config.verifyTimeoutMs ?? 30_000
+
+  return Method.toServer(charge, {
+    defaults: {
+      currency,
+      decimals,
+      destination: config.destination,
+    },
+
+    async verify({ credential, request }) {
+      const { sessionId, txHash } = credential.payload
+
+      // Submit tx hash for faster detection if provided
+      if (txHash) {
+        await api.submitTx(sessionId, txHash, 'auto').catch(() => {
+          // Non-fatal — Stableyard may detect it independently
+        })
+      }
+
+      // Verify the session payment
+      const verification = await api.verifySession(sessionId)
+
+      if (!verification.verified) {
+        // If not yet verified, poll for settlement
+        try {
+          await api.waitForSettlement(sessionId, verifyTimeoutMs)
+        } catch {
+          throw new Error(`Payment verification failed for session ${sessionId}`)
+        }
+      }
+
+      return {
+        method: 'stableyard' as const,
+        status: 'success' as const,
+        reference: sessionId,
+        timestamp: new Date().toISOString(),
+      }
+    },
+  })
+}
+
+export { charge } from './method.js'

package/src/stableyard-api.ts

@@ -0,0 +1,275 @@
+/**
+ * Stableyard API client — thin wrapper around api.stableyard.fi/v2
+ *
+ * Handles session creation, verification, payment, and status polling.
+ * Based on OpenAPI spec at https://api.stableyard.fi/sdk.json
+ */
+
+const PRODUCTION_URL = 'https://api.stableyard.fi/v2'
+const SANDBOX_URL = 'https://api-staging.stableyard.fi/v2'
+
+export type StableyardConfig = {
+  /** Stableyard API key (sy_secret_* for server, sy_pub_* for client) */
+  apiKey: string
+  /** Base URL override. Auto-detected from key prefix (sy_test_* → sandbox) */
+  baseUrl?: string
+}
+
+export type CreateSessionParams = {
+  /** Amount in smallest unit (6 decimals). 10000000 = $10.00 USDC */
+  amount: number
+  /** Destination — username@stableyard or wallet address */
+  destination: string
+  /** Currency: "USDC" or "USDT". Defaults to "USDC" */
+  currency?: 'USDC' | 'USDT'
+  /** Human-readable description (max 500 chars) */
+  description?: string
+  /** Metadata (max 20 keys, 500 chars each) */
+  metadata?: Record<string, string>
+  /** Redirect URL on success */
+  successUrl?: string
+  /** API path for x402/paywall use case */
+  resource?: string
+  /** Restrict payer chains. Default: all supported */
+  acceptedChains?: string[]
+  /** Generate QR codes for POS */
+  qrFormats?: ('universal' | 'solana' | 'evm')[]
+  /** Revenue splits (basis points, must total 10000) */
+  splits?: Array<{ destination: string; percentage: number }>
+  /** TTL in seconds. Default: 900 */
+  expiresIn?: number
+  /** Source chain — if provided, calls Intent Engine inline and returns deposit address */
+  sourceChain?: string
+  /** Source token — defaults to session currency */
+  sourceToken?: string
+}
+
+export type Session = {
+  object: 'session'
+  id: string
+  type: 'checkout' | 'deposit' | 'transfer'
+  status: 'open' | 'pending' | 'routing' | 'settled' | 'failed' | 'expired' | 'refunded'
+  livemode: boolean
+  amount: number
+  currency: 'USDC' | 'USDT'
+  amountFormatted: string
+  destination: {
+    accountId: string
+    paymentAddress: string | null
+    wallet: string
+    chain: string
+    token: string
+  }
+  source: {
+    wallet: string
+    chain: string
+    token: string
+  } | null
+  fees: {
+    total: number
+    totalFormatted: string
+    stableyard: number
+    partner: number
+  }
+  checkoutUrl: string | null
+  clientSecret: string | null
+  paymentMethods: Array<{
+    type: 'wallet_direct' | 'vault_balance'
+    depositAddress: string | null
+    chain?: string
+  }> | null
+  /** Deposit info — populated when sourceChain is provided in creation */
+  deposit?: {
+    /** "direct_transfer" (same-chain) or "gasyard" (cross-chain via gateway) */
+    type: string
+    /** Deposit address (for direct transfer) */
+    address?: string
+    /** Gateway contract address (for cross-chain) */
+    gatewayAddress?: string
+    /** Chain ID for payment */
+    chainId: number
+    /** Token details */
+    token: { address: string; symbol: string; decimals: number }
+    /** Amount to send */
+    amount: { raw: string; formatted: string }
+    /** Payment methods with calldata */
+    methods: Array<{
+      type: string
+      address?: string
+      gatewayAddress?: string
+      transactions?: Array<{ type: string; to: string; data: string; value: string; chainId: number }>
+      gaslessSupported?: boolean
+      gaslessEndpoint?: string
+      instructions?: string[]
+    }>
+  } | null
+  metadata: Record<string, string>
+  refundedAmount: number
+  createdAt: number
+  updatedAt: number
+  expiresAt: number
+  settledAt: number | null
+  requestId: string
+}
+
+export type QuoteResponse = {
+  fees: {
+    total: number
+    stableyard: number
+  }
+  merchantReceives: number
+  route: {
+    sourceChain: string
+    destChain: string
+    estimatedSeconds: number
+  }
+  intentOrderId?: string
+  deposit?: {
+    address: string
+    gatewayAddress: string
+    methods: Array<{
+      type: 'gateway' | 'deposit_address'
+      transactions?: Array<{ type: string; to: string; data: string }>
+      address?: string
+    }>
+  }
+}
+
+export type VerifyResponse = {
+  verified: boolean
+  status: string
+  sessionId: string
+  [key: string]: unknown
+}
+
+function detectBaseUrl(apiKey: string): string {
+  if (apiKey.startsWith('sy_test_')) return SANDBOX_URL
+  return PRODUCTION_URL
+}
+
+export class StableyardAPI {
+  private readonly apiKey: string
+  private readonly baseUrl: string
+
+  constructor(config: StableyardConfig) {
+    this.apiKey = config.apiKey
+    this.baseUrl = config.baseUrl ?? detectBaseUrl(config.apiKey)
+  }
+
+  private async request<T>(path: string, options: RequestInit = {}): Promise<T> {
+    const url = `${this.baseUrl}${path}`
+    const res = await fetch(url, {
+      ...options,
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${this.apiKey}`,
+        ...options.headers,
+      },
+    })
+
+    if (!res.ok) {
+      const body = await res.text().catch(() => '')
+      throw new Error(`Stableyard API error ${res.status} on ${path}: ${body}`)
+    }
+
+    return res.json() as Promise<T>
+  }
+
+  /** Create a payment session */
+  async createSession(params: CreateSessionParams): Promise<Session> {
+    return this.request<Session>('/sessions', {
+      method: 'POST',
+      body: JSON.stringify({
+        amount: params.amount,
+        destination: params.destination,
+        currency: params.currency,
+        description: params.description,
+        metadata: params.metadata,
+        successUrl: params.successUrl,
+        resource: params.resource,
+        acceptedChains: params.acceptedChains,
+        qrFormats: params.qrFormats,
+        splits: params.splits,
+        expiresIn: params.expiresIn,
+        sourceChain: params.sourceChain,
+        sourceToken: params.sourceToken,
+      }),
+    })
+  }
+
+  /** Get session details */
+  async getSession(sessionId: string): Promise<Session> {
+    return this.request<Session>(`/sessions/${sessionId}`)
+  }
+
+  /** Get a quote for a specific source chain (preview without commit) */
+  async getQuote(sessionId: string, sourceChain: string, commit?: boolean): Promise<QuoteResponse> {
+    return this.request<QuoteResponse>(`/sessions/${sessionId}/quote`, {
+      method: 'POST',
+      body: JSON.stringify({ sourceChain, commit }),
+    })
+  }
+
+  /** Verify a payment session (for x402/MPP use case) */
+  async verifySession(sessionId: string): Promise<VerifyResponse> {
+    return this.request<VerifyResponse>(`/sessions/${sessionId}/verify`, {
+      method: 'POST',
+    })
+  }
+
+  /** Submit transaction hash for faster detection */
+  async submitTx(sessionId: string, txHash: string, chain: string): Promise<{ status: string }> {
+    return this.request(`/sessions/${sessionId}/submit-tx`, {
+      method: 'POST',
+      body: JSON.stringify({ txHash, chain }),
+    })
+  }
+
+  /** Pay a session from vault (gasless EIP-712) */
+  async payFromVault(
+    sessionId: string,
+    params: { method: 'vault_balance'; signedMessage: string; signerAddress: string },
+  ): Promise<{ status: string }> {
+    return this.request(`/sessions/${sessionId}/pay`, {
+      method: 'POST',
+      body: JSON.stringify(params),
+    })
+  }
+
+  /** Cancel a session */
+  async cancelSession(sessionId: string): Promise<void> {
+    await this.request(`/sessions/${sessionId}/cancel`, { method: 'POST' })
+  }
+
+  /** Resolve a wallet/username/ID to account details */
+  async resolveAccount(query: string): Promise<Record<string, unknown>> {
+    return this.request(`/accounts/resolve?q=${encodeURIComponent(query)}`)
+  }
+
+  /** Check multi-chain portfolio balances (no auth required) */
+  async getPortfolio(address: string): Promise<Record<string, unknown>> {
+    return this.request(`/network/portfolio?address=${encodeURIComponent(address)}`)
+  }
+
+  /** Poll session until settled or timeout */
+  async waitForSettlement(
+    sessionId: string,
+    timeoutMs: number = 60_000,
+    pollIntervalMs: number = 2_000,
+  ): Promise<Session> {
+    const deadline = Date.now() + timeoutMs
+
+    while (Date.now() < deadline) {
+      const session = await this.getSession(sessionId)
+
+      if (session.status === 'settled') return session
+      if (session.status === 'failed' || session.status === 'expired' || session.status === 'refunded') {
+        throw new Error(`Session ${sessionId} ${session.status}`)
+      }
+
+      await new Promise(resolve => setTimeout(resolve, pollIntervalMs))
+    }
+
+    throw new Error(`Session ${sessionId} timed out waiting for settlement`)
+  }
+}

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "declaration": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist", "demo"]
+}