{
  "openapi": "3.0.3",
  "info": {
    "title": "HoneyCoin B2B Fiat API",
    "description": "REST API for cross-border payouts, payment collections, FX rates, banks, and mobile money utilities across African markets. Full human docs: https://docs.honeycoin.app — agent capabilities: https://honeycoin.app/agents.md",
    "version": "2.0.0",
    "contact": {
      "name": "HoneyCoin API Support",
      "email": "api@honeycoin.app",
      "url": "https://docs.honeycoin.app"
    }
  },
  "servers": [
    {
      "url": "https://api-v2.honeycoin.app/api/b2b",
      "description": "Production"
    },
    {
      "url": "https://api-v2.honeycoin.app/api/sandbox/b2b",
      "description": "Sandbox"
    }
  ],
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "Obtain via POST /auth/generate-bearer-token with api-key header and publicKey body. Tokens expire after 2 hours."
      },
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "api-key",
        "description": "API key from https://b2b.honeycoin.app (Developers → API Keys). Format: HC_…"
      }
    }
  },
  "paths": {
    "/auth/generate-bearer-token": {
      "post": {
        "operationId": "generateBearerToken",
        "summary": "Generate Bearer token",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["publicKey"],
                "properties": {
                  "publicKey": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Token issued"
          }
        }
      }
    },
    "/fiat/payout": {
      "post": {
        "operationId": "createPayout",
        "summary": "Send payout to mobile money, bank, Paybill, or Till",
        "responses": {
          "200": {
            "description": "Payout accepted"
          }
        }
      }
    },
    "/fiat/deposit/bank-transfer": {
      "post": {
        "operationId": "createBankTransferDeposit",
        "summary": "Create virtual bank account for collection",
        "responses": {
          "200": {
            "description": "Deposit account created"
          }
        }
      }
    },
    "/fiat/payment-sdk": {
      "post": {
        "operationId": "createPaymentSdkSession",
        "summary": "Universal Payment SDK session",
        "responses": {
          "200": {
            "description": "Payment session created"
          }
        }
      }
    },
    "/fiat/deposit/{transactionId}/refund": {
      "post": {
        "operationId": "refundDeposit",
        "summary": "Refund a mobile money deposit",
        "parameters": [
          {
            "name": "transactionId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Refund initiated"
          }
        }
      }
    },
    "/utilities/rates/historical": {
      "get": {
        "operationId": "getHistoricalRates",
        "summary": "Get FX rates",
        "responses": {
          "200": {
            "description": "Rates returned"
          }
        }
      }
    },
    "/transactions": {
      "get": {
        "operationId": "listTransactions",
        "summary": "Query transaction history",
        "responses": {
          "200": {
            "description": "Transactions returned"
          }
        }
      }
    },
    "/utilities/banks": {
      "get": {
        "operationId": "listBanks",
        "summary": "Get supported banks by country",
        "parameters": [
          {
            "name": "country",
            "in": "query",
            "schema": {
              "type": "string",
              "example": "KE"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Banks returned"
          }
        }
      }
    },
    "/utilities/momo/providers": {
      "get": {
        "operationId": "listMomoProviders",
        "summary": "Get mobile money operators",
        "responses": {
          "200": {
            "description": "Providers returned"
          }
        }
      }
    }
  }
}