Overview
An adapter is a Domain A component that bridges an AI agent framework to the ISCL secure signing layer. Adapters construct declarativeTxIntent objects, call ISCL Core over HTTP, and present results back to the agent or user. They never touch private keys, never sign transactions, and never call the blockchain directly.
Every adapter in the Clavion ecosystem follows the same four-step contract:
- Accept user/agent input (natural language, command, tool call).
- Build a
TxIntentdescribing the desired on-chain action. - Send the intent through the ISCL Core API for policy checks, simulation, approval, signing, and broadcast.
- Return the result to the caller.
Architecture Pattern
Every adapter sits between the agent framework and ISCL Core, acting as a translation layer. Component overview:Existing Adapters
All four adapters share the same core pattern:ISCLClient + buildIntent() + executeSecurePipeline(). The only differences are how they receive input and present output.
| Adapter | Framework | Package | Use Case | Key Files |
|---|---|---|---|---|
| OpenClaw | OpenClaw runtime | @clavion/adapter-openclaw | AI agent skills | src/skills/, src/shared/iscl-client.ts |
| MCP | Model Context Protocol | @clavion/adapter-mcp | Claude Desktop / Cursor / IDEs | src/server.ts, src/tools/ |
| Eliza | ElizaOS (ai16z) | @clavion/plugin-eliza | Autonomous agents | src/index.ts, src/actions/ |
| Telegram | grammY | @clavion/adapter-telegram | Chat-based approval | src/bot.ts, src/commands/ |
ISCLClient
Copy The constructor reads the base URL from three sources in priority order:
Common error codes:
src/shared/iscl-client.ts from any existing adapter. The client is framework-agnostic and identical across all adapters. It wraps the ISCL Core REST API with typed methods.Constructor
options.baseUrl(explicit)ISCL_API_URLenvironment variablehttp://127.0.0.1:3000(default)
Key Methods
| Method | HTTP Call | Purpose |
|---|---|---|
health() | GET /v1/health | Connectivity check, returns version + uptime |
txBuild(intent) | POST /v1/tx/build | Build transaction (policy check only, no signing) |
txPreflight(intent) | POST /v1/tx/preflight | Simulate + risk score |
txApproveRequest(intent) | POST /v1/tx/approve-request | Full pipeline: build + preflight + user prompt |
txSignAndSend(payload) | POST /v1/tx/sign-and-send | Sign + broadcast (requires approval token) |
balance(token, account, chainId?) | GET /v1/balance/:token/:account | Read ERC-20 or native balance |
txReceipt(hash) | GET /v1/tx/:hash | Look up transaction receipt |
Error Handling
All methods throwISCLError on non-2xx responses:| Status | Meaning |
|---|---|
| 400 | Invalid TxIntent (schema validation failed) |
| 403 | Policy denied the transaction |
| 404 | Resource not found (e.g., unknown tx hash) |
| 422 | Preflight simulation reverted |
| 500 | Internal server error |
Intent Builder
The intent builder converts framework-specific parameters into a
TxIntent object. Every adapter has one, and they are nearly identical.Building Actions for Each Type
- ERC-20 Transfer
- Native ETH Transfer
- ERC-20 Approval
- Swap (exact input)
Handler Functions -- The 2-Step Pipeline
Every fund-affecting operation follows the same two-step pipeline:
txApproveRequest(intent)— Sends the intent to ISCL Core, which runs policy checks, preflight simulation, and prompts the user for approval. This call blocks until the user approves or denies.txSignAndSend({ intent, approvalTokenId })— If approved, sends the intent with the single-use approval token. ISCL Core verifies the token, signs the transaction, and broadcasts it.
Shared Pipeline Function
Extract this intosrc/shared/pipeline.ts so all handlers share the same logic:Complete Handler Example
Read-Only Operations
Balance checks and transaction lookups do not require the approval pipeline:Framework Integration
Each framework has its own way of registering tools, commands, or actions. Below are the patterns used by the four existing adapters.
- MCP
- ElizaOS
- Telegram
- OpenClaw
Register tools on an
McpServer instance. Each tool has a name, description, Zod schema, and async handler.Key file:
packages/adapter-mcp/src/server.tsSecurity Checklist
Every adapter must satisfy these five invariants. Violations break the trust model and will be caught by thedomain-b-integrity.test.ts security test suite.
| # | Rule | What to Check |
|---|---|---|
| 1 | Never import Domain B packages | No imports from @clavion/signer, @clavion/policy, @clavion/audit, @clavion/preflight, @clavion/registry, or @clavion/sandbox. The only allowed monorepo dependency is @clavion/types. |
| 2 | Never access private keys | No reading key files, no process.env.PRIVATE_KEY, no key material in memory. The adapter has no concept of a private key. |
| 3 | Never make direct RPC/blockchain calls | No viem client creation, no ethers.JsonRpcProvider, no fetch("https://rpc.example.com"). All chain access goes through the ISCL Core API (/v1/balance/, /v1/tx/, etc.). |
| 4 | Never construct raw calldata | No encodeFunctionData, no ABI encoding, no raw data fields. Use the declarative TxIntent format and let ISCL Core build the transaction. |
| 5 | Always handle ISCLError responses | Check for ISCLError, display policy deny reasons to the user, and never silently swallow errors. A policy denial is not a bug — it is the system working correctly. |
Complete Minimal Example
A self-contained adapter that works with any framework. This example implements a transfer handler in approximately 60 lines:transfer() from whatever command, tool, or action handler your framework provides.
Further Reading
- API Reference — Full endpoint documentation and response schemas
- TxIntent Schema — Detailed schema definitions
- Trust Domains — Domain A/B/C boundaries explained
- Development Setup — Local development environment
- Repository Structure — Package layout and dependencies