Forge for FastAPI (0.1.2 preview)

Forge adds agent traffic telemetry, x402 discovery context, and service feedback to an existing FastAPI app. It does not replace your facilitator, verify payments, or settle funds.

The package is named clawcash-forge, imported as forge_sdk. Install from PyPI:

python -m pip install clawcash-forge==0.1.2

Integrate

Keep your FastAPI routes, lifespan, payment middleware, and facilitator registration as they are. Wrap the finished app and export that wrapper to Uvicorn:

import os
from fastapi import FastAPI
from forge_sdk import init_forge

app = FastAPI()
# Register your existing routes and middleware here.
# This includes your existing x402 v1/v2 dispatch middleware.

application = init_forge(app, api_key=os.environ["FORGE_API_KEY"])

uvicorn server:application

app is still your FastAPI object. application is the outer ASGI app that Uvicorn serves. Do not serve server:app, which bypasses Forge. With Nginx, preserve payment-required, payment-response, and legacy x-payment-response headers. Keep ASGI lifespan enabled. For an ASGI host without lifespan, explicitly await application.start() and await application.close() in the host's lifecycle.

Create an API key for your service in Forge first. Initialization downloads only that service's registered resource routes. Non-business routes such as health checks are excluded.

What changes

• On registered x402 routes, captures status, duration, completion, agent type, client, and search query. Query strings, request bodies, and authorization/payment-signature headers are not exported wholesale.
• Adds agentType, agentTypeOther, client, and search_query query declarations to those OpenAPI operations. agentType and client are required in discovery. Runtime parsing remains optional and never rejects a merchant request for missing context. JSON agent_context is also accepted when the complete request body fits 3 KB.
• Appends feedback guidance to the existing main x-guidance, preserving merchant text. OpenAPI 3.0 and 3.1 are supported. Local response references are copied before extension. Ambiguous/composed/external response schemas are skipped.
• Adds a free GET /feedback questionnaire and POST /feedback submission route on the merchant's own origin. Invalid submissions explain the accepted schema so an agent can retry. The wrapper forwards submissions to Forge.
• Adds only feedback_id to eligible successful JSON objects, and advertises it in their response schema. The ID is a registered short-lived credential linked to the interaction. This preview uses the backend's pilot feedback policy, requesting feedback on every eligible response. It does not implement sampled grants.
• Adds the feedback invitation to the v2 payment-required resource description. Recognized Bazaar queryParams declarations receive context fields. Unknown/custom Bazaar schema layouts are preserved, not guessed.
• Reads settlement evidence from v2 payment-response and legacy x-payment-response. A 2xx status alone is never treated as payment. Network-qualified payer addresses from successful settlement evidence support Forge's global wallet-linked agent identity.

The legacy v1 challenge body is preserved byte for byte. Payment offers, recipients, assets, amounts, and opaque custom discovery fields are preserved. There is no monkey-patching of _x402_mw, _settle_v1, or facilitator functions. Do not describe this SDK as passive observation: the discovery and feedback changes above are intentional.

Custom settlement paths

If your custom v1 implementation emits a standard settlement response header, Forge can read it automatically. Otherwise report its actual outcome after settlement, inside the request task:

application.record_settlement(
    success=result.success,
    network="eip155:8453",  # or full Solana CAIP-2 network
    reference=result.transaction,
    payer=result.payer,
    protocol_version=1,
)

Pass amount in base units as a string and asset address if available. Never infer payment from a request signature or HTTP 200. This is SDK-reported evidence, not independent on-chain verification. Custom background tasks outside the request context must not use this method.

Failure and response behavior

Collector initialization failures warn and retry in the background. The merchant app remains available, but telemetry, schema enrichment, and feedback IDs are unavailable until initialization succeeds. Configuration errors (invalid collector URL, missing key, feedback route collision) raise at construction so they can be fixed before serving.

Telemetry uses a bounded in-memory queue. It is best-effort and may drop events during prolonged outages, overload, shutdown, or worker termination. Each worker owns its own queue. No disk spool is used. application.diagnostics reports readiness and drops.

Feedback link registration can add up to 1.5 seconds to eligible JSON responses. On failure the original response is returned. Streaming responses without a bounded Content-Length, responses larger than 64 KB, compressed/signed/cacheable responses, non-object JSON, and objects already containing reserved feedback fields are not modified. Bounded JSON responses may be buffered across chunks. Merchant exceptions and disconnect cancellation propagate normally.

The feedback endpoint is free and unauthenticated at the merchant boundary. Its token and answers are validated by Forge, which applies the existing feedback rules. Use your normal edge rate limits for this public endpoint.

application = init_forge(
    app,
    api_key=os.environ["FORGE_API_KEY"],
    api_url="https://dev-api.forge.clawca.sh",
    feedback_path="/feedback",  # choose another path if you already use this route
    verification=True,  # automatic temporary ownership proof
    feedback=True,  # false disables feedback route, IDs and invitations
    discovery=True,  # false leaves the served OpenAPI/discovery unchanged
    queue_size=1000,
)

No public origin is inferred from Host or forwarded headers. Feedback URLs are relative to the same merchant origin. Mount the wrapper at your API root. Register all merchant routes and custom OpenAPI generation before wrapping.

Preview scope

FastAPI/ASGI only, not Flask/WSGI. This version does not implement the Node SDK's sampled feedback grants, or adapters for every merchant-specific discovery schema. It does not fetch an invitation-specific questionnaire via GET token: public GET returns the fixed current form. Base and Solana settlement metadata are supported. Real funds and the client's private legacy compatibility module have not been exercised by tests.

Build and test

python -m pip install -e '.[test]'
python -m pytest
python -m build

The x402 integration test additionally requires x402==2.10.0 and cdp-sdk==1.43.0. Test deployments use FastAPI 0.136.0 and Uvicorn 0.44.0, with a mock collector/facilitator and no payment. contract.json is copied from the Node SDK's feedback/context definitions to keep the collector contract aligned.

Automatic ownership verification

Enabled by default. After initialization Forge obtains a temporary proof, adds X-Forge-Verification only to configured resource responses (including unpaid 402 responses), and polls the existing ownership API every 10 seconds. The backend makes an unpaid request to the registered public resource to verify control. Nginx must preserve this response header. No payment signature, API key, or expected proof is sent in that verification request.

Proof-bearing responses use Cache-Control: private, no-store. The SDK stops attaching the header after verification completes, when the proof expires, on authorization failure, and at shutdown. Already verified services receive no proof header, including after a restart. Existing merchant headers with the same name are preserved. Temporary collector failures do not block merchant requests. Pass verification=False to disable the handshake. application.verification.status exposes initializing, pending, complete, unavailable, or disabled.