SKILLS.md Integration Contract

Overview

The SKILLS.md file is the canonical integration contract for AI agents and orchestrators working with the Agentic Wallet platform. It provides a machine-readable specification of capabilities, runtime behavior, schemas, and operational constraints. Location: /SKILLS.md in the repository root Last Verified: 2026-03-03

Purpose

SKILLS.md serves as the single source of truth for:

Integration modes - How agents can interact with the platform (CLI, SDK, API, MCP)
Intent schemas - Canonical request/response formats
Execution semantics - Transaction lifecycle and async behavior
Output contracts - What agents must return after substantial operations
Runtime constraints - Known limitations and operational boundaries

Skills Index Version

Current State

skills_index_version: 3
project: agentic-wallet
network_default: solana-devnet
repo_skill_dir: skills/
repo_skill_files_present: false

The skills/ directory exists but contains no checked-in SKILL.md files. SKILLS.md in the root is the active integration contract.

Integration Modes

Agents can integrate using four primary modes:

Intent Runner (Legacy)
Operator CLI
TypeScript SDK
MCP Tools

Compatibility CLI for orchestrators that use legacy intent formats.

Intent Runner

npm run intent-runner -- --file <intent.json>
npm run intent-runner -- --intent '<json-string>'

Legacy Adapter Behavior:

fromWalletId (base58) → internal walletId UUID lookup
Legacy chain/createdAt/reasoning preserved at intent.legacy
Intent type normalization:
- transfer → transfer_sol or transfer_spl
- swap → swap
- create_mint → create_mint
- mint_token → mint_token

Full-featured command-line interface with all platform operations.

CLI Commands

npm run cli -- doctor
npm run cli -- wallet create [label]
npm run cli -- agent exec <agentId> --type <type> --protocol <protocol> --intent '<json>'
npm run cli -- tx create --wallet-id <id> --type <type> --protocol <protocol> --intent '<json>'

See CLI Integration for complete command reference.

Typed SDK client for programmatic integration.

SDK Usage

import { createAgenticWalletClient } from '@agentic-wallet/sdk';

const client = createAgenticWalletClient(baseUrl, { 
  apiKey, 
  tenantId 
});

// Exposed modules:
client.wallet
client.policy
client.transaction
client.agent
client.protocol
client.risk
client.strategy
client.treasury
client.audit
client.mcp

See SDK Integration for complete module reference.

Model Context Protocol server for AI agent tool invocation.Endpoints:

GET /mcp/tools - List available tools
POST /mcp/call - Invoke a tool

Current Tools (70+ available):

wallet.create, wallet.balance, wallet.tokens
tx.create, tx.get, tx.approve
policy.evaluate, policy.create
protocol.quote, protocol.swap
agent.execute, agent.create
risk.get_protocol, risk.set_protocol
gateway.request (schema-validated generic proxy)

See MCP Integration for complete tool catalog.

Authentication & Scopes

Gateway Configuration

Environment Variables

API_GATEWAY_ENFORCE_AUTH=true|false  # default: true
API_GATEWAY_API_KEYS=key:tenant:scope1,scope2;key2:*:all
API_GATEWAY_RATE_LIMIT_PER_MINUTE=<int>

Required Headers

x-api-key: <key>
x-tenant-id: <tenant>  # optional

Scope Groups

API keys can be scoped to specific capability groups:

wallets - Wallet operations
transactions - Transaction lifecycle
policies - Policy management
agents - Agent runtime
protocols - Protocol adapters
risk - Risk controls
strategy - Strategy/backtesting
treasury - Treasury operations
audit - Audit/observability
mcp - MCP tools

Example:

API_GATEWAY_API_KEYS=dev-api-key:*:all;restricted-key:tenant-a:wallets,transactions

Canonical Intent Schemas

Transaction Create

Request Schema

{
  "walletId": "uuid",
  "agentId": "uuid",         // optional
  "type": "transactionType",
  "protocol": "string",
  "gasless": false,           // optional
  "idempotencyKey": "string", // optional
  "intent": {}                // type-specific payload
}

Supported Transaction Types

View All Transaction Types (26 types)

transfer_sol - Native SOL transfer
transfer_spl - SPL token transfer
swap - DEX swap
stake - Validator staking
unstake - Validator unstaking
lend_supply - Lending protocol supply
lend_borrow - Lending protocol borrow
create_mint - Create SPL token mint
mint_token - Mint SPL tokens
query_balance - Query balance (read-only)
query_positions - Query positions (read-only)
create_escrow - Create escrow contract
accept_escrow - Accept escrow
release_escrow - Release escrow funds
refund_escrow - Refund escrow
dispute_escrow - Dispute escrow
resolve_dispute - Resolve escrow dispute
create_milestone_escrow - Create milestone escrow
release_milestone - Release milestone payment
x402_pay - HTTP 402 payment
flash_loan_bundle - Flash loan bundle
cpi_call - Cross-program invocation
custom_instruction_bundle - Custom instruction bundle
treasury_allocate - Treasury allocation
treasury_rebalance - Treasury rebalance
paper_trade - Paper trade (no real funds)

Common Intent Payloads

{
  "type": "transfer_sol",
  "protocol": "system-program",
  "intent": {
    "destination": "base58-pubkey",
    "lamports": 1000000
  }
}

{
  "type": "transfer_spl",
  "protocol": "spl-token",
  "intent": {
    "destination": "base58-pubkey",
    "mint": "token-mint-pubkey",
    "amount": "1000000"
  }
}

{
  "type": "swap",
  "protocol": "jupiter",
  "intent": {
    "inputMint": "SOL_MINT",
    "outputMint": "USDC_MINT",
    "amount": "1000000",
    "slippageBps": 50
  }
}

{
  "type": "query_balance",
  "protocol": "system-program",
  "intent": {}
}

Read-only intents (query_balance, query_positions) do not produce on-chain signatures and confirm without submission.Rent precheck: transfer_sol validates unfunded destination rent threshold before execution.

Policy Rule Types

Policies support 11 rule types for governance:

Policy Rule Reference

spending_limit - Per-transaction and daily spending caps

{
  "type": "spending_limit",
  "maxLamportsPerTx": 1000000,
  "maxLamportsPerDay": 10000000,
  "requireApprovalAboveLamports": 500000
}

address_allowlist - Allowed destination addresses
address_blocklist - Blocked destination addresses
program_allowlist - Allowed program IDs
token_allowlist - Allowed token mints

protocol_allowlist - Allowed protocol adapters

{
  "type": "protocol_allowlist",
  "protocols": ["system-program", "jupiter"]
}

rate_limit - Transaction rate limiting
time_window - Time-based restrictions
max_slippage - Maximum slippage tolerance
protocol_risk - Protocol risk controls
portfolio_risk - Portfolio exposure limits

Transaction Lifecycle

Canonical execution pipeline: Behavior Rules:

POST /api/v1/transactions returns 201, 202, or 500 based on current state
Use GET /api/v1/transactions/:txId polling for final state
If approval_gate, call /approve or /reject
idempotencyKey replays prior record when identical key is reused
Durable outbox is SQLite-backed for create/retry/approve processing

Response Envelope

Gateway normalizes all responses to a stable machine envelope:

Response Format

{
  "status": "success" | "failure",
  "errorCode": "VALIDATION_ERROR" | "POLICY_VIOLATION" | "PIPELINE_ERROR" | "CONFIRMATION_FAILED" | null,
  "failedAt": "validation" | "policy" | "build" | "sign" | "send" | "confirm" | "completed" | "gateway" | null,
  "stage": "validation" | "policy" | "build" | "sign" | "send" | "confirm" | "completed" | "gateway",
  "traceId": "uuid",
  "data": {},
  "error": "optional string",
  "errorMessage": "optional string"
}

Critical Behavior: GET /api/v1/transactions/:txId may return HTTP 200 but envelope status="failure" when data.status="failed".Agents must key control flow from envelope status, errorCode, and stage, not HTTP code alone.

Error Codes

VALIDATION_ERROR - Schema/input mismatch
POLICY_VIOLATION - Policy/capability/budget disallow
PIPELINE_ERROR - Build/sign/send/runtime failures
CONFIRMATION_FAILED - Explicit confirmation-stage failures

Agent Heartbeat Context

When agents run in autonomous mode, the scheduler provides context on each tick:

Scheduler Context Fields

{
  "tick": 1,
  "walletId": "uuid",
  "knownWallets": [...],
  "meta": {...},
  "balance": {...},
  "tokens": [...],
  "recentTransactions": [...],
  "openApprovals": [...],
  "protocolPositions": [...],
  "escrowSummary": {...},
  "policySummary": {...}
}

Agents can use this context to make autonomous decisions based on current state.

Output Contract for Agents

For substantial runs, agents should return:

Interface used - CLI/API/SDK/MCP
Commands or API calls executed - Full command/request log
Wallet/agent/transaction IDs and signatures - All created resources
Final statuses and policy decisions - Terminal states
Proof/replay references - Auditability artifacts
Remaining risks or TODOs - Operational notes

Example Output:

Agent Run Summary

## Interface
SDK (TypeScript)

## Commands Executed
1. `client.wallet.create({ label: 'bot-1' })`
2. `client.agent.create({ name: 'arb-bot', walletId, ... })`
3. `client.agent.execute(agentId, { type: 'swap', ... })`

## IDs
- Wallet: `abc-123`
- Agent: `def-456`
- Transaction: `ghi-789`
- Signature: `base58-sig`

## Status
- Transaction: `confirmed`
- Policy: `allow`

## Proofs
- `/api/v1/transactions/ghi-789/proof`
- `/api/v1/transactions/ghi-789/replay`

## Risks
- Escrow adapter requires deployed program ID

Reliability & Durability

RPC Failover

RPC Pool Configuration

SOLANA_RPC_URL=https://api.devnet.solana.com
SOLANA_RPC_POOL_URLS=https://rpc1.com,https://rpc2.com,https://rpc3.com
SOLANA_RPC_HEALTH_PROBE_MS=30000
SOLANA_RPC_MAX_RETRIES=3
SOLANA_RPC_RETRY_DELAY_MS=1000

Behavior:

Health-scored RPC pool failover
Background endpoint probes and runtime health scoring
Adaptive compute budget and priority fee tuning

Durable Outbox

Outbox Configuration

TX_OUTBOX_LEASE_MS=60000
TX_OUTBOX_POLL_MS=5000
TX_OUTBOX_MAX_ATTEMPTS=5
TRANSACTION_ENGINE_DB_PATH=./data/tx-engine.db

Semantics:

SQLite-backed queue with lease/retry/dedupe/recovery
Restart recovery drain of pending processing work
Deterministic idempotency via idempotencyKey

Delta Guard

Delta Guard Configuration

DELTA_GUARD_ABSOLUTE_TOLERANCE_LAMPORTS=5000

Behavior:

Checks expected vs observed lamport movement
Absolute lamport tolerance avoids false positive fee-noise pauses
Auto-pause on delta breach respects wallet autoPauseOnBreach control

Security Guardrails

Critical Security Rules:

Agent logic must never hold or print private keys
Signing is only through wallet-engine sign boundary
Keep execution pipeline ordering intact
Simulate before submit whenever supported
Default demos/tests to Solana devnet
Do not bypass durable outbox for spend-capable actions
Choose signer backend explicitly for production

Signer Backends

Signer Configuration

WALLET_SIGNER_BACKEND=encrypted-file|memory|kms|hsm|mpc

# KMS
WALLET_KMS_MASTER_SECRET=...
WALLET_KMS_KEY_ID=...  # optional

# HSM
WALLET_HSM_PIN=...
WALLET_HSM_MODULE_SECRET=...
WALLET_HSM_SLOT=...  # optional

# MPC
WALLET_MPC_NODE_SECRETS=secret1,secret2,secret3
# or
WALLET_MPC_NODE1_SECRET=...
WALLET_MPC_NODE2_SECRET=...
WALLET_MPC_NODE3_SECRET=...

Known Limitations

Single-node persistence

Persistence is SQLite-backed and single-node. Horizontal scale needs Postgres + distributed queue infrastructure.

Protocol adapter availability

Solend/DEX adapters depend on external API contracts and availability. They fail closed instead of returning synthetic fallback quotes.

Escrow program deployment

Escrow adapter requires a deployed escrow program (ESCROW_PROGRAM_ID) and account wiring in intent. This repo does not ship a deployed escrow program artifact.

MCP tool coverage

MCP includes a validated generic gateway.request tool, but named high-level MCP wrappers are curated (not exhaustive one-by-one parity wrappers).

Minimal Integration Runbook

Install dependencies

npm install

Configure environment

cp .env.example .env
# Edit .env with required values

Minimum required:

WALLET_KEY_ENCRYPTION_SECRET
API_GATEWAY_API_KEYS (or keep default)

Start services

set -a; source .env; set +a
npm run dev

Create wallet & agent

npm run wallets -- create --label bot-1
npm run cli -- agent create arb-bot --intents transfer_sol query_balance

Attach policy

npm run cli -- policy create --wallet-id <walletId> --name limits --rules '[{"type":"spending_limit","maxLamportsPerTx":1000000}]'

Execute intent

npm run cli -- agent exec <agentId> --type query_balance --protocol system-program --intent '{}'

Poll until confirmed/failed

npm run cli -- tx get <txId>

Handle approval gate (if needed)

npm run cli -- tx approve <txId>
# or
npm run cli -- tx reject <txId>

Collect artifacts

npm run cli -- tx proof <txId>
npm run cli -- tx replay <txId>
npm run cli -- audit events --tx-id <txId>
npm run cli -- audit metrics

Smoke Tests

Devnet Validation

npm run devnet:smoke
npm run devnet:multi-agent
npm run devnet:protocol-matrix

Version History

Version	Date	Changes
3	2026-03-03	Current version with SQLite persistence, MCP tools, escrow adapter
2	2026-02-15	Added agent autonomy, treasury, strategy modules
1	2026-01-10	Initial SKILLS.md with core wallet/policy/transaction

Next Steps

CLI Integration

Explore the command-line interface

SDK Integration

Integrate with TypeScript SDK

MCP Tools

Use MCP server for AI agents

API Reference

Browse REST API endpoints

Getting Started

Architecture

Core Concepts

Operations

Security

Integration

SKILLS.md Integration Contract

Overview

Purpose

Skills Index Version

Integration Modes

Authentication & Scopes

Gateway Configuration

Required Headers

Scope Groups

Canonical Intent Schemas

Transaction Create

Supported Transaction Types

Common Intent Payloads

Policy Rule Types

Transaction Lifecycle

Response Envelope

Error Codes

Agent Heartbeat Context

Output Contract for Agents

Reliability & Durability

RPC Failover

Durable Outbox

Delta Guard

Security Guardrails

Signer Backends

Known Limitations

Minimal Integration Runbook

Smoke Tests

Version History

Next Steps

CLI Integration

SDK Integration

MCP Tools

API Reference

​Overview

​Purpose

​Skills Index Version

​Integration Modes

​Authentication & Scopes

​Gateway Configuration

​Required Headers

​Scope Groups

​Canonical Intent Schemas

​Transaction Create

​Supported Transaction Types

​Common Intent Payloads

​Policy Rule Types

​Transaction Lifecycle

​Response Envelope

​Error Codes

​Agent Heartbeat Context

​Output Contract for Agents

​Reliability & Durability

​RPC Failover

​Durable Outbox

​Delta Guard

​Security Guardrails

​Signer Backends

​Known Limitations

​Minimal Integration Runbook

​Smoke Tests

​Version History

​Next Steps

CLI Integration

SDK Integration

MCP Tools

API Reference

Overview

Purpose

Skills Index Version

Integration Modes

Authentication & Scopes

Gateway Configuration

Required Headers

Scope Groups

Canonical Intent Schemas

Transaction Create

Supported Transaction Types

Common Intent Payloads

Policy Rule Types

Transaction Lifecycle

Response Envelope

Error Codes

Agent Heartbeat Context

Output Contract for Agents

Reliability & Durability

RPC Failover

Durable Outbox

Delta Guard

Security Guardrails

Signer Backends

Known Limitations

Minimal Integration Runbook

Smoke Tests

Version History

Next Steps