ACK-Pay ADK Tool Adapter

Wrap ACK-Pay payment flows as Google ADK FunctionTools so Gemini-powered agents can make verified USDC payments and receive cryptographic receipts.

The Gap

ACK-Pay provides verifiable payment infrastructure for AI agents -- USDC transfers with W3C Verifiable Credential receipts. The ecosystem already has a LangChain tool adapter, but Google's Agent Development Kit (ADK) is a different framework with its own tool interface.

This adapter bridges that gap: it wraps ACK-Pay operations as ADK FunctionTool instances so any ADK agent can make and verify payments natively.

Framework	Tool Interface	Status
LangChain	@langchain/core Tool	Exists
Google ADK	FunctionDeclaration + Tool	This repo
CrewAI	CrewAI Tool	Planned

Architecture

graph LR
    User([User]) -->|"Pay 5 USDC to did:example:bob"| Agent[ADK Gemini Agent]
    Agent -->|function_call| AckPayTool[AckPayTool]
    AckPayTool -->|USDC transfer| Chain[(Base / Ethereum)]
    AckPayTool -->|generate receipt VC| Receipt[ACK-Pay Receipt VC]
    Receipt -->|function_response| Agent
    Agent -->|"Paid! Receipt: ack:receipt:0x..."| User

    Agent -->|function_call| VerifyTool[VerifyReceiptTool]
    VerifyTool -->|verify VC signature| Valid{Valid?}
    Valid -->|yes| Agent

Loading

sequenceDiagram
    participant U as User
    participant A as ADK Agent (Gemini)
    participant T as AckPayTool
    participant B as Blockchain (Base)
    participant V as VerifyReceiptTool

    U->>A: "Pay alice 10 USDC for design work"
    A->>T: makePayment(amount=10, recipient="did:example:alice", ...)
    T->>B: Initiate USDC transfer
    B-->>T: Transaction hash + confirmation
    T->>T: Generate ACK-Pay receipt VC
    T-->>A: { txHash, receiptVC, status: "confirmed" }
    A-->>U: "Payment confirmed! Receipt: ack:receipt:0xabc..."

    U->>A: "Verify this receipt"
    A->>V: verifyReceipt(receiptId="ack:receipt:0xabc...")
    V-->>A: { valid: true, amount: 10, recipient: "did:example:alice" }
    A-->>U: "Receipt is valid. 10 USDC to alice, confirmed on Base."

Loading

Install

git clone https://github.com/anthropic-labs/ack-adk-tool-adapter.git
cd ack-adk-tool-adapter
npm install
cp .env.example .env
# Fill in your API keys

Quick Start

1. Register the tools with an ADK agent

import { AckPayTool } from "./src/ack-pay-tool";
import { VerifyReceiptTool } from "./src/ack-verify-tool";

// Create tool instances
const payTool = new AckPayTool({
  circleApiKey: process.env.CIRCLE_API_KEY!,
  walletId: process.env.CIRCLE_WALLET_ID!,
  chain: "base-sepolia",
});

const verifyTool = new VerifyReceiptTool();

// Register with your ADK agent (see src/agent-config.ts for full example)

2. Run the demo

npm run build
npm run demo

The demo simulates a user asking an agent to make a payment, showing the full flow from natural language request through blockchain confirmation to receipt generation.

Project Structure

src/
  ack-pay-tool.ts       # Main payment tool -- ADK FunctionTool wrapper
  ack-verify-tool.ts    # Receipt verification tool
  agent-config.ts       # Example ADK agent configuration
  demo.ts               # End-to-end demo simulation
docs/
  adk-vs-langchain.md   # Why both adapters are needed
.env.example            # Required environment variables

How ADK Tools Work

Google ADK uses FunctionDeclarations to describe tool capabilities to the Gemini model. The model decides when to call a tool based on the declaration's name, description, and parameter schema. This adapter maps ACK-Pay operations to that interface:

1. Declare the function schema (name, description, parameters with types)
2. Register it with the ADK agent's tool list
3. Handle the function call when the model invokes it
4. Return structured data back to the model as the function response

See src/ack-pay-tool.ts for a fully commented implementation.

---

Author

Sebastian Borjas — Founder & CEO, Lucilla Inc.

Pioneering pay-per-visit advertising on-chain — the first platform where businesses pay USDC rewards only when customers physically show up, verified by wearable sensors and GPS, settled transparently on-chain. No impressions, no clicks, no fraud. Real foot traffic, real payments, real proof.

Lucilla combines Circle Programmable Wallets, USDC on Base/Arc, ERC-8004 agent reputation, and W3C Verifiable Credentials to build the trust infrastructure for location-verified agentic commerce.

• Website: lucilla.app
• Email: s.borjas@lucilla.ca
• X: @sb_lucilla
• GitHub: @superbigroach

License

MIT