Foinse

Get paid when AI uses your site.

Put a price on a page, API, or tool. A person or their agent pays in compute they already hold. You get paid in compute, with a receipt.

How it works

  1. Choose what to charge for. A useful page, API, or tool can have a price.
  2. Add the payment door. The SDK checks payment before giving access.
  3. Get paid. You receive compute and a receipt for every payment.

Hand it to your coding agent

Give your agent the Foinse repository and tell it to follow middleware/README.md. It has the setup steps and a runnable example.

For developers: the quickstart

This example charges for access to /premium. It runs offline in test mode; the repository explains how to connect live settlement.

Full example: middleware/examples/fastapi_fixture_app.py, with setup in middleware/README.md.

from fastapi import FastAPI
from toll_middleware import TollMiddleware, build_fixture_gate

world = build_fixture_gate("gate.sqlite3", toll_atomic=100)  # test mode, offline

app = FastAPI()

@app.get("/premium")
def premium():
    return {"message": "You paid the toll."}

app.add_middleware(
    TollMiddleware,
    gate=world.gate,  # live: your real QuotaKeyGateService
    toll_signing_key=world.toll_signing_key,
    toll_policy=world.toll_policy,
    public_base_url="https://your-site.example",
    protect=("/premium",),
)
Package and runtime status

The Python distribution is monorepo-only, requires Python 3.12 or newer, and imports the foinse core from this repository. Installing middleware/python alone is not a supported standalone deployment. The Node distribution is private and source-only, requires Node 18 or newer, and relays a running compatible gate; it does not embed the Python economics.

Door 1 middleware flow
  1. Mount the middleware before your protected route. An unpaid request receives a signed HTTP 402 challenge naming the route, price, provider options, surrender endpoint, and descriptor.
  2. The visitor POSTs its capped native provider key and the exact descriptor directly to that surrender endpoint with an idempotency key. Inline provider-key headers are retired and scrubbed.
  3. The historic Door 1 gate verifies before charging and returns a qtt1 bearer ticket.
  4. The visitor presents Authorization: Bearer qtt1.… to the protected route. Middleware sends it only to the gate's bodyless consume-ticket control POST; an exact 204 permits the local app to run once.

Tickets are short-lived, single-use, and bound to the exact resource path. Wrong-resource, expired, or replayed tickets receive a fresh 402. The ticket authorizes your paid route; it is not FK1, a settlement receipt, or raw compute.

Door 2 is a different access grant

Door 2 verifies by making the exact charge. Its committed payment movement event_id is the access grant, so this path does not need a separate qtt1 ticket. Do not invent a ticket requirement for Door 2 or describe the Door 1 middleware handshake as universal.

Account and ledger REST access

FK1 authenticates a Foinse account where the API specifies account access. It is not a native provider key and is not a universal toll-visitor credential. A quota key is a capped authorization around a native provider key, not a third account-key family beside native keys and FK1.

Reconciliation and errors

Responses are JSON. A settled line satisfies payer debit = recipient credit + protocol fee; the recipient's listed amount is not reduced by the processing toll. A line that fails conservation is not settled. Follow each endpoint's idempotency semantics rather than blindly retrying uncertain state-changing calls.

Versions and evidence

/v1 and /v2 are HTTP route families with different stability expectations; the version label alone does not define Door 1, Door 2, or an asset. Fixture gates exercise real middleware wiring and economic rules with deterministic local transports, not real provider quota. Live settlement requires the operator's real gate and provider transports.

Test first

Build against the sandbox, which is fixture-grade and labeled fixture throughout, before moving to live keys. See developers for integration selection and webhooks for settlement events.