@agentis-hq/cli 0.1.0

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@agentis-hq/cli",
+  "version": "0.1.0",
+  "type": "module",
+  "bin": {
+    "agentis": "./dist/index.js"
+  },
+  "description": "Agentis CLI",
+  "exports": {
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "templates",
+    "package.json"
+  ],
+  "scripts": {
+    "dev": "bun run src/index.ts",
+    "build": "tsup",
+    "check": "bun --check src/index.ts"
+  },
+  "dependencies": {
+    "@agentis-hq/core": "^0.1.0",
+    "@agentis-hq/sdk": "^0.1.0",
+    "@napi-rs/keyring": "^1.2.0",
+    "@noble/ciphers": "^2.2.0",
+    "@noble/curves": "^2.2.0",
+    "@noble/hashes": "^2.2.0",
+    "@scure/bip32": "^2.2.0",
+    "@scure/bip39": "^2.2.0",
+    "@solana-program/system": "^0.12.0",
+    "@solana/kit": "^6.8.0",
+    "uuid": "^14.0.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0"
+  }
+}

package/templates/facilitator/.env.example.tpl

@@ -0,0 +1,20 @@
+AGENTIS_API_URL={{AGENTIS_API_URL}}
+AGENTIS_FACILITATOR_ID={{FACILITATOR_ID}}
+AGENTIS_HEARTBEAT_SECRET={{HEARTBEAT_SECRET}}
+AGENTIS_PUBLIC_URL=
+
+NETWORK={{NETWORK}}
+ACCEPTED_MINT={{ACCEPTED_MINT}}
+FACILITATOR_FEE_BPS={{FEE_BPS}}
+FACILITATOR_PORT=3000
+DATABASE_PATH=data/facilitator.db
+
+KORA_RPC_URL=http://localhost:8080/
+KORA_API_KEY={{KORA_API_KEY}}
+KORA_PORT=8080
+SOLANA_RPC_URL=https://api.devnet.solana.com
+KORA_PRIVATE_KEY=
+
+ADMIN_TOKEN=change-me
+DEFAULT_SELLER_PAY_TO=
+DEFAULT_SELLER_BALANCE_USD=0

package/templates/facilitator/README.md.tpl

@@ -0,0 +1,46 @@
+# {{NAME}}
+
+Kora-backed x402 facilitator scaffolded by Agentis.
+
+## What This Does
+
+- Exposes x402 `/verify`, `/settle`, and `/supported`.
+- Uses Kora to sponsor/sign/submit Solana transactions.
+- Keeps a local SQLite seller ledger.
+- Charges facilitator fees from prepaid seller balances.
+- Sends heartbeat metrics to Agentis for operator tracking.
+
+## Run
+
+```bash
+bun install
+cp .env.example .env
+```
+
+Fill `KORA_PRIVATE_KEY`, then fund that signer with devnet SOL. Start Kora and the facilitator in separate terminals:
+
+```bash
+bun run kora
+bun run dev
+```
+
+## Seller Ledger
+
+The seller should advertise a gross x402 price that already accounts for facilitator fees. This facilitator settles the gross payment to the seller, then deducts its configured fee from the seller's prepaid local ledger.
+
+Add or top up a seller:
+
+```bash
+curl -X POST http://localhost:3000/admin/sellers \
+  -H "content-type: application/json" \
+  -H "x-admin-token: $ADMIN_TOKEN" \
+  -d '{"payTo":"SELLER_WALLET","topUpUsd":10}'
+```
+
+## Publish
+
+After deploying publicly:
+
+```bash
+agentis facilitator publish {{FACILITATOR_ID}} --url https://your-facilitator.example --listed
+```

package/templates/facilitator/kora/kora.toml.tpl

@@ -0,0 +1,103 @@
+[kora]
+rate_limit = 100
+
+[kora.auth]
+api_key = "{{KORA_API_KEY}}"
+
+[kora.cache]
+enabled = false
+default_ttl = 300
+account_ttl = 60
+
+[kora.enabled_methods]
+liveness = true
+estimate_transaction_fee = false
+get_supported_tokens = true
+sign_transaction = true
+sign_and_send_transaction = true
+transfer_transaction = false
+get_blockhash = true
+get_config = true
+get_payer_signer = true
+get_version = true
+
+[validation]
+max_allowed_lamports = 1000000
+max_signatures = 10
+price_source = "Mock"
+allow_durable_transactions = false
+allowed_programs = [
+  "11111111111111111111111111111111",
+  "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
+  "ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL",
+  "ComputeBudget111111111111111111111111111111",
+  "MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr"
+]
+allowed_tokens = [
+  "{{ACCEPTED_MINT}}"
+]
+allowed_spl_paid_tokens = [
+  "{{ACCEPTED_MINT}}"
+]
+disallowed_accounts = []
+
+[validation.fee_payer_policy]
+
+[validation.fee_payer_policy.system]
+allow_transfer = false
+allow_assign = false
+allow_create_account = false
+allow_allocate = false
+
+[validation.fee_payer_policy.system.nonce]
+allow_initialize = false
+allow_advance = false
+allow_authorize = false
+allow_withdraw = false
+
+[validation.fee_payer_policy.spl_token]
+allow_transfer = false
+allow_burn = false
+allow_close_account = false
+allow_approve = false
+allow_revoke = false
+allow_set_authority = false
+allow_mint_to = false
+allow_initialize_mint = false
+allow_initialize_account = false
+allow_initialize_multisig = false
+allow_freeze_account = false
+allow_thaw_account = false
+
+[validation.fee_payer_policy.token_2022]
+allow_transfer = false
+allow_burn = false
+allow_close_account = false
+allow_approve = false
+allow_revoke = false
+allow_set_authority = false
+allow_mint_to = false
+allow_initialize_mint = false
+allow_initialize_account = false
+allow_initialize_multisig = false
+allow_freeze_account = false
+allow_thaw_account = false
+
+[validation.fee_payer_policy.alt]
+allow_create = false
+allow_extend = false
+allow_freeze = false
+allow_deactivate = false
+allow_close = false
+
+[validation.price]
+type = "free"
+
+[kora.usage_limit]
+enabled = false
+cache_url = "redis://localhost:6379"
+max_transactions = 1000
+fallback_if_unavailable = false
+
+[kora.bundle]
+enabled = false

package/templates/facilitator/kora/signers.toml

@@ -0,0 +1,8 @@
+[signer_pool]
+strategy = "round_robin"
+
+[[signers]]
+name = "main_signer"
+type = "memory"
+private_key_env = "KORA_PRIVATE_KEY"
+weight = 1

package/templates/facilitator/package.json.tpl

@@ -0,0 +1,25 @@
+{
+  "name": "{{NAME}}",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "tsx src/facilitator.ts",
+    "start": "tsx src/facilitator.ts",
+    "typecheck": "tsc --noEmit",
+    "kora": "RPC_URL=${SOLANA_RPC_URL:-https://api.devnet.solana.com} kora --config kora/kora.toml rpc start --signers-config kora/signers.toml --port ${KORA_PORT:-8080}"
+  },
+  "dependencies": {
+    "@solana/kora": "^0.2.1",
+    "@x402/core": "^2.10.0",
+    "@x402/svm": "^2.10.0",
+    "dotenv": "^17.2.3",
+    "express": "^5.2.1"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.0",
+    "@types/node": "^24.5.2",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.0"
+  }
+}

package/templates/facilitator/src/facilitator.ts

@@ -0,0 +1,163 @@
+import { config } from 'dotenv'
+import express from 'express'
+import { KoraClient } from '@solana/kora'
+import { SOLANA_DEVNET_CAIP2 } from '@x402/svm'
+import {
+  getMetrics,
+  listSellers,
+  recordSettlement,
+  requireSellerCanPayFee,
+  upsertSeller,
+  microsToDollars,
+} from './ledger'
+import { startHeartbeat } from './heartbeat'
+
+config()
+
+const app = express()
+app.use(express.json({ limit: '2mb' }))
+
+const PORT = Number(process.env.FACILITATOR_PORT ?? 3000)
+const NETWORK = process.env.NETWORK ?? SOLANA_DEVNET_CAIP2
+const KORA_RPC_URL = process.env.KORA_RPC_URL ?? 'http://localhost:8080/'
+const KORA_API_KEY = process.env.KORA_API_KEY ?? ''
+const DEFAULT_FEE_BPS = Number(process.env.FACILITATOR_FEE_BPS ?? 500)
+
+function kora() {
+  return new KoraClient({ rpcUrl: KORA_RPC_URL, apiKey: KORA_API_KEY })
+}
+
+function paymentAmountMicros(paymentRequirements: any): number {
+  const raw = paymentRequirements?.maxAmountRequired ?? paymentRequirements?.amount
+  const amount = typeof raw === 'bigint' ? Number(raw) : Number(String(raw ?? '0'))
+  if (!Number.isFinite(amount) || amount <= 0) throw new Error('Invalid payment amount')
+  return amount
+}
+
+function paymentPayTo(paymentRequirements: any): string {
+  const payTo = String(paymentRequirements?.payTo ?? '')
+  if (!payTo) throw new Error('Missing payment recipient')
+  return payTo
+}
+
+function paymentTransaction(paymentPayload: any): string {
+  const transaction = paymentPayload?.payload?.transaction
+  if (!transaction || typeof transaction !== 'string') throw new Error('Missing Solana transaction in payment payload')
+  return transaction
+}
+
+function assertNetwork(paymentRequirements: any) {
+  const network = String(paymentRequirements?.network ?? '')
+  if (!network.startsWith('solana:')) throw new Error('Invalid network')
+}
+
+function requireAdmin(req: express.Request, res: express.Response): boolean {
+  const token = process.env.ADMIN_TOKEN
+  if (!token || token === 'change-me') {
+    res.status(500).json({ error: 'ADMIN_TOKEN must be set before using admin endpoints' })
+    return false
+  }
+  if (req.header('x-admin-token') !== token) {
+    res.status(401).json({ error: 'Unauthorized' })
+    return false
+  }
+  return true
+}
+
+const defaultSeller = process.env.DEFAULT_SELLER_PAY_TO
+if (defaultSeller) {
+  upsertSeller({
+    payTo: defaultSeller,
+    label: 'default',
+    balanceUsd: Number(process.env.DEFAULT_SELLER_BALANCE_USD ?? 0),
+  })
+}
+
+app.get('/health', (_req, res) => {
+  res.json({ ok: true, network: NETWORK, feeBps: DEFAULT_FEE_BPS, ...getMetrics() })
+})
+
+app.get('/supported', async (_req, res) => {
+  try {
+    const { signer_address } = await kora().getPayerSigner()
+    res.json({
+      kinds: [{
+        x402Version: 2,
+        scheme: 'exact',
+        network: NETWORK,
+        extra: { feePayer: signer_address },
+      }],
+    })
+  } catch (err) {
+    res.status(500).json({ error: err instanceof Error ? err.message : String(err) })
+  }
+})
+
+app.post('/verify', async (req, res) => {
+  try {
+    const { paymentPayload, paymentRequirements } = req.body
+    assertNetwork(paymentRequirements)
+    const payTo = paymentPayTo(paymentRequirements)
+    const amountMicros = paymentAmountMicros(paymentRequirements)
+    requireSellerCanPayFee(payTo, amountMicros, DEFAULT_FEE_BPS)
+    await kora().signTransaction({ transaction: paymentTransaction(paymentPayload) })
+    res.json({ isValid: true })
+  } catch (err) {
+    res.status(400).json({
+      isValid: false,
+      invalidReason: err instanceof Error ? err.message : 'Kora validation failed',
+    })
+  }
+})
+
+app.post('/settle', async (req, res) => {
+  try {
+    const { paymentPayload, paymentRequirements } = req.body
+    assertNetwork(paymentRequirements)
+    const payTo = paymentPayTo(paymentRequirements)
+    const amountMicros = paymentAmountMicros(paymentRequirements)
+    const { feeMicros } = requireSellerCanPayFee(payTo, amountMicros, DEFAULT_FEE_BPS)
+    const { signature } = await kora().signAndSendTransaction({
+      transaction: paymentTransaction(paymentPayload),
+    })
+    recordSettlement({ payTo, signature, amountMicros, feeMicros })
+    res.json({ transaction: signature, success: true, network: NETWORK })
+  } catch (err) {
+    res.status(400).json({
+      transaction: '',
+      success: false,
+      network: NETWORK,
+      errorReason: err instanceof Error ? err.message : 'Kora settlement failed',
+    })
+  }
+})
+
+app.get('/admin/sellers', (req, res) => {
+  if (!requireAdmin(req, res)) return
+  res.json(listSellers().map((seller: any) => ({
+    ...seller,
+    balanceUsd: microsToDollars(seller.balanceMicros),
+  })))
+})
+
+app.post('/admin/sellers', (req, res) => {
+  if (!requireAdmin(req, res)) return
+  const payTo = String(req.body?.payTo ?? '')
+  if (!payTo) return res.status(400).json({ error: 'payTo is required' })
+  const seller = upsertSeller({
+    payTo,
+    label: req.body?.label ? String(req.body.label) : undefined,
+    topUpUsd: req.body?.topUpUsd === undefined ? undefined : Number(req.body.topUpUsd),
+    balanceUsd: req.body?.balanceUsd === undefined ? undefined : Number(req.body.balanceUsd),
+    feeBps: req.body?.feeBps === undefined ? undefined : Number(req.body.feeBps),
+    active: req.body?.active === undefined ? undefined : Boolean(req.body.active),
+  })
+  res.json({ ...seller, balanceUsd: microsToDollars(seller.balanceMicros) })
+})
+
+startHeartbeat()
+
+app.listen(PORT, () => {
+  console.log(`Agentis facilitator listening at http://localhost:${PORT}`)
+  console.log(`Kora RPC: ${KORA_RPC_URL}`)
+})

package/templates/facilitator/src/heartbeat.ts

@@ -0,0 +1,36 @@
+import { getMetrics } from './ledger'
+
+export function startHeartbeat() {
+  const apiUrl = process.env.AGENTIS_API_URL
+  const id = process.env.AGENTIS_FACILITATOR_ID
+  const secret = process.env.AGENTIS_HEARTBEAT_SECRET
+  if (!apiUrl || !id || !secret) {
+    console.warn('[heartbeat] disabled: missing Agentis heartbeat env')
+    return
+  }
+
+  const send = async () => {
+    try {
+      const metrics = getMetrics()
+      await fetch(`${apiUrl}/facilitators/${id}/heartbeat`, {
+        method: 'POST',
+        headers: {
+          'content-type': 'application/json',
+          'x-agentis-heartbeat-secret': secret,
+        },
+        body: JSON.stringify({
+          publicUrl: process.env.AGENTIS_PUBLIC_URL || null,
+          version: 'agentis-facilitator/0.1.0',
+          supported: ['x402', process.env.NETWORK ?? 'solana-devnet'],
+          feeBps: Number(process.env.FACILITATOR_FEE_BPS ?? 500),
+          ...metrics,
+        }),
+      })
+    } catch (err) {
+      console.warn('[heartbeat] failed', err instanceof Error ? err.message : err)
+    }
+  }
+
+  void send()
+  setInterval(send, 30_000).unref()
+}

package/templates/facilitator/src/ledger.ts

@@ -0,0 +1,141 @@
+import { DatabaseSync } from 'node:sqlite'
+import { mkdirSync } from 'fs'
+import { dirname } from 'path'
+
+export type Seller = {
+  payTo: string
+  label: string | null
+  balanceMicros: number
+  feeBps: number | null
+  active: number
+}
+
+const dbPath = process.env.DATABASE_PATH ?? 'data/facilitator.db'
+mkdirSync(dirname(dbPath), { recursive: true })
+
+const db = new DatabaseSync(dbPath)
+db.exec(`
+  PRAGMA journal_mode = WAL;
+  CREATE TABLE IF NOT EXISTS sellers (
+    pay_to TEXT PRIMARY KEY,
+    label TEXT,
+    balance_micros INTEGER NOT NULL DEFAULT 0,
+    fee_bps INTEGER,
+    active INTEGER NOT NULL DEFAULT 1,
+    created_at TEXT NOT NULL,
+    updated_at TEXT NOT NULL
+  );
+  CREATE TABLE IF NOT EXISTS settlements (
+    id TEXT PRIMARY KEY,
+    pay_to TEXT NOT NULL,
+    transaction_signature TEXT NOT NULL,
+    amount_micros INTEGER NOT NULL,
+    fee_micros INTEGER NOT NULL,
+    created_at TEXT NOT NULL
+  );
+`)
+
+export function dollarsToMicros(value: number): number {
+  return Math.round(value * 1_000_000)
+}
+
+export function microsToDollars(value: number): number {
+  return value / 1_000_000
+}
+
+export function getSeller(payTo: string): Seller | null {
+  const row = db.prepare(`
+    SELECT pay_to as payTo, label, balance_micros as balanceMicros, fee_bps as feeBps, active
+    FROM sellers
+    WHERE pay_to = ?
+  `).get(payTo) as Seller | null
+  return row
+}
+
+export function upsertSeller(input: { payTo: string; label?: string | null; topUpUsd?: number; balanceUsd?: number; feeBps?: number | null; active?: boolean }): Seller {
+  const current = getSeller(input.payTo)
+  const now = new Date().toISOString()
+  const balanceMicros = input.balanceUsd === undefined
+    ? (current?.balanceMicros ?? 0) + dollarsToMicros(input.topUpUsd ?? 0)
+    : dollarsToMicros(input.balanceUsd)
+
+  if (current) {
+    db.prepare(`
+      UPDATE sellers
+      SET label = ?, balance_micros = ?, fee_bps = ?, active = ?, updated_at = ?
+      WHERE pay_to = ?
+    `).run(
+      input.label ?? current.label,
+      balanceMicros,
+      input.feeBps ?? current.feeBps,
+      input.active === undefined ? current.active : Number(input.active),
+      now,
+      input.payTo,
+    )
+  } else {
+    db.prepare(`
+      INSERT INTO sellers (pay_to, label, balance_micros, fee_bps, active, created_at, updated_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?)
+    `).run(
+      input.payTo,
+      input.label ?? null,
+      balanceMicros,
+      input.feeBps ?? null,
+      input.active === undefined ? 1 : Number(input.active),
+      now,
+      now,
+    )
+  }
+
+  return getSeller(input.payTo)!
+}
+
+export function requireSellerCanPayFee(payTo: string, amountMicros: number, defaultFeeBps: number): { seller: Seller; feeMicros: number } {
+  const seller = getSeller(payTo)
+  if (!seller || !seller.active) throw new Error('Seller is not enabled on this facilitator')
+  const feeBps = seller.feeBps ?? defaultFeeBps
+  const feeMicros = Math.ceil(amountMicros * feeBps / 10_000)
+  if (seller.balanceMicros < feeMicros) throw new Error('Seller prepaid facilitator balance is too low')
+  return { seller, feeMicros }
+}
+
+export function recordSettlement(input: { payTo: string; signature: string; amountMicros: number; feeMicros: number }) {
+  const now = new Date().toISOString()
+  db.exec('BEGIN IMMEDIATE')
+  try {
+    db.prepare(`
+      UPDATE sellers
+      SET balance_micros = balance_micros - ?, updated_at = ?
+      WHERE pay_to = ?
+    `).run(input.feeMicros, now, input.payTo)
+    db.prepare(`
+      INSERT INTO settlements (id, pay_to, transaction_signature, amount_micros, fee_micros, created_at)
+      VALUES (?, ?, ?, ?, ?, ?)
+    `).run(crypto.randomUUID(), input.payTo, input.signature, input.amountMicros, input.feeMicros, now)
+    db.exec('COMMIT')
+  } catch (err) {
+    db.exec('ROLLBACK')
+    throw err
+  }
+}
+
+export function listSellers() {
+  return db.prepare(`
+    SELECT pay_to as payTo, label, balance_micros as balanceMicros, fee_bps as feeBps, active
+    FROM sellers
+    ORDER BY updated_at DESC
+  `).all()
+}
+
+export function getMetrics() {
+  const settled = db.prepare(`
+    SELECT COUNT(*) as count, COALESCE(SUM(amount_micros), 0) as volumeMicros
+    FROM settlements
+  `).get() as { count: number; volumeMicros: number }
+  const sellers = db.prepare(`SELECT COUNT(*) as count FROM sellers WHERE active = 1`).get() as { count: number }
+  return {
+    settledCount: settled.count,
+    settledVolumeUsd: microsToDollars(settled.volumeMicros),
+    sellerCount: sellers.count,
+  }
+}

package/templates/facilitator/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "strict": true,
+    "skipLibCheck": true,
+    "types": ["node"]
+  },
+  "include": ["src/**/*.ts"]
+}