{
  "openapi": "3.1.0",
  "info": {
    "title": "AbaPay",
    "version": "1.0.0",
    "description": "AbaPay is a Web3 utility bill payment agent covering 140+ countries — airtime, data, electricity, cable TV, education, bank and more — settled on-chain. This endpoint accepts x402 payments in stablecoins on Celo and Base to pay a bill on behalf of the caller.",
    "contact": {
      "email": "support@abapays.com",
      "name": "AbaPay",
      "url": "https://abapays.com"
    }
  },
  "servers": [
    { "url": "https://agents.abapays.com" }
  ],
  "paths": {
    "/api/pay/x402": {
      "post": {
        "operationId": "payBillViaX402",
        "summary": "Pay a real-world utility bill (airtime, data, electricity, cable) via x402 — 140+ countries",
        "description": "Settles a real-world bill payment via the x402 protocol. The caller pays in a supported stablecoin on Celo or Base; on confirmed settlement, AbaPay vends the underlying service (airtime top-up, data bundle, electricity token, cable subscription) through its provider integration and returns the result. Price is dynamic — it equals the live value of the bill being paid, converted to the settlement token at the platform's current exchange rate, plus any applicable service fee and a flat $0.001 facilitator fee, so there is no fixed catalog price for this resource. For ELECTRICITY, BANK, JAMB (EDUCATION), and CABLE (except Showmax), the meter/account/smartcard number is checked against the biller only AFTER settlement, not before — a wrong-but-plausible number still settles on-chain, then fails verification and is refunded automatically rather than being rejected upfront.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["serviceID", "serviceCategory", "network", "billersCode", "nairaAmount", "token", "blockchain", "wallet_address"],
                "properties": {
                  "serviceID": { "type": "string", "description": "VTpass service identifier, e.g. \"mtn\", \"ikeja-electric\"" },
                  "serviceCategory": { "type": "string", "description": "AIRTIME | DATA | ELECTRICITY | CABLE | BANK | EDUCATION" },
                  "network": { "type": "string", "description": "Provider name, e.g. MTN, IKEJA-ELECTRIC, DSTV" },
                  "billersCode": { "type": "string", "description": "Phone number, meter number, or smartcard/IUC number being paid for" },
                  "nairaAmount": { "type": "number", "description": "Bill amount denominated in NGN — the source of truth for pricing this request, including for international bills (the local-currency figure travels separately as foreignAmount)" },
                  "token": { "type": "string", "enum": ["USDC", "USD₮"], "description": "On Celo, both USDC and USDT (Tether) settle via x402 — each implements EIP-3009 transferWithAuthorization. On Base, USDC only (Base USDT has no transferWithAuthorization). cUSD/USDm are never supported (no transferWithAuthorization)." },
                  "blockchain": { "type": "string", "enum": ["CELO", "BASE"], "description": "Celo settles through Celo's own x402 facilitator; Base settles through Coinbase's CDP facilitator" },
                  "wallet_address": { "type": "string", "description": "The paying wallet's address, for cross-checking against the x402 payment authorization's payer" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Bill vended successfully (or queued for background processing).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "status": { "type": "string", "enum": ["SUCCESS", "FAILED_VENDING", "TIMEOUT"] },
                    "purchased_code": { "type": "string", "nullable": true, "description": "Electricity token or exam PIN, when applicable" },
                    "units": { "type": "string", "nullable": true },
                    "request_id": { "type": "string" },
                    "tx_hash": { "type": "string", "description": "The on-chain settlement transaction hash" }
                  }
                }
              }
            }
          },
          "402": {
            "description": "Payment required — standard x402 challenge response."
          }
        },
        "x-payment-info": {
          "price": {
            "mode": "dynamic",
            "currency": "USDC",
            "min": "0.05"
          },
          "protocols": [
            {
              "protocol": "x402",
              "version": 2,
              "scheme": "exact",
              "network": "eip155:42220",
              "asset": "0xcebA9300f2b948710d2653dD7B07f33A8B32118C",
              "payTo": "0x5df8aE2B963165b735B18Ca86B1ea448d2AA032C"
            },
            {
              "protocol": "x402",
              "version": 2,
              "scheme": "exact",
              "network": "eip155:42220",
              "asset": "0x48065fbBE25f71C9282ddf5e1cD6D6A887483D5e",
              "payTo": "0x5df8aE2B963165b735B18Ca86B1ea448d2AA032C"
            },
            {
              "protocol": "x402",
              "version": 2,
              "scheme": "exact",
              "network": "eip155:8453",
              "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
              "payTo": "0xC0A4dAA04DEd9c54D1239507B5A5E645761ef488"
            }
          ]
        }
      }
    }
  }
}