Documentation

npm install @routedock/routedock

The package ships ESM and CJS dual builds with full TypeScript declarations. Subpath imports keep your bundle small:

import { RouteDockClient } from '@routedock/routedock'        // types + client
import { RouteDockClient } from '@routedock/routedock/client' // client only
import { routedock } from '@routedock/routedock/provider'      // provider only

Peer dependency: express@^4.18.0 (for provider middleware).

The agent client wraps all three payment modes behind a single function call.

import { RouteDockClient } from '@routedock/routedock'
import { Keypair } from '@stellar/stellar-sdk'

const client = new RouteDockClient({
  wallet: Keypair.fromSecret(process.env.AGENT_SECRET),
  network: 'testnet',
  spendCap: { daily: '1.00', asset: 'USDC' },         // optional local guard
  commitmentSecret: process.env.COMMITMENT_SECRET,      // required for mpp-session
})

// One-shot payment — mode selected automatically from manifest
const result = await client.pay('https://provider.example.com/price')
// result.data   — response body
// result.txHash — settlement hash (or null for session vouchers)
// result.mode   — 'x402' | 'mpp-charge' | 'mpp-session'
// result.amount — amount paid

// Sustained streaming access via payment channel
const session = await client.openSession('https://provider.example.com/stream')
for await (const update of session.stream()) {
  console.log(update)
  if (done) break
}
const closeResult = await session.close()
// closeResult.closeTxHash — on-chain settlement hash
// closeResult.totalPaid   — cumulative USDC paid
// closeResult.vouchersIssued — number of off-chain vouchers

One Express middleware handles all three payment modes, serves the manifest, and settles on-chain.

import express from 'express'
import { routedock } from '@routedock/routedock/provider'

const app = express()

app.use('/price', routedock({
  modes: ['x402', 'mpp-charge'],
  pricing: { x402: '0.001', 'mpp-charge': '0.0008' },
  asset: 'USDC',
  assetContract: process.env.USDC_ASSET_CONTRACT,
  payee: process.env.STELLAR_PAYEE_ADDRESS,
  payeeSecretKey: process.env.STELLAR_PAYEE_SECRET,
  network: process.env.STELLAR_NETWORK,
  facilitatorApiKey: process.env.OPENZEPPELIN_API_KEY,  // mainnet x402 only
  manifest,
  onSettled: async (txHash, amount, mode) => {
    console.log(`Settled: ${mode} ${amount} USDC — ${txHash}`)
  },
}))

app.get('/price', async (req, res) => {
  // This only runs after payment is verified
  res.json({ price: '0.199', pair: 'XLM/USDC' })
})

On testnet, x402 uses a local ExactStellarFacilitatorScheme — no third-party dependency. On mainnet, it routes to the OpenZeppelin hosted facilitator automatically.

Every provider serves /.well-known/routedock.json. The SDK fetches and validates it against a JSON Schema (AJV, draft-07) before every call.

{
  "routedock": "1.0",
  "name": "Stellar DEX Price Feed",
  "modes": ["x402", "mpp-charge"],
  "network": "testnet",
  "asset": "USDC",
  "asset_contract": "CBIELTK6YBZJU5UP2WWQEUCYKLPU6AUNZ2BQ4WWFEIE3USCIHMXQDAMA",
  "payee": "G...",
  "pricing": {
    "x402": { "amount": "0.001", "per": "request" },
    "mpp-charge": { "amount": "0.0008", "per": "request" }
  },
  "endpoints": { "price": "GET /price" },
  "tags": ["price", "stellar", "dex"]
}

The JSON Schema lives at packages/sdk/src/schemas/routedock.schema.json. Providers validate the manifest at startup — invalid manifests prevent the server from starting.

Deterministic, manifest-driven, no randomness:

1. If caller passes { sustained: true } and manifest supports mpp-session → open payment channel
2. Else if manifest supports mpp-charge → native SAC transfer (lower fees, no facilitator)
3. Else if manifest supports x402 → x402 with facilitator
4. Else throw RouteDockNoSupportedModeError

Override with { forceMode: 'x402' } to bypass automatic selection.

The MPP session mode uses the stellar-experimental/one-way-channel Soroban contract.

1. Channel deployed with USDC deposit, commitment key, recipient, refund window (17280 ledgers)
2. Each interaction: agent signs cumulative ed25519 commitment off-chain — no RPC call, no tx fee
3. Server verifies by simulating prepare_commitment on the contract (read-only)
4. On close: server calls close(amount, signature) — one Soroban tx settles everything

50 interactions, 2 on-chain transactions. Each voucher costs zero gas. The channel contract enforces settlement via ed25519_verify on Soroban.

The agent vault at contracts/agent-vault/ uses the Crossmint stellar-smart-account pattern. Three policies run inside __check_auth:

• Daily cap — rejects if current_day_spend + amount > daily_cap
• Endpoint allowlist — rejects transfers to addresses not in the stored allowlist
• Session key expiry — rejects if the current ledger exceeds the expiry ledger

These are consensus-layer guarantees — Soroban rejects the transaction before broadcast. The agent cannot overspend even if the SDK is compromised.

The Supabase providers table indexes manifests withpg_trgm trigram search. Agents can query by capability:

SELECT * FROM providers
WHERE name % 'streaming price feed'
ORDER BY similarity(name, 'streaming price feed') DESC

Tags, description, and manifest JSON are all indexed. No exact keyword matching required.

Provider:

STELLAR_NETWORK=testnet              # or mainnet
STELLAR_PAYEE_SECRET=S...            # server keypair
STELLAR_PAYEE_ADDRESS=G...           # derived from above
OPENZEPPELIN_API_KEY=...             # mainnet x402 only
USDC_ASSET_CONTRACT=CBIELTK6...      # testnet USDC SAC
SUPABASE_URL=https://...supabase.co
SUPABASE_SERVICE_KEY=eyJ...          # never expose to clients
CHANNEL_CONTRACT_ID=C...             # mpp-session only
COMMITMENT_PUBLIC_KEY=G...           # mpp-session only

Agent:

STELLAR_NETWORK=testnet
AGENT_SECRET=S...
COMMITMENT_SECRET=S...               # ed25519 key for signing vouchers
AGENT_DAILY_CAP_USDC=0.002
PROVIDER_A_URL=http://localhost:3001
PROVIDER_B_URL=http://localhost:3002

Dashboard:

NEXT_PUBLIC_SUPABASE_URL=https://...supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJ...
NEXT_PUBLIC_STELLAR_NETWORK=testnet
NEXT_PUBLIC_STELLAR_EXPERT_URL=https://stellar.expert/explorer/testnet