TypeScript / Node.js SDK

Install

npm install @pqsafe/agent-pay

Requirements

Node.js ≥ 18.0.0
TypeScript ≥ 5.0 (recommended)

Core API

See the auto-generated API Reference for complete type signatures.

Key functions

Function	Description
`generateKeyPair()`	Generate ML-DSA-65 keypair
`createSpendEnvelope(options)`	Create a bounded spend envelope
`createSignedEnvelope(envelope, secretKey)`	Sign an envelope
`verifyEnvelope(signed, publicKey)`	Verify a signed envelope
`executeAgentPayment(signed, request)`	Execute a payment
`buildLedgerRecord(signed, result)`	Build a ledger record
`submitToLedger(record)`	Submit to the append-only ledger

Rail-specific exports

import { probeX402Endpoint } from '@pqsafe/agent-pay'       // x402 rail
import { executeWithApproval } from '@pqsafe/agent-pay'      // Approval gate
import { commitEnvelopeToArbitrum } from '@pqsafe/agent-pay' // On-chain anchor

Configuration

import { setAgentPayConfig } from '@pqsafe/agent-pay'

setAgentPayConfig({
  defaultRail: 'airwallex',
  logLevel: 'info',
  ledgerUrl: 'https://ledger.pqsafe.xyz',
})

Error types

All SDK errors are instances of PQSafeError:

import { PQSafeError } from '@pqsafe/agent-pay'

try {
  await executeAgentPayment(signed, request)
} catch (err) {
  if (err instanceof PQSafeError) {
    console.log(err.code)    // e.g. 'ENVELOPE_EXPIRED'
    console.log(err.message)
    console.log(err.details) // Additional context
  }
}

Error codes

Code	Meaning
`ENVELOPE_SIGNATURE_INVALID`	ML-DSA-65 verification failed
`ENVELOPE_EXPIRED`	`validUntil` has passed
`ENVELOPE_ALREADY_USED`	Replay attack prevention
`AMOUNT_EXCEEDS_ENVELOPE`	Payment amount > `maxAmount`
`RECIPIENT_NOT_ALLOWED`	Recipient not in `allowedRecipients`
`RAIL_NOT_ALLOWED`	Rail not in `allowedRails`
`APPROVAL_REQUIRED`	Human approval not yet received
`RAIL_TIMEOUT`	Rail API did not respond in time
`INSUFFICIENT_BALANCE`	Rail account has insufficient funds

Full API reference

→ Auto-generated API Reference