IBANforge Credits API
Prepaid credit bundles — pay once in USDC (x402), get an API key with N credits; batch validation debits 1 credit per IBAN
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/ibanforge-credits-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: IBANforge Credits API
version: 1.8.0
description: IBANforge checks the bank behind an IBAN before you pay.
contact:
name: IBANforge support
url: https://github.com/cammac-creator/ibanforge/issues
email: support@ibanforge.com
servers:
- url: https://api.ibanforge.com
description: Production
- url: http://localhost:3000
description: Local development
tags:
- name: Credits
description: Prepaid credit bundles — pay once in USDC (x402), get an API key with N credits; batch validation debits 1 credit per IBAN
paths:
/v1/credits/balance:
get:
operationId: getCreditBalance
summary: Read the remaining credits of the presented key
description: 'For a key with prepaid credits: credits_remaining, credits_total (everything ever bought on the key, recharges included), credits_used and the top-up endpoints. For a key without credits the answer is type: "subscription" with a pointer to GET /v1/keys/usage. On every key, `allowance` gives the allowance of the key (null on a key born of a purchase, which has none), `billing_order` is "allowance_then_credits" on a key that holds both, and `topup` carries the card links that recharge THIS key. When the credits of a key born of a purchase run out, billed routes answer 402 with cause.reason "credits_exhausted", the same links, and X-Credits-Topup-Url (the 1,000-credit one). Authentication is the key itself, in any of the three places every billed route accepts: Authorization: Bearer, X-API-Key, or ?api_key=.'
tags:
- Credits
security:
- apiKey: []
responses:
'200':
description: type ("credit_bundle" or "subscription"), key_prefix, allowance, topup, and, for a key with credits, credits_remaining, credits_total, credits_used, topup_endpoints and, when it also holds an allowance, billing_order.
'401':
description: Missing or invalid API key ("missing_key" / "invalid_key")
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'429':
description: Rate limit exceeded. Applied globally by the server, so any operation can answer it. Honour the Retry-After header; see https://api.ibanforge.com/rate-limits.yml
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
/v1/credits/bundles:
get:
operationId: listCreditBundles
summary: List prepaid credit bundles (free)
description: 'Lists the available prepaid credit bundles with prices. Buy a bundle once via x402 (POST /v1/credits/buy/{bundle}) and receive an API key preloaded with N credits (1 credit = 1 validation/lookup; batch validation debits 1 credit per IBAN) — credits never expire. Card checkout is also available at https://ibanforge.com/pricing. The `subscription` object lists the flat monthly alternative (Pro: 10,000 requests/month by card).'
tags:
- Credits
security: []
responses:
'200':
description: Available bundles
content:
application/json:
schema:
type: object
required:
- bundles
properties:
bundles:
type: array
items:
type: object
properties:
slug:
type: string
enum:
- 1k
- 5k
- 25k
credits:
type: integer
example: 1000
price_usdc:
type: number
example: 5
price_per_call_usdc:
type: number
example: 0.005
buy_endpoint:
type: string
example: POST /v1/credits/buy/1k
payment_method:
type: string
example: x402 USDC on Base mainnet
documentation:
type: string
subscription:
type: object
description: 'The recurring alternative to packs: a flat monthly plan paid by card, key delivered by e-mail after checkout.'
properties:
plan:
type: string
example: pro
monthly_requests:
type: integer
example: 10000
price_usd_per_month:
type: number
example: 29
checkout:
type: string
format: uri
payment_method:
type: string
example: card (Stripe)
'429':
description: Rate limit exceeded. Honour the Retry-After header; see https://api.ibanforge.com/rate-limits.yml
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
/v1/credits/buy/{bundle}:
post:
operationId: buyCreditBundle
summary: Buy a prepaid credit bundle (x402, USDC)
description: 'Pay once via x402 (USDC on Base). Present the API key you already hold (as on any billed route) and the credits land on THAT key: the answer carries same_key: true, api_key echoes the key you presented, and nothing changes in your integration; presenting the key costs no request, and a purchase never grants a free allowance. Without a key (or with an invalid one), you receive a fresh API key preloaded with the bundle credits, recoverable once at recovery_url if the response is lost. Nothing is credited or activated before the payment settles. Bundles: 1k = $4, 5k = $20, 25k = $80. Credits never expire. Optionally pass {"email": "..."} in the body: it becomes the contact of a NEW key; on a recharge it is only kept as the payer''s contact, never attached to the key. Check the balance with GET /v1/credits/balance.'
tags:
- Credits
security:
- x402Payment: []
parameters:
- name: bundle
in: path
required: true
description: Bundle slug
schema:
type: string
enum:
- 1k
- 5k
- 25k
example: 1k
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
email:
type: string
format: email
description: Optional — attach the key to an email address
responses:
'200':
description: 'This payment was already recorded and its purchase was credited or minted (a replayed request): idempotent: true, nothing credited or minted twice. recovery_url only while the key it minted is active and still recoverable'
'201':
description: 'The key you presented was recharged (same_key: true), or a new credit key was minted (shown only once: save it)'
content:
application/json:
schema:
type: object
required:
- api_key
- credits
- bundle
properties:
api_key:
type: string
description: 'Full API key: the key you presented on a recharge, echoed as sent; a new key otherwise, shown only once'
same_key:
type: boolean
description: true when the credits landed on the key you presented
recharged:
type: boolean
key_prefix:
type: string
credits:
type: integer
example: 1000
description: The credits of this bundle
credits_added:
type: integer
example: 1000
description: 'On a recharge: the credits added to the key'
bundle:
type: string
example: 1k
price_paid_usdc:
type: number
example: 4
price_per_call_usdc:
type: number
example: 0.004
first_call:
type: string
description: 'On a new key: a curl command that works with it'
usage_hint:
type: string
balance_endpoint:
type: string
example: GET /v1/credits/balance
recovery_url:
type: string
format: uri
description: 'On a new key: fetch it once if this response is lost'
recovery_note:
type: string
note:
type: string
description: 'Present when the key you sent was invalid or revoked: the pack is on a NEW key'
message:
type: string
'402':
description: 'Payment required (x402): bundle price in USDC. A settlement the facilitator REFUSED ends here too (an explicit reason, nothing broadcast), and nothing is credited'
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'404':
description: Unknown bundle slug — choose 1k, 5k or 25k
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'409':
description: 'This payment was already seen and its purchase was not credited: "payment_pending" (its settlement is not confirmed yet: do NOT pay again), "payment_refused" (refused when it was settled: sign a new payment), "payment_reversed" (refunded or disputed) or "payment_already_used". Nothing is settled again'
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'413':
description: Request body exceeds 256 KB. Applied globally to every operation that takes a body, before routing and before payment, so nothing is charged. Split the input (batch validation accepts up to 100 IBANs per call).
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'429':
description: Rate limit exceeded. Applied globally by the server, so any operation can answer it. Honour the Retry-After header; see https://api.ibanforge.com/rate-limits.yml
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'502':
description: 'settlement_unconfirmed: the outcome of the settlement is unknown (settlement.cause: "timeout", "settlement_pending" when the transfer was broadcast but not confirmed yet, or "facilitator_error" for a network error or a 5xx). The payment may have settled: do NOT pay again. The purchase stays pending and is reconciled by hand once the transfer is confirmed on-chain; settlement.transaction carries the transaction hash when the facilitator returned one'
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
components:
schemas:
ApiError:
type: object
required:
- error
- message
additionalProperties: true
properties:
error:
type: string
description: 'Stable machine-readable token in snake_case, e.g. "invalid_json", "invalid_request", "batch_too_large", "payment_required", "payload_too_large", "rate_limit_exceeded". Branch on this, never on `message`. An invalid IBAN is not an ApiError: validation answers 200 with `valid: false`.'
example: batch_too_large
message:
type: string
description: Human-readable sentence explaining the failure. Wording may change; the token above will not.
example: Maximum 100 IBANs per batch request
securitySchemes:
x402Payment:
type: apiKey
in: header
name: PAYMENT-SIGNATURE
description: x402 USDC micropayment signature (protocol v2). Clients holding v1 payment requirements may send the same signature as X-Payment; both are accepted.
apiKey:
type: http
scheme: bearer
description: API key (Bearer ifk_xxx) — 25 free requests/month without an email address, 200 a month once claimed, or a custom quota for paid keys
accountSession:
type: apiKey
in: cookie
name: ibanforge_account
description: 'Session of the account page, set by POST /v1/account/session: HttpOnly, Secure, SameSite=Strict, Path=/v1/account, 7 days from sign-in. Read-only: it opens no paid route and no route that acts on a key.'
externalDocs:
description: Agent-oriented overview (llms.txt) with copy-paste examples
url: https://api.ibanforge.com/llms.txt