Skip to main content
The requests module handles request validation and access control.

Methods

isValidRequest

Validate an incoming request with payment token.
const result = await payments.requests.isValidRequest(
  accessToken,
  requestBody
)
Parameters:
NameTypeDescription
accessTokenstringBearer token from Authorization header
requestBodyobjectThe request body being validated
Returns:
interface ValidationResult {
  isValid: boolean
  balance: number
  reason?: string
  subscriberAddress?: string
  planId?: string
  expiresAt?: Date
}
Example:
// Extract token from header
const authHeader = req.headers['authorization']
const token = authHeader?.substring(7) // Remove "Bearer "

const { isValid, balance, reason } = await payments.requests.isValidRequest(
  token,
  req.body
)

if (!isValid) {
  return res.status(402).json({
    error: 'Payment Required',
    reason
  })
}

// Process request...
console.log(`Credits remaining: ${balance}`)

getRequests

Get request history for an agent.
const requests = await payments.requests.getRequests({
  agentId: 'did:nv:agent-123',
  limit: 100,
  offset: 0
})
Returns:
interface RequestRecord {
  requestId: string
  agentId: string
  planId: string
  subscriberAddress: string
  creditsUsed: number
  timestamp: Date
  status: 'success' | 'failed'
}

getRequestById

Get details of a specific request.
const request = await payments.requests.getRequestById(requestId)

Validation Response Codes

reasonMeaning
undefinedValid request
TOKEN_EXPIREDAccess token has expired
INSUFFICIENT_BALANCENot enough credits
PLAN_EXPIREDTime-based plan has expired
INVALID_TOKENToken is malformed or invalid
UNAUTHORIZEDToken doesn’t grant access to this agent

Usage Patterns

Express Middleware

async function validatePayment(req, res, next) {
  const auth = req.headers['authorization']

  if (!auth?.startsWith('Bearer ')) {
    return res.status(402).json({ error: 'Payment Required' })
  }

  const token = auth.substring(7)
  const { isValid, balance, reason } = await payments.requests.isValidRequest(
    token,
    req.body
  )

  if (!isValid) {
    return res.status(402).json({
      error: 'Payment Required',
      reason
    })
  }

  req.payment = { balance }
  next()
}

With Minimum Credits

async function requireMinCredits(token, body, minCredits) {
  const { isValid, balance } = await payments.requests.isValidRequest(
    token,
    body
  )

  if (!isValid || balance < minCredits) {
    throw new Error('Insufficient credits')
  }

  return { balance }
}

Types

interface ValidationResult {
  isValid: boolean
  balance: number
  reason?: ValidationReason
  subscriberAddress?: string
  planId?: string
  expiresAt?: Date
}

type ValidationReason =
  | 'TOKEN_EXPIRED'
  | 'INSUFFICIENT_BALANCE'
  | 'PLAN_EXPIRED'
  | 'INVALID_TOKEN'
  | 'UNAUTHORIZED'

interface GetRequestsParams {
  agentId?: string
  planId?: string
  subscriberAddress?: string
  limit?: number
  offset?: number
}

Next Steps