Skip to main content

API Overview

What this API covers​

bnbpay-api provides indexed payment state and relay operations for x402Flex integrations.

Primary groups:

  • health and network metadata
  • payment lookup and intent building
  • sessions
  • invoices
  • relay execution
  • gift cards

Typed client usage​

What this does: initializes a typed API client with canonical request/response types.

import { createApiClient } from '@pepay/x402flex';

const api = createApiClient({
  baseUrl: 'https://api.bnbpay.org',
  apiKey: process.env.BNBPAY_API_KEY,
});

const health = await api.health();
const networks = await api.networks();

Expected result: typed endpoint access from one SDK package.

Auth model​

  • Public read endpoints are typically rate-limited.
  • Relay endpoints may enforce x-api-key.

Error model​

API errors are surfaced as BnbpayApiError with:

  • statusCode
  • parsed details payload (if returned)

Common response shape:

{
  "error": "Human readable message"
}

Endpoint map​

  • Health:
    • GET /health
  • Networks:
    • GET /networks
  • Tokens:
    • GET /tokens
  • Payments:
    • GET /payments
    • GET /payments/:paymentId
    • GET /payments/:paymentId/status
    • POST /payments/build-intent
    • GET /can-pay
  • Wallets:
    • GET /wallets/:address/payments
  • Sessions:
    • GET /sessions
    • GET /sessions/agent/:address
    • GET /sessions/:sessionId
    • GET /sessions/:sessionId/spends
    • GET /sessions/:sessionId/payments
  • Invoices:
    • POST /invoices
    • GET /invoices/:invoiceId
    • GET /invoices/:invoiceId/status
    • POST /invoices/:invoiceId/cancel
    • POST /invoices/:invoiceId/confirm-payment
    • GET /invoices/:invoiceId/stream-sse
    • GET /invoices/:invoiceId/stream
  • Relay:
    • POST /relay/payment
    • POST /relay/permit2/bundle
    • POST /relay/session/open
    • POST /relay/session/open-claimable
    • POST /relay/session/claim
    • POST /relay/session/revoke
  • Gift cards:
    • POST /giftcards/create
    • POST /giftcards/claim
    • POST /giftcards/redeem
    • POST /giftcards/:cardId/cancel
    • GET /giftcards/:cardId
    • GET /giftcards

Common integration failures​

  • Wrong network key for route (bnb vs bnbTestnet).
  • Relay payload missing scheme-specific object.
  • paymentId lookup before indexer confirmation window.