@clawcash/forge

The fastest way to make an existing SaaS/API app agent-native.

Define a paid action on top of your backend and run an outbound worker that fulfills jobs from the ClawCash gateway. Agents discover, pay (x402/USDC), and call the gateway — your app adds no routes, no middleware, and no public agent surface. Zero runtime dependencies.

Published under the ClawCash npm org.

agent  ->  gateway.clawca.sh/<handle>/<action>   (x402)
               | job queued
worker ->  claims job (outbound long-poll), runs execute(), posts result
               |
agent  <-  result, same request

Install

npm install @clawcash/forge

Quick start (worker mode — the default)

One self-contained file. Your web server is not touched.

// src/forge/agent-worker.ts
import { defineAgentService, forgeWorker } from "@clawcash/forge";

const removeBackground = defineAgentService({
  name: "remove_background",
  description: "Remove the background from an image.",
  input: { imageUrl: "url" },
  output: { resultUrl: "url" },
  payment: { amount: "0.10", currency: "USDC", protocols: ["x402"] },
  async execute({ imageUrl }) {
    // call the API your product already has — loopback, hosted, or direct import
    const res = await fetch("http://127.0.0.1:3000/api/remove", {
      method: "POST",
      headers: { "content-type": "application/json" },
      body: JSON.stringify({ imageUrl }),
    });
    const data = await res.json();
    return { resultUrl: data.resultUrl };
  },
});

forgeWorker({ services: [removeBackground], handle: "my-app" });

FORGE_API_KEY=fk_live_... node --import tsx src/forge/agent-worker.ts
# [forge-worker] my-app polling https://gateway.clawca.sh/jobs/claim ...

Env: FORGE_API_KEY (required, from the Forge dashboard), FORGE_HANDLE (if not passed as an option), GATEWAY_URL (optional override).

The worker makes outbound requests only. It runs behind NAT, on localhost, in a private subnet — anywhere with outbound HTTPS. Polling doubles as the merchant heartbeat.

If the handle is not registered yet (claim returns 404), the worker keeps waiting — deploy first, then press Go live on the Forge dashboard. Only a bad FORGE_API_KEY (401) stops the worker.

Fetch-handler mode (inbound alternative)

For gateway-push deployments, createForgeHandler(services) returns a web-standard (Request) => Promise<Response> serving /forge/health, /forge/status, /.well-known/clawcash.json, and POST /forge/fulfill/{action} (gated by FORGE_API_KEY). Mounts natively in Next.js route handlers, Hono, Bun, Deno; createForgeRequestMatcher returns null on unmatched routes for fall-through mounting.

API

| Export | Purpose | |--------|---------| | defineAgentService | Declare name, schemas, payment, and execute | | forgeWorker | Outbound worker: claim paid jobs, execute, report results | | createForgeHandler / createForgeRequestMatcher | Web-standard inbound fulfillment surface | | validateInput / checkType | Schema validation | | waitUntil / context.waitUntil | Poll until a job completes inside execute | | getForgeApiKey / forgeGatewayLoopbackHeaders | Auth helpers for fulfillment traffic |

Build

npm install
npm run build