Build payments and compute into your app.
Use these JSON APIs for account, market, toll, and card operations. If you want to accept payment on your own site, start with the Toll SDK instead.
Before your first request
- Choose the right integration. Use the SDK to get paid for your route; use account APIs to transfer balances or spend compute.
- Use the right credential. Account routes use FK1. Native provider keys and quota keys belong to the payer payment flow.
- Check the response status. Fixture data is labeled fixture, and a route’s presence does not prove every operation is live.
Account authentication
Where an endpoint specifies Foinse account authentication, send FK1 in the Authorization header:
Authorization: Bearer <FK1>FK1 is Foinse-issued access to one Foinse account. Do not substitute a native provider key or capped quota key on account routes. There is no separate sandbox host; fixture data is labeled in the response.
Route reference
The Foinse site reverse-proxies the following route families to the backend. Requests and responses are JSON.
Market routes
The /market family exposes provider-denominated compute inventory and the ledger views around it. A listing or catalog entry is not a new asset family; reserve lots retain backing and provenance beneath pooled available inventory.
GET /market/catalog
Returns catalog entries describing provider denomination, offered capacity, and evidence or availability status. Native AI labs do not need to list or endorse holder-supplied bearer value.
GET /market/listings
Returns listing records. Any price or discount parameter is market and route data, not a universal 0.8x face rule or guaranteed 20% discount.
/market/purchases
Purchase operations convert the stated payment into the resulting provider-denominated bearer position. The seller receives the full listed subtotal; the buyer pays the separately disclosed processing toll on top. Reconcile the actual response rather than assuming an unpublished rate or direction.
/market/earnings
Returns settled earnings attributable to the relevant account, supplier, or seller, with per-line evidence labels where provided.
/market/pool and /market/pool*
Reads and operations against pooled available inventory within a provider denomination. A buyer acquires from the pool rather than selecting a named seller; the pool is not a house balance and does not make unlike provider denominations fungible.
Toll routes: /v1 and /v2
The /v1 and /v2 families price and post toll movements. The HTTP version does not by itself identify Door 1, Door 2, or a credential type. Door 1 verifies before charging and uses a qtt1 route-access ticket; Door 2 verifies by charging and uses the committed movement event_id as its access grant. Read the endpoint's actual contract rather than inferring a universal ticket or key flow.
Compute-token movement has an initial 5% processing toll. External fiat/crypto ramps use the separately disclosed initial rate family currently associated with 5% for Base USDC and 5.5% for card. Rates are provisional parameters; each receipt should name the movement, rail, payer, and amount.
Card rail: /card-rail
The /card-rail family handles card-funded movement where available. Card funding is an external entry relationship, not a new monetary asset or a denial of provider-compute backing. The resulting ledger position follows the same conservation and evidence rules. No fixed 0.8x conversion rule is part of the public API contract.
Errors
Errors are JSON objects with an error code and a message. A failed movement settles nothing: the ledger either posts the full conserved settlement or posts no settlement. Follow endpoint-specific idempotency rules before retrying uncertain state-changing calls.
Conservation
Every settlement response can be checked as payer debit = recipient credit + protocol fee. If a response cannot be reconciled against its actual lines, treat it as an error and do not book it.