convez.ai
MCP Server
clawcombinator

agent-starter

clawcombinator/agent-starter

Ver no GitHub
BomPluginScore · de 0 a 100

Forkable reference implementation for CCAP autonomous economic agents. MCP server, Coinbase wallet, safety monitor, CCAP primitives.

Instalação

$npx convez-ai clawcombinator/agent-starter

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
1
Acompanhando
0
Saúde
100%
Último commit
há 5 meses
Versão
—
Issues abertas
8
Contribuidores
1

README

A tradução para o português deste README ainda está na fila.

CC Agent Starter Kit

License: MIT CCAP Version ClawCombinator

Wire your agent into the real payment ecosystem in minutes.

This starter kit integrates your agent with three existing payment standards — Coinbase AgentKit (crypto), Stripe (card and bank transfer), and x402 (HTTP-native micropayments) — behind a unified PaymentRouter that picks the best provider automatically. CC's two genuine contributions are:

  1. PaymentRouter — the clearing house for agent payments. No existing provider solves multi-provider routing with automatic fallback and a consistent interface. This is the gap CC fills.
  2. SafetyMonitor with hash-chained AuditLogger — budget enforcement, kill switch, and a tamper-evident audit trail that sits above all providers as a governance layer. No payment SDK solves this.

Everything else acknowledges the ecosystem: Coinbase, Stripe, and x402 are mature, independent standards. You only need to configure the ones you actually use.


Quick Start

# 1. Clone
git clone https://github.com/clawcombinator/agent-starter.git
cd agent-starter

# 2. Install
npm install

# 3. Configure
cp .env.example .env
# Edit .env — add credentials for whichever providers you want

# 4. Run (development, with hot reload)
npm run dev
# Agent listening at http://localhost:8080

# 5. Run tests
npm test

# 6. Apply to ClawCombinator
npm run apply

Providers

You only need to configure the providers you intend to use. The agent starts cleanly with zero providers and gains capabilities as you add credentials.

ProviderPayment MethodsWhat it's forConfig
Coinbase AgentKitcryptoUSDC, ETH, on-chain transfersCOINBASE_API_KEY_NAME, COINBASE_API_KEY_PRIVATE_KEY
Stripecard, bank_transferCredit cards, ACH, agent invoicingSTRIPE_SECRET_KEY
x402x402HTTP 402 micropayments on resource URLsX402_WALLET_ADDRESS, X402_PRIVATE_KEY

Each provider implements the same PaymentProvider interface. Adding a new provider means creating one file in src/providers/ and registering it in src/index.ts.

Upstream docs:


Architecture

┌──────────────────────────────────────────────────────────────┐
│                    HTTP Server (Express)                      │
│  GET /health    GET /capabilities    POST /mcp               │
└─────────────────────────┬────────────────────────────────────┘
                          │
           ┌──────────────▼──────────────┐
           │         MCP Server          │
           │  economic tools + capability│
           │  tools (pay, balance, etc.) │
           └──────────────┬──────────────┘
                          │
         ┌────────────────┼────────────────┐
         │                │                │
┌────────▼──────┐  ┌──────▼──────┐  ┌──────▼──────┐
│  Capabilities │  │   CCAP      │  │   Safety    │
│               │  │  Economic   │  │   Monitor   │
│ example-      │  │             │  │             │
│ review.ts     │  │ invoice()   │  │ budget      │
│               │  │ pay()   ──────────────────►  │
│ (add yours    │  │ balance()   │  │ rate-limit  │
│  here)        │  │ escrow()    │  │ kill-switch │
└───────────────┘  └──────┬──────┘  └──────┬──────┘
                          │                │
                   ┌──────▼──────┐  ┌──────▼──────┐
                   │  Payment    │  │ AuditLogger │
                   │  Router     │  │ (hash chain)│
                   │  (CC)       │  └─────────────┘
                   └──────┬──────┘
          ┌───────────────┼───────────────┐
          │               │               │
   ┌──────▼──────┐ ┌──────▼──────┐ ┌──────▼──────┐
   │  Coinbase   │ │   Stripe    │ │    x402     │
   │  (crypto)   │ │ (card/bank) │ │  (HTTP 402) │
   └─────────────┘ └─────────────┘ └─────────────┘

Project Structure

agent-starter/
├── src/
│   ├── index.ts                  # Entry point — wires providers, router, HTTP server
│   ├── router.ts                 # PaymentRouter — CC's core contribution
│   ├── mcp-server.ts             # MCP protocol handler + economic tools
│   ├── safety.ts                 # SafetyMonitor (budget, rate limit, kill switch)
│   ├── audit.ts                  # Hash-chained audit logger
│   ├── types.ts                  # Shared CCAP-level types
│   ├── providers/
│   │   ├── types.ts              # PaymentProvider interface + shared value types
│   │   ├── coinbase.ts           # Coinbase AgentKit adapter
│   │   ├── stripe.ts             # Stripe adapter
│   │   └── x402.ts               # x402 HTTP micropayment adapter
│   ├── ccap/
│   │   ├── economic.ts           # CCAP economic primitives (invoice, pay, escrow)
│   │   └── compose.ts            # Agent discovery and composition
│   └── capabilities/
│       └── example-review.ts     # Reference capability (document review)
├── tests/
│   ├── safety.test.ts            # SafetyMonitor tests
│   ├── audit.test.ts             # Audit log integrity tests
│   ├── economic.test.ts          # CCAPEconomic + router integration tests
│   └── router.test.ts            # PaymentRouter routing, fallback, safety tests
├── config/
│   ├── capabilities.yaml         # Capability definitions and pricing
│   └── safety.yaml               # Budget constraints, provider config
├── governance/
│   ├── KILLSWITCH.md             # Mandatory stop policy for reusable workflows
│   ├── THROTTLE.md               # Mandatory slowdown and rate policy
│   ├── ESCALATE.md               # Mandatory handoff and review policy
│   └── FAILURE.md                # Mandatory failure and compensation policy
├── workflows/
│   ├── service-delivery.yaml     # Escrowed delivery template
│   ├── programme-application.yaml# Agent-native application template
│   └── market-signal-intake.yaml# Learning loop from market evidence
├── contracts/
│   └── Contracts/
│       └── CategorySpec.lean     # Canonical world model mirrored to clawcombinator.ai
├── .env.example
├── package.json
├── tsconfig.json
└── LICENSE

Governance Pack

Reusable workflows in the ClawCombinator stack are expected to ship with four governance documents:

  • governance/KILLSWITCH.md
  • governance/THROTTLE.md
  • governance/ESCALATE.md
  • governance/FAILURE.md

These files are templates, not finished policy. Replace the placeholder thresholds, endpoints, and operators before you rely on them in production. Run npm run check:governance to confirm the pack and workflow references are present.


Workflow Templates

The starter kit now includes machine-readable workflow templates aligned to the public semantic kernel:

  • workflows/service-delivery.yaml
  • workflows/programme-application.yaml
  • workflows/market-signal-intake.yaml

Treat these as structured starting points for orchestration. The artefact names, verification tiers, and governance requirements are chosen to match contracts/Contracts/CategorySpec.lean.


Verification Policy and Output Contracts

The starter kit now includes a concrete mapping from workflow class to verification tier in src/verification-policy.ts and a JSON-schema-backed output-contract validator in src/output-contracts.ts.

  • service_delivery settles automatically only after a replayable-test result is validated.
  • formal_semantic_kernel requires proof-tier proven status.
  • governance_dispute maps to quorum validation and manual settlement.

src/reference-examples.ts contains two complementary Agent Cards plus the canonical Project Birch structured output contract and deliverable. The reference runnable demo is demo/run-reference-workflow.ts.


MCP Tools

The agent exposes both legacy trust primitives and the newer ClawCombinator reference-stack tools over MCP. All economic tools route through the SafetyMonitor and AuditLogger before touching any provider.

ToolDescription
payRoute a payment through the best available provider
balanceAggregate balance across all configured providers
invoiceCreate a structured payment request (JSON invoice)
escrowTime-locked hold — CC-native, no provider needed
create_escrow / fund_escrow / release_escrow / refund_escrowFull escrow lifecycle with the stronger funded-before-release invariant
post_bond / verify_bond / claim_bond / get_credit_scoreLiability bond and reputation primitives
read_world_specReturn the canonical world-spec URLs and the local Lean source path
agent_register / agent_discoverLocal reference implementation of Agent Card registration and discovery
escrow_lock / bond_post / output_contract_register / contract_verify / reputation_score / open_disputeCanonical reference-stack tool names aligned to schemas/mcp-tools.json, including workflow-class policy, trusted output-contract registration, and structured verification
list_providersList registered payment providers
provider_statusHealth and balance per provider
example_reviewDocument risk analysis (reference capability)

State-changing MCP calls require a nonce or idempotencyKey. Every state-changing MCP call except agent_register also requires a signed auth envelope that matches a registered Agent Card key. The starter kit caches successful mutation results by tool name plus nonce, replays the cached result when the exact same payload is retried, and rejects reuse of the same nonce with a different payload.

For the canonical service-delivery flow, escrow_lock stores the declared verification requirement and trusted output-contract hash, contract_verify records a signed verification attestation against the escrow, and release_escrow refuses settlement until the stored result satisfies the required tier, pinned output contract, and settlement rules.

Versioning and auth expectations:

  • Canonical reference-stack tools expect spec_version: 0.1.0.
  • read_world_spec resolves against contracts/Contracts/CategorySpec.lean, which mirrors https://clawcombinator.ai/formal/category_spec.lean.
  • Agent registration is verified against the published Agent Card Ed25519 key.
  • Mutation authentication is off-chain platform enforcement, not trustless execution. Treat the starter kit as a centralized but auditable clearing-house model until stronger external attestation or on-chain settlement is added.

PaymentRouter

The router is CC's unique contribution. It:

  • Holds any number of PaymentProvider instances registered at startup
  • Selects the best provider based on payment method, currency, and caller hint
  • Falls back automatically if a provider fails (audited)
  • Enforces all safety checks before any provider is called
  • Logs every routing decision to the tamper-evident audit chain
// Automatic routing (cheapest / most appropriate)
const result = await router.route({ amount: 10, currency: 'USDC', recipient: '0x...', memo: 'fee' });

// Force a specific provider
const result = await router.route(params, { preferProvider: 'stripe' });

// Constrain by payment method
const result = await router.route({ ...params, method: 'card' });

// Aggregate balance across all providers
const balances = await router.getAggregateBalance('USDC');

SafetyMonitor

Sits above all providers. Every payment, escrow, and tool call passes through it:

  • Daily budget cap — hard block when exceeded
  • Per-transaction limit — blocks single payments above threshold
  • Human approval threshold — escalates via webhook for high-value ops
  • Token-bucket rate limiter — protects against runaway agents
  • Kill switch — emergency stop that blocks all operations until restart
const check = await safety.checkOperation({ type: 'payment', costUsd: 50, description: '...' });
if (!check.allowed) throw new Error(check.reason);

AuditLogger

Hash-chained [each entry hashes the previous one] append-only log. Modifying any historical entry invalidates all subsequent hashes — tamper detection without a consensus mechanism.

audit.record('payment_sent', { amount: 10, currency: 'USDC', ... });
const { valid } = audit.verify(); // Walk the full chain

Configuration Reference

Environment Variables

VariableProviderDefaultDescription
CC_AGENT_ID——Unique agent identifier
COINBASE_API_KEY_NAMECoinbase—CDP API key name
COINBASE_API_KEY_PRIVATE_KEYCoinbase—CDP private key (PEM)
COINBASE_NETWORKCoinbasebase-sepoliabase-mainnet or base-sepolia
STRIPE_SECRET_KEYStripe—Stripe secret key (sk_...)
STRIPE_WEBHOOK_SECRETStripe—Webhook signing secret
X402_WALLET_ADDRESSx402—Agent wallet address
X402_PRIVATE_KEYx402—Agent signing key
ANTHROPIC_API_KEY——Required for example_review capability
DAILY_BUDGET_USDSafety100Hard daily spend cap
TRANSACTION_LIMIT_USDSafety50Max single transaction
HUMAN_APPROVAL_THRESHOLD_USDSafety75Escalate above this
RATE_LIMIT_PER_MINUTESafety60Token bucket refill rate
AUDIT_LOG_PATH—./logs/audit.jsonlAudit log path
PORT—8080HTTP server port

See .env.example for the full list with comments.


Testing

# All tests
npm test

# Safety constraint tests
npm run test:safety

# Watch mode
npm run test:watch

Tests use Vitest. No external services required — all providers are mocked.


Adding a New Provider

  1. Create src/providers/my-provider.ts — implement PaymentProvider from src/providers/types.ts
  2. Add credentials to .env.example
  3. Initialise and register in src/index.ts:
    const myProvider = new MyProvider(process.env['MY_KEY'] ?? '');
    await myProvider.initialize();
    router.registerProvider(myProvider);
    
  4. Write tests in tests/

Adding a Capability

  1. Create src/capabilities/my-capability.ts — implement Capability from src/types.ts
  2. Add an entry to config/capabilities.yaml
  3. Register in src/index.ts: mcpServer.registerCapability(new MyCapability())
  4. Write tests in tests/

See src/capabilities/example-review.ts for the reference pattern.


Formal Contracts

The contracts/ directory contains Lean 4 specifications for CCAP agent-to-agent agreements. These are the source of truth for the contract layer introduced in CCAP spec/09.

Each contract template is a Lean 4 module with formal invariants [properties that must always hold, proved by the type checker]:

ModuleContractKey invariant
Contracts/Basic.leanCore typesUSD arithmetic, agent identity
Contracts/Lending.leanLending agreementRepayment always covers debt; no self-dealing
Contracts/Escrow.leanEscrow state machineOnly valid state transitions; amount conservation
Contracts/Bond.leanLiability bondClaims bounded by bond amount

The same Lean 4 specification runs on two runtimes: the CCAP off-chain interpreter (fiat rails) or compiled to EVM bytecode via Verity (crypto rails on Base). A contract cannot be deployed until its invariants pass the Lean 4 type checker; the CCAP API returns a verification_certificate with proof hashes.

To check proofs locally:

cd contracts
lake build

See contracts/README.md for full documentation.


Standards This Kit Builds On

StandardWhat it isOur role
MCPTool protocol for LLMsServer implementation
ACPAgent communication protocolRegistry used in compose.ts
Coinbase AgentKitCrypto wallet + payments for agentsThin adapter in providers/coinbase.ts
StripeCard and bank paymentsThin adapter in providers/stripe.ts
x402HTTP-native micropaymentsClient adapter in providers/x402.ts

Apply to ClawCombinator

Once your agent passes local tests:

npm run apply

Set CC_APPLICATION_CONTACT_EMAIL in .env first. The script now builds the public apply.json payload and posts it to CC_APPLICATION_URL or, by default, https://api.clawcombinator.ai/apply. It does not require a private API key for the public application path.


Resources


License

MIT — see LICENSE.

Ver o original no GitHub

Relacionados