Relay Endpoints

Relay endpoints submit on-chain transactions on behalf of the client. Use them when you want gasless UX or a centralized relayer.

Relay payment

POST /relay/payment

Supports:

• push_signed (signed raw transaction)
• permit2, eip2612, eip3009

import { createApiClient } from '@pepaylabs/bnbpay';

const api = createApiClient({ apiKey: process.env.BNBPAY_RELAY_KEY });

await api.relay.payment({
  network: 'bnb',
  scheme: 'permit2',
  intent,
  witness,
  witnessSignature,
  permit2,
  reference,
});

Permit2 bundle (gasless approval + payment)

POST /relay/permit2/bundle

Use when the payer cannot approve Permit2 on-chain. Provide a signed approval tx + bundle constraints.

await api.relay.permit2Bundle({
  network: 'bnb',
  intent,
  witness,
  witnessSignature,
  permit2,
  approvalTx,
  targetBlock,
});

Session management

• POST /relay/session/open – open a standard SessionGuard session
• POST /relay/session/open-claimable – open a claimable session (gift cards)
• POST /relay/session/claim – bind a claimable session to an agent wallet
• POST /relay/session/revoke – revoke an active session

These endpoints accept typed data grants signed by the payer (or claim signer), then relay the on-chain transaction.

Notes

• Relay endpoints are rate-limited and may require x-api-key.
• Always recompute referenceHash from the final reference string.
• Use /networks to retrieve router + Permit2 metadata for each chain.
• EIP-3009 payloads must be signed as ReceiveWithAuthorization with to = router.
• EIP-3009 authNonce must be intent-derived; the relay rejects non-derived nonces.