openapi: 3.1.0
info:
  title: Ibanforge BIC API
  version: 1.4.3
  contact:
    url: https://ibanforge.com
  description: 'Operations tagged BIC across 2 of this provider''s published API definitions: ibanforge-bic-api-openapi.yml, ibanforge-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.ibanforge.com
  description: Production
- url: http://localhost:3000
  description: Local development
tags:
- name: BIC
  description: BIC/SWIFT lookup endpoints (paid via x402)
paths:
  /v1/bic/{code}:
    get:
      operationId: lookupBIC
      summary: Lookup a BIC/SWIFT code
      description: Returns institution details for a BIC/SWIFT code (8 or 11 characters). Costs 0.003 USDC via x402.
      tags:
      - BIC
      security:
      - x402Payment: []
      - apiKey: []
      parameters:
      - name: code
        in: path
        required: true
        description: BIC/SWIFT code (8 or 11 characters)
        schema:
          type: string
          minLength: 8
          maxLength: 11
          example: UBSWCHZH
      responses:
        '200':
          description: BIC lookup result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BICLookupResult'
        '400':
          description: Invalid BIC format
        '402':
          description: Payment required (x402)
    servers:
    - url: https://api.ibanforge.com
      description: Production
    - url: http://localhost:3000
      description: Local development
components:
  schemas:
    BICLookupResult:
      type: object
      required:
      - bic
      - bic8
      - bic11
      - found
      - valid_format
      - institution
      - country
      - city
      - branch_code
      - branch_info
      - lei
      - lei_status
      - is_test_bic
      - source
      - cost_usdc
      properties:
        bic:
          type: string
          example: UBSWCHZH
        bic8:
          type: string
          example: UBSWCHZH
        bic11:
          type: string
          example: UBSWCHZHXXX
        found:
          type: boolean
        valid_format:
          type: boolean
        institution:
          type: string
          nullable: true
          example: UBS AG
        country:
          type: object
          required:
          - code
          - name
          properties:
            code:
              type: string
              example: CH
            name:
              type: string
              example: Switzerland
        city:
          type: string
          nullable: true
        address:
          type: object
          description: Registered head-office address (present when available — GLEIF or directory sourced)
          properties:
            type:
              type: string
              example: registered
            street:
              type: string
              nullable: true
              example: Bahnhofstrasse 45
            post_code:
              type: string
              nullable: true
              example: '8001'
            region:
              type: string
              nullable: true
              example: CH-ZH
            city:
              type: string
              nullable: true
              example: Zurich
            country:
              type: string
              example: CH
            romanized:
              type: string
              nullable: true
            romanization:
              type: string
              example: original_latin
            source:
              type: string
              example: GLEIF
            language:
              type: string
              example: en
            as_of:
              type: string
              format: date
        address_available:
          type: boolean
        branch_code:
          type: string
          example: XXX
        branch_info:
          type: string
          nullable: true
        lei:
          type: string
          nullable: true
        lei_status:
          type: string
          nullable: true
        is_test_bic:
          type: boolean
        source:
          type: string
          nullable: true
        note:
          type: string
        cost_usdc:
          type: number
          example: 0.003
        processing_ms:
          type: number
    BICLookupResult_2:
      type: object
      required:
      - bic
      - bic8
      - bic11
      - found
      - valid_format
      - institution
      - country
      - city
      - branch_code
      - branch_info
      - lei
      - lei_status
      - is_test_bic
      - source
      - cost_usdc
      properties:
        bic:
          type: string
          example: UBSWCHZH
        bic8:
          type: string
          example: UBSWCHZH
        bic11:
          type: string
          example: UBSWCHZHXXX
        found:
          type: boolean
        valid_format:
          type: boolean
        institution:
          type:
          - string
          - 'null'
          example: UBS AG
        country:
          type: object
          required:
          - code
          - name
          properties:
            code:
              type: string
              example: CH
            name:
              type: string
              example: Switzerland
        city:
          type:
          - string
          - 'null'
        address:
          type: object
          description: Registered head-office address (present when available — GLEIF or directory sourced)
          properties:
            type:
              type: string
              example: registered
            street:
              type:
              - string
              - 'null'
              example: Bahnhofstrasse 45
            post_code:
              type:
              - string
              - 'null'
              example: '8001'
            region:
              type:
              - string
              - 'null'
              example: CH-ZH
            city:
              type:
              - string
              - 'null'
              example: Zurich
            country:
              type: string
              example: CH
            romanized:
              type:
              - string
              - 'null'
            romanization:
              type: string
              example: original_latin
            source:
              type: string
              example: GLEIF
            language:
              type: string
              example: en
            as_of:
              type: string
              format: date
        address_available:
          type: boolean
        branch_code:
          type: string
          example: XXX
        branch_info:
          type:
          - string
          - 'null'
        lei:
          type:
          - string
          - 'null'
        lei_status:
          type:
          - string
          - 'null'
        is_test_bic:
          type: boolean
        source:
          type:
          - string
          - 'null'
        note:
          type: string
        cost_usdc:
          type: number
          example: 0.003
        processing_ms:
          type: number
  securitySchemes:
    x402Payment:
      type: apiKey
      in: header
      name: X-Payment
      description: x402 USDC micropayment token
    apiKey:
      type: http
      scheme: bearer
      description: API key (Bearer ifk_xxx) — 200 free requests/month, or custom quota for paid keys
externalDocs:
  description: Agent-oriented overview (llms.txt) with copy-paste examples
  url: https://api.ibanforge.com/llms.txt
x-refined-from:
- ibanforge-bic-api-openapi.yml
- ibanforge-openapi.yml