API Overview

bnbpay-api is the off-chain source of truth for invoices, indexed payments, sessions, and relay execution.

Base URL

https://api.bnbpay.org

Use createApiClient({ baseUrl }) from @pepaylabs/bnbpay for a typed client.

Auth

• GET endpoints are public and rate-limited.
• Relay endpoints accept x-api-key when relay auth is enforced.

Error shape

Errors typically return:

{
  "error": "Human readable message"
}

The SDK client throws BnbpayApiError with statusCode + details.

Endpoint map

Category	Endpoints
Health	GET /health
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
Networks	GET /networks
Tokens	GET /tokens
Gift Cards	POST /giftcards/create, POST /giftcards/claim, POST /giftcards/redeem, POST /giftcards/:cardId/cancel, GET /giftcards/:cardId, GET /giftcards

OpenAPI

The canonical spec lives at bnbpay-api/docs/openapi.yaml in the repo. Use it for codegen or validation.