Skip to main content

Sessions (SessionGuard)

SessionGuard lets a payer pre-authorize an agent or workflow with rate limits, token caps, and scoped merchants.

Standard session grant​

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

const grant = {
  sessionId,
  payer,
  agent,
  merchantScope,
  deadline,
  expiresAt,
  epoch,
  nonce,
  rateLimit: { maxTxPerMinute: 5 },
  allowedSchemes: ['push:evm:direct'],
  tokenCaps: [{ token: USDT, cap: '1000000', dailyCap: '1000000' }],
};

const typedData = buildSessionGrantTypedData(grant, {
  chainId,
  verifyingContract: SESSION_STORE,
});

Relay the signed grant via POST /relay/session/open.

Notes:

  • allowedSchemes are hashed as keccak256(abi.encodePacked(bytes32[] schemes)). If you compute schemesHash manually, use canonical packing (no per-element hashing).

Claimable session grant (gift cards)​

Claimable grants allow a third party to claim a session before spending:

  • Open with POST /relay/session/open-claimable.
  • Claim with POST /relay/session/claim (signed by claimSigner).

Reference tagging​

When spending via session, tag the reference string with session + resource IDs:

import { formatSessionReference, buildSessionContext } from '@pepaylabs/bnbpay';

const reference = formatSessionReference('order-200', sessionId, resourceId);
const ctx = buildSessionContext({ sessionId }, { defaultAgent: agent });

Session spend authorization​

Every session spend must include SessionSpendAuth signed by the session agent. The auth is bound to the current session epoch and spend nonce.

import { getFlexSchemeId, hashPaymentIntent } from '@pepaylabs/bnbpay';

const state = await sessionStore.getSessionState(sessionId);
const spendNonce = await sessionStore.getSessionSpendNonce(sessionId);

const sessionAuth = {
  sessionId,
  intentHash: hashPaymentIntent(intent),
  schemeId: getFlexSchemeId('exact:evm:eip3009'),
  spendNonce,
  expiresAt: Math.floor(Date.now() / 1000) + 3600,
  epoch: state.epoch,
};
// Sign SessionSpendAuth typed data with the agent key.

Indexing + reconciliation​

  • GET /sessions/:sessionId/payments lists payments tied to a session.
  • auditSessionReceipts can reconcile on-chain logs locally.