@agent-society/connector

ILP connector node for AI agent payment networks. Routes messages, tracks balances, settles on-chain.

This is the core package of the agent-runtime monorepo. See the root README for full usage documentation.

Install

npm install @agent-society/connector

What's Inside

• ILP Packet Routing — RFC-0027 compliant packet forwarding with configurable routing tables
• BTP Peers — WebSocket-based peer connections using Bilateral Transfer Protocol (RFC-0023)
• Tri-Chain Settlement — Payment channels on Base L2 (EVM), XRP Ledger, and Aptos
• Accounting — In-memory ledger (default, zero dependencies) or TigerBeetle (optional, high-throughput)
• Explorer UI — Built-in real-time dashboard for packet flow, balances, and settlement monitoring
• Admin API — HTTP endpoints for peer management, balance queries, and ILP packet sending
• CLI — npx agent-runtime setup, health, validate commands

Quick Example

import { ConnectorNode, createLogger } from '@agent-society/connector';

const node = new ConnectorNode('config.yaml', createLogger('my-agent', 'info'));

node.setPacketHandler(async (request) => {
  console.log(`Received ${request.amount} tokens`);
  return { accept: true };
});

await node.start();

Configuration

YAML config file or pass a config object directly:

nodeId: my-agent
btpServerPort: 3000
healthCheckPort: 8080

peers:
  - id: peer-b
    url: ws://peer-b:3001
    authToken: secret-token

routes:
  - prefix: g.peer-b
    nextHop: peer-b

Accounting Backend

Default: In-Memory Ledger

Zero dependencies. Persists to JSON snapshots on disk.

| Variable | Default | Description | | --- | --- | --- | | LEDGER_SNAPSHOT_PATH | ./data/ledger-snapshot.json | Snapshot file path | | LEDGER_PERSIST_INTERVAL_MS | 30000 | Persistence interval (ms) |

Optional: TigerBeetle

High-performance double-entry accounting. Falls back to in-memory if connection fails.

| Variable | Required | Description | | --- | --- | --- | | TIGERBEETLE_CLUSTER_ID | Yes | TigerBeetle cluster identifier | | TIGERBEETLE_REPLICAS | Yes | Comma-separated replica addresses |

Explorer UI

Enabled by default. Provides real-time packet visualization and settlement monitoring.

| Variable | Default | Description | | --- | --- | --- | | EXPLORER_ENABLED | true | Enable/disable explorer | | EXPLORER_PORT | 3001 | HTTP/WebSocket port | | EXPLORER_RETENTION_DAYS | 7 | Event retention period | | EXPLORER_MAX_EVENTS | 1000000 | Maximum events to retain |

Endpoints:

| Endpoint | Description | | --- | --- | | GET /api/events | Query historical events (supports filtering) | | GET /api/health | Explorer health status | | WS /ws | Real-time event streaming |

Exported API

Classes: ConnectorNode, ConfigLoader, RoutingTable, PacketHandler, BTPServer, BTPClient, BTPClientManager, AdminServer, AccountManager, SettlementMonitor, UnifiedSettlementExecutor

Types: ConnectorConfig, PeerConfig, RouteConfig, SettlementConfig, LocalDeliveryConfig, SendPacketParams, PaymentRequest, PaymentResponse, ILPPreparePacket, ILPFulfillPacket, ILPRejectPacket

Utilities: createLogger, createPaymentHandlerAdapter, computeFulfillmentFromData, computeConditionFromData, validateIlpSendRequest

Package Structure

src/
├── core/       # Packet forwarding, ConnectorNode, payment handler
├── btp/        # BTP server and client (WebSocket peers)
├── routing/    # Routing table and prefix matching
├── settlement/ # Multi-chain settlement executors, claim signing
├── http/       # Admin API, health endpoints, ILP send handler
├── explorer/   # Embedded telemetry UI server and event store
├── wallet/     # HD wallet derivation for multi-chain keys
├── security/   # KMS integration (AWS, Azure, GCP)
├── config/     # Configuration schema and validation
└── utils/      # Logger, OER encoding

Testing

npm test                 # Unit tests
npm run test:acceptance  # Acceptance tests

License

MIT — see LICENSE.