Bitrefill Account API

openapi: 3.2.0
info:
  title: Bitrefill x402 Account API
  description: Buy gift cards, eSIMs, mobile top-ups and prepaid cards with USDC via x402. 10,000+ brands across 180+ countries. No API keys or Bitrefill account required — wallet payment and optional SIWX sign-in only.
  version: 1.0.0
  contact:
    name: Bitrefill
    email: miguelmorales@bitrefill.com
  x-guidance: 'Agent checkout flow: search (gift-cards/esims/topups) → GET /x402/products/detail?slug=… → POST /x402/invoice/create with items → POST /x402/invoice/pay with invoice_id → GET /x402/invoice/status?invoice_id=… (SIWX with the paying wallet to retrieve codes). Pay each micro-fee via x402 (PAYMENT-SIGNATURE header) or mint a session at POST /x402/connect (SIGN-IN-WITH-X) and send X-Access-Token on later calls. Full guide: bitrefill.com/agents/SKILL.md'
servers:
- url: https://api.bitrefill.com
tags:
- name: Account
  description: Orders and eSIMs for the paying wallet (SIWX).
paths:
  /x402/connect:
    post:
      operationId: connectWallet
      summary: Mint a session token (SIWX)
      description: Sign the sign-in-with-x challenge once to obtain a reusable X-Access-Token. No micro-fee; SIWX signature is the authentication.
      tags:
      - Account
      parameters:
      - name: SIGN-IN-WITH-X
        in: header
        required: false
        description: Base64 JSON of decomposed SIWE fields (domain, address, uri, version, chainId, type, nonce, issuedAt, signature). Required on SIWX-only routes when no X-Access-Token is present.
        schema:
          type: string
      responses:
        '200':
          description: token, token_header (X-Access-Token), expires_in, and next_step to GET /x402/my/orders.
        '402':
          description: Authentication Required — sign-in-with-x challenge in extensions["sign-in-with-x"] (SIGN-IN-WITH-X header on retry).
        '500':
          description: Unexpected server error.
  /x402/my/orders:
    get:
      operationId: listMyOrders
      summary: List orders for the signed-in wallet
      description: Requires SIWX or X-Access-Token from the wallet that paid invoices. Returns empty list if the wallet has no agent user yet.
      tags:
      - Account
      parameters:
      - name: start
        in: query
        required: false
        description: Pagination offset (default 0).
        schema:
          type: integer
          minimum: 0
      - name: limit
        in: query
        required: false
        description: Page size (default 50, max 100).
        schema:
          type: integer
          minimum: 1
          maximum: 100
      - name: X-Access-Token
        in: header
        required: false
        description: Session JWT from POST /x402/connect. Bypasses micro-fees and SIWX re-signing until expiry.
        schema:
          type: string
      - name: SIGN-IN-WITH-X
        in: header
        required: false
        description: Base64 JSON of decomposed SIWE fields (domain, address, uri, version, chainId, type, nonce, issuedAt, signature). Required on SIWX-only routes when no X-Access-Token is present.
        schema:
          type: string
      responses:
        '200':
          description: orders array (formatted order objects).
        '402':
          description: Authentication Required — sign-in-with-x challenge in extensions["sign-in-with-x"] (SIGN-IN-WITH-X header on retry).
        '500':
          description: Unexpected server error.
  /x402/my/esims:
    get:
      operationId: listMyEsims
      summary: List eSIMs for the signed-in wallet
      description: Requires SIWX or X-Access-Token. Includes active bundles and topup_options_url per eSIM.
      tags:
      - Account
      parameters:
      - name: X-Access-Token
        in: header
        required: false
        description: Session JWT from POST /x402/connect. Bypasses micro-fees and SIWX re-signing until expiry.
        schema:
          type: string
      - name: SIGN-IN-WITH-X
        in: header
        required: false
        description: Base64 JSON of decomposed SIWE fields (domain, address, uri, version, chainId, type, nonce, issuedAt, signature). Required on SIWX-only routes when no X-Access-Token is present.
        schema:
          type: string
      responses:
        '200':
          description: esims array with iccid, product_id, and topup_options_url.
        '402':
          description: Authentication Required — sign-in-with-x challenge in extensions["sign-in-with-x"] (SIGN-IN-WITH-X header on retry).
        '500':
          description: Unexpected server error.