Headless Stellar wallet SDK for autonomous AI agents on the x402 payment protocol.
Meridian gives AI agents the ability to discover, negotiate, and pay for HTTP APIs autonomously — no browser, no human approval, no WalletConnect popup. It handles everything from keypair management and stablecoin balance tracking to Soroban auth-entry signing, spending policy enforcement, and cross-stablecoin path payment routing.
If you are building an agent that needs to pay for things, Meridian is the foundation.
The x402 protocol revives HTTP 402 as a standard for per-request stablecoin payments. An x402-enabled server returns a 402 Payment Required response with a machine-readable payment specification. The client pays, re-sends the request with proof of payment, and receives the resource — all in a single round-trip.
The problem: every existing Stellar wallet is built for humans. They assume a browser, a UI, and a person clicking "Approve." Autonomous agents have none of those things.
Meridian is the missing piece. It is purpose-built for server-side agents — headless, programmatic, and designed with the assumption that no human will be watching when a payment is made.
- Complete x402 round-trip — parse a 402 response, sign the Soroban auth entry, verify with the facilitator, and retry the original request in a single method call
- Policy engine — per-request, per-hour, per-day, and per-session spending limits; endpoint whitelists and blacklists; velocity limits; violation hooks
- Cross-stablecoin routing — if your agent holds PYUSD but the server requires USDC, Meridian resolves a path payment through the Stellar DEX atomically
- Encrypted key storage — AES-256-GCM encryption at rest, pluggable storage adapters (file, environment variable, OS keychain, in-memory)
- Persistent spending ledger — SQLite-backed budget accounting that survives agent restarts
- Audit-grade logging — every payment attempt, policy decision, and settlement recorded via structured Pino logs
- Facilitator resilience — fallback facilitator chain, exponential backoff, circuit breaker, capability caching
- Testnet-first development — auto-fund via Stellar friendbot, mock facilitator utility for fast offline tests
- Node.js 20 or higher
- A Stellar account (Meridian can generate and fund one on testnet automatically)
- A funded stablecoin balance (USDC, PYUSD, or USDY on Stellar)
- Access to an x402 facilitator (the OpenZeppelin testnet facilitator works out of the box)
pnpm add meridian-walletMeridian is organized into five internal modules that compose into a single wallet interface. You never import the modules directly — you instantiate a wallet and call methods.
Incoming x402 payment request (HTTP 402 response)
│
▼
┌───────────────────┐
│ Balance Tracker │ Confirms sufficient stablecoin and XLM reserves
└────────┬──────────┘
│
▼
┌───────────────────┐
│ Policy Engine │ Evaluates spending rules — approves or rejects
└────────┬──────────┘
│
▼
┌───────────────────┐
│ Path Resolver │ If asset mismatch, finds DEX conversion route
└────────┬──────────┘
│
▼
┌───────────────────┐
│ Auth Signer │ Constructs and signs the Soroban auth entry
└────────┬──────────┘
│
▼
┌───────────────────┐
│ Facilitator │ /verify → resource delivery → /settle
└────────┬──────────┘
│
▼
Response returned
Ledger updated
Audit log written
Keypair generation, import (secret key, raw seed, BIP-39 mnemonic), AES-256-GCM encryption at rest, pluggable storage adapters, and account activation checks. The secret key never leaves this module and is never logged.
Queries USDC, PYUSD, USDY, and XLM balances via Horizon. Manages trustlines. Caches balances with configurable TTL and invalidates after every outgoing payment. Performs a sufficient-funds pre-check before any signing operation.
The core x402 primitive. Parses 402 responses, constructs Soroban authorization entries, handles nonce management, signs in-process, and manages the full facilitator interaction cycle — /verify, resource delivery confirmation, and /settle.
Evaluates spending policies before every signing operation. Maintains a SQLite-backed spending ledger that persists across agent restarts. Supports hot-reload of policy configuration and violation hooks with configurable severity levels.
When the agent's available stablecoin doesn't match the server's required asset, queries Horizon's path-finding API for a strict-receive route through the Stellar DEX. Enforces slippage protection. Constructs the path payment Soroban auth entry atomically.
The primary method. Makes an HTTP request and handles the x402 payment flow automatically if a 402 response is received. Returns the final HTTP response.
Returns current stablecoin and XLM balances. Uses cached values within the TTL window.
The wallet's Stellar public address (G...).
Funds the wallet via Stellar friendbot. Testnet only.
Dry-run policy evaluation. Returns { approved: boolean, reason?: string } without signing anything. Useful for checking affordability before committing to a workflow.
Returns a summary of session spending: total spent, spend by asset, spend by endpoint, payments by hour.
Hot-reload the spending policy without restarting the wallet.
Register a callback for policy violations. Callback receives { reason, severity, details }.
Returns discovered facilitator capabilities from cached /supported responses.
Secret keys never leave the process. Signing happens in-process inside the Key Manager. The secret key is never passed to any external call, never logged, and never serialized in any response or error message.
Every payment is gated by policy. No Soroban auth entry is signed without passing through the Policy Engine. A policy violation aborts the payment before any cryptographic operation occurs.
External input is validated at the boundary. Every 402 response, facilitator response, and configuration object is validated against a Zod schema before any internal code touches it. Malformed or unexpected input is rejected with a descriptive error.
Budget accounting survives restarts. The spending ledger is persisted to SQLite. An agent that crashes and restarts does not lose its memory of what it spent in the current hour or day.
For production deployments: use the OS keychain adapter (keySource: { type: 'keychain' }) or an external secrets manager rather than storing secret keys in environment variables or files. The storage adapter interface is designed to make HashiCorp Vault and AWS Secrets Manager integrations straightforward to implement.
| Asset | Network | Issuer |
|---|---|---|
| USDC | Mainnet | Centre (via Stellar anchor) |
| PYUSD | Mainnet | Paxos (via Stellar anchor) |
| USDY | Mainnet | Ondo Finance (via Stellar anchor) |
| USDC | Testnet | Testnet anchor |
Meridian is byte-compatible with the x402-stellar npm package and the OpenZeppelin x402 facilitator. It implements the x402 v2 payment specification.
MIT