Skip to main content

​
Payment Options

There are four public payment modes you can reason about safely.

​
1. Managed agent wallet

Best when you want the easiest operational flow.
  • use an existing managed agent wallet
  • generate a connect string or gateway-safe credential bundle for it
  • let the wallet pay for gateway calls within the configured limits
Creating a new managed (custodial) wallet is currently unavailable: the legacy dashboard service that derived and encrypted wallet keys has been retired, and creation returns custodial_wallet_creation_unavailable. Existing managed wallets still settle calls, and connect tokens can still be minted for them. To provision a wallet yourself today, run the local stdio MCP package and create a local wallet, or use raw x402 mode with your own payer.
If you are using the local Apiosk MCP package, import that connect string through apiosk_get_started so the package can save it locally and verify the setup with a first call.

​
2. Raw x402 proof flow

Best when you want direct control of the payer.
  • call the gateway without proof
  • receive HTTP 402
  • sign the payment challenge with your own payer
  • retry with x-payment
The 402 may list several networks, Base plus Polygon and Arbitrum where the facilitator supports them, one accepts entry per network the API is configured for, all at the same USDC price. Pick the entry you can pay on and name that network in your payment payload; a Base entry is always included as fallback. See Multi-chain Settlement. Use this when you already have your own payment orchestration or want the most explicit proof path.

​
3. SEPA Direct Debit rail

Best when the buyer is an EU business that prefers bank-side settlement instead of on-chain USDC.
  • sign a SEPA mandate once via the buyer portal
  • the gateway debits the buyer’s IBAN through Mollie for paid calls covered by the mandate
  • pricing is a monthly subscription tier: Apiosk takes no per-transaction percentage on SEPA
  • per-call debits are batched in a settlement ledger and reconciled on the bank side
Use this when the buyer needs euro-denominated settlement, an IBAN paper trail, or already has a Mollie relationship. You can pin the rail per request with X-Apiosk-Rail: sepa. If you omit the header, the gateway auto-selects the cheapest viable rail and falls back when the preferred rail is unavailable.

​
4. Unpaid routes

Some routes can be configured as free. In those cases the gateway does not require payment before forwarding the request.

​
Recommendation

  • use managed wallet mode for operator dashboards and repeated agent workflows
  • use raw x402 mode for protocol-level integrations and explicit payment control
  • use the SEPA rail when the buyer needs euro-denominated bank settlement
  • use unpaid mode only when the listing or endpoint is intentionally public
  • for local MCP installs, start with apiosk_get_started and let it tell you whether you are ready or still need funding