Skip to content

altaga/Tollbit

Folders and files

NameName
Last commit message
Last commit date

Latest commit

ย 

History

13 Commits
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 

Repository files navigation

Tollbit โ€” Pay-per-call APIs and Intelligence using x402 and OWS

Turn any API into a monetized endpoint โ€” no API keys, just a wallet.

Tollbit Logo

Tollbit is a cutting-edge autonomous API monetization layer built entirely around the Open Wallet Standard (OWS) and the x402 payment protocol. It combines an autonomous AI agent system with local-first, policy-gated wallet storage. By bridging foundation models with decentralized micropayments, Tollbit unlocks zero-account access, putting highly-capable Agents behind seamless pay-per-call endpoints.

๐ŸŒ Live Web DApp | ๐ŸŽฅ Video Demo | ๐Ÿ“ฑ App Code | ๐Ÿ›ก๏ธ OWS Server Code


๐Ÿง  Problem

Using APIs today means:

accounts API keys billing setup

This creates friction โ€” especially for AI agents that need to act autonomously.

๐Ÿ’ก Solution

Tollbit replaces API keys with micropayments using HTTP 402 (Payment Required).

Instead of authenticating with credentials, users simply pay per request.

๐Ÿš€ Why this matters

Tollbit enables a new model for the internet:

Payment as access control

This unlocks the agent economy, where AI systems can:

discover services pay dynamically execute tasks autonomously

โœจ Key Features

  • Zero-Account Access: Users don't need subscriptions; they pay per prompt using standard wallet setups and the x402 payment protocol.
  • Autonomous Economics: Agents cover their own execution costs via dynamic routing and micro-transactions depending on complexity.
  • Secure Treasury: Uses an isolated OWS server to manage keys safelyโ€”no private keys touch the frontend.
  • Base Sepolia Faucet: Onboard users quickly with an intelligent testnet USDC faucet driven by OWS server-side signing.
  • AI Tooling: Langchain-powered agents natively browse the web, format responses, and route intelligently to different AWS Bedrock models.

OWS Architecture

๐ŸŽฏ Using the Live App (Walkthrough)

You can experience the complete autonomous economy directly in your browser. No complicated local setup or private key management is required. The entire application runs smoothly on the Base Sepolia testnet.

๐Ÿ‘‰ Launch DApp: https://tollbit.expo.app

Step 1: Initializing the Session

When you first open the web application, you are greeted by the Geppetto chat interface. Because Tollbit is an entirely zero-account ecosystem, there are no signup screens, usernames, or passwords. Your identity and session are intrinsically tied to your wallet, immediately establishing a seamless connection to our AI models. First connect your wallet.

Step 1: Initializing

Step 2: Claiming Testnet Gas (USDC Faucet)

If you are visiting for the first time and your wallet lacks the necessary USDC for micro-payments, the platform will automatically detect your balance and prompt you to utilize the integrated Tollbit Faucet.

  1. Locate the "Get Testnet USDC" or "Get USDC Drop" button dynamically rendered in the UI (this button gracefully disappears once your wallet is funded).
  2. Click the button to request your drop.
  3. What happens under the hood: The request hits our backend where the Tollbit OWS Server resolves its hardware-isolated Faucet Wallet. It then signs a live transaction via the x-api-key and sends 0.1 USDC (Base Sepolia) directly to your address. This is performed entirely securely server-side.
  4. Your balance inside the application instantly reflects the drop. You are now fueled to begin the AI economy!

Step 2: Claiming Testnet Gas Step 3: Claiming Testnet Gas Step 4: Claiming Testnet Gas

Step 3: Engaging with the AI (Tiered Pricing)

Tollbit operates an intelligent tiered AI agent called "Geppetto." You have granular control over your queries, and can select between different complexity modesโ€”each strictly backed by a micro-transaction proportionate to the compute used:

  • Standard Request ($0.001): Ideal for basic reasoning, generated natively by Llama 3 or Amazon Nova.
  • Advanced Request with Tools ($0.003): The agent accesses a Langchain duckduckgo_search tool, allowing it to autonomously browse the real-time internet to answer factual questions or ingest news.
  1. Type a question into the chat (e.g., "What is the Open Wallet Standard?" or "Search the web for the latest tech news").
  2. Select whether to enable Tools / Web Search via the interface dropdowns.
  3. Hit Send.

Step 5: Engaging with the AI Step 7: Engaging with the AI

Step 4: The x402 Payment Intercept In Action

When you send a prompt, your request encounters the x402 Payment Required protocol. Tollbit uses an advanced decentralized gateway rather than traditional web guards:

  1. Pre-flight & Rejection: The /api/basic or /api/advance endpoint intercepts your request. Before executing inference, the server replies with an HTTP 402 Payment Required status, detailing the specific cost (e.g., exactly $0.003 USDC payable to our global Agent Address) along with a traceId.
  2. Transaction Signing: Your local application client handles this standard gracefully, prompting an EVM transaction on Base Sepolia matching the explicit requested parameters.
  3. Execution Unlocked: The micro-transaction is verified. Your payload is automatically re-submitted with cryptographic proof, the endpoint unlocks, and the AWS Bedrock environment processes your prompt.

Step 8: Engaging with the AI

Step 5: Validating Agent Responses

After the payment mathematically settles, the AI agent's reasoning streams directly into your chat interface. By leveraging blockchain explorers mapped to your transaction history, you can transparently trace the exact Base Sepolia micropayments. The Geppetto economy is therefore self-sustained natively on-chain without any opaque centralized accounting!

Step 8: Engaging with the AI


๐Ÿš€ System Architecture

Tollbit is built entirely from scratch to leverage advanced web3 infrastructure for an autonomous economy. The repository is split into two primary environments:

  • tollbit/: The frontend web application (built on React Native/Expo) with built-in API routes (powered by Hono) for serving agent responses.
  • ows-server/: An Express-based Open Wallet Standard (OWS) reference server handling the actual signing of EVM transactions.

Core Technologies

  • x402 Protocol: The backbone of Tollbit's API economy. It intercepts HTTP requests to our agent endpoints and demands cryptographically verifiable micropayment proofs before executing the prompt.
  • Open Wallet Standard (OWS): The local-first keystore and policy manager. Instead of passing around private keys, Tollbit uses the OWS server to issue scoped API keys that respect spending budgets and specific chain allowlists.
  • Langchain (AI Agent): The framework operating "Geppetto". It allows Tollbit to orchestrate complex reasoning, coordinate multi-step workflows like internet scraping, and wrap results into HTTP outputs.
  • Amazon Bedrock: Provides foundational models (Llama 3 and Amazon Nova) for parsing and generation, scaling based on the exact tier requested by the user.

๐Ÿ’ฒ x402 Micropayments (Technical Details)

A key component of our application is the utilization of the x402 HTTP status code standard, largely due to its seamless drop-in integration with REST APIs. We enforce x402 as the primary gatekeeper for prompt execution and monetization.

Dynamic Payment Routing

For the use case of payments, x402 offers a native way to block computation until the transaction is settled. When a user requests an AI generation, the Geppetto endpoint checks for an exact EVM payment matched to the AI's address.

This dynamic price routing enables us to facilitate variable costs depending on if the user invokes simple logic ($0.001) or requests an external Web Search tool ($0.003), ensuring the agent always covers its compute costs.

The complete technical implementation for this section can be found here: Code


๐Ÿ› ๏ธ OWS Server API Specification

The ows-server is a reference implementation of the Open Wallet Standard (OWS). It acts as a secure, local-first vault that isolates the master secret while providing policy-gated access to AI agents.

๐Ÿ” Security & Spending Policies

Instead of complex smart contracts, Tollbit uses OWS policyIds to cap agent expenditures. This prevents runaway AI loops from draining wallets by issuing scoped API keys with strict daily spend limits and chain allowlists.

Core Endpoints

Method Endpoint Auth Description
POST /api/wallets Admin Initializes a new OWS-compatible wallet.
POST /api/wallets/:name/api-keys Admin Generates a policy-gated API token for an agent.
POST /api/wallets/:name/keys Admin Fetches the addresses / public keys associated with a wallet.
POST /api/wallets/:name/sign Agent Signs a message for a specific chain using the API token.
POST /api/wallets/:name/sign-transaction Agent Signs a hex-encoded transaction for a specific chain using the API token.

๐Ÿ› ๏ธ Key Implementation Highlights:

  • Scoped API Keys: Uses API tokens as the primary authentication and decryption mechanism for agent-based access.
// Secure Message Signing via OWS
const result = signMessage(walletName, chain, message, apiToken);

The complete technical implementation for this section can be found here: Code


โ›ฝ USDC Faucet & OWS Integration

Tollbit includes a built-in USDC Faucet designed to onboard new users by providing a small amount of "gas" and test funds (0.1 USDC on Base Sepolia). This feature serves as a primary demonstration of how Tollbit integrates with the Open Wallet Standard (OWS) for secure, server-side transaction signing.

๐Ÿ—๏ธ Faucet Architecture

The faucet operates as a bridge between the user's frontend and the OWS-managed treasury.

  1. Trigger: User clicks "Get USDC Drop" in the Tollbit UI.
  2. Request: Frontend calls the /api/faucet endpoint with the user's EVM address.
  3. OWS Signature Flow:
    • The server resolves the Faucet wallet address from the OWS registry.
    • An unsigned EIP-1559 transaction is constructed.
    • OWS signs the transaction using the hardware-isolated keys for the Faucet wallet.
  4. Broadcast: The server receives the signature, assembles the raw transaction, and broadcasts it to Base Sepolia.

๐Ÿ› ๏ธ Key Implementation Highlights:

  • Server-Side Signing: The faucet requests a cryptographic signature from the OWS server using a managed API key.
// Requesting signature from OWS Server
const signResponse = await fetch(`${OWS_BASE_URL}/api/wallets/${FAUCET_WALLET_NAME}/sign-transaction`, {
  method: "POST",
  headers: { "x-api-key": FAUCET_API_KEY },
  body: JSON.stringify({ chain: "evm", txHex }),
});

The complete technical implementation for this section can be found here: Code


๐Ÿค– AI Agent (Geppetto)

The Tollbit platform incorporates an AI agent named Geppetto, built using the Langchain framework. Geppetto is capable of interpreting multi-step queries, generating robust textual outputs, and actively pulling real-time internet data.

Agent Setup and Tools

Geppetto utilizes specialized tools injected directly into AWS Bedrock conversational flows to expand its capabilities.

  • weather_tool: Provides real-time weather data and forecasts for specified locations.

Weather Tool

  • duckduckgo_search: Facilitates real-time external data scraping when factual references and internet browsing are required.

DuckDuckGo Search

  • finance_tool: Fetches up-to-date market data, stock prices, and financial technical analysis.

Finance Tool

The complete technical implementation for this section can be found here: Code

Special Method: Payment Protocol Pre-Flight

To ensure full transparency into the x402 payment lifecycle and proactively protect against unbilled AI generations, Tollbit implements a robust custom telemetry middleware. This wrapper dynamically resolves unique Trace-Ids, intercepts edge-case node crashes or provider timeouts, and gracefully formats them into unified 401 client signals for the wallet extension.

๐Ÿ› ๏ธ Key Implementation Highlights:

  • Trace-ID Resolution: Ensures log correlation across asynchronous payment tiers.
const traceId = c.req.header("X-Geppetto-Trace-Id") || crypto.randomUUID();
c.header("X-Geppetto-Trace-Id", traceId);
  • Error Hardening: Automatically detects cold starts and provides retry hints to the client.
const isInitError = err.message.includes("initialize");
return c.json({ error: clientMsg, traceId, retry: isInitError }, 401);

By wrapping all agent generation inside productionPaymentMiddleware, we guarantee zero revenue leakage, ensure exact metering of token usage, and maintain highly verbose system dashboard integrations for complete observability.

The complete technical implementation for this section can be found here: Code


Built for the Open Wallet Standard Hackathon

About

No description, website, or topics provided.

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

 
 
 

Contributors