PQSafe quickstart — verified envelope in 60 seconds

1

Install the SDK

0:00 — 0:20

Node / TypeScript

# core SDK
npm i @pqsafe/agent-pay

# conformance test vectors (optional)
npm i @pqsafe/conformance

Python

# core SDK
pip install pqsafe

# conformance test vectors (optional)
pip install pqsafe-conformance

2

Verify a test envelope

0:20 — 0:40

verify.ts

import { verify } from '@pqsafe/agent-pay';

const vec = await fetch(
  'https://pqsafe.xyz/spec/ap2-pq-test-vectors-v1.json'
).then(r => r.json());

const result = await verify(vec.tcs[0].envelope, {
  ecdsa_pub_hex: vec.ecdsa_public_key_compressed_hex,
  mldsa_pub_b64u: vec.mldsa_public_key_base64url,
});

console.log(result.valid ? 'OK' : 'REJECTED');
// → OK

verify.py

from pqsafe import verify
import urllib.request, json

vec = json.load(urllib.request.urlopen(
  'https://pqsafe.xyz/spec/ap2-pq-test-vectors-v1.json'
))

result = verify(
  vec['tcs'][0]['envelope'],
  ecdsa_pub_hex=vec['ecdsa_public_key_compressed_hex'],
  mldsa_pub_b64u=vec['mldsa_public_key_base64url'],
)

print('OK' if result.valid else 'REJECTED')
# → OK

3

Reject a tampered one

0:40 — 0:60

tamper.ts

const evil = structuredClone(vec.tcs[0].envelope);
evil.amount = '9999.00';  // mutate

const r = await verify(evil, {
  ecdsa_pub_hex: vec.ecdsa_public_key_compressed_hex,
  mldsa_pub_b64u: vec.mldsa_public_key_base64url,
});

console.log(r.valid ? 'OK' : 'REJECTED');
// → REJECTED

tamper.py

import copy
evil = copy.deepcopy(vec['tcs'][0]['envelope'])
evil['amount'] = '9999.00'  # mutate

r = verify(
  evil,
  ecdsa_pub_hex=vec['ecdsa_public_key_compressed_hex'],
  mldsa_pub_b64u=vec['mldsa_public_key_base64url'],
)

print('OK' if r.valid else 'REJECTED')
# → REJECTED

Drop into your agent framework

One import. The pqsafePay tool gates every payment call on a verified envelope. Snippets below are minimal — consult each plugin's README for production wiring.

pip install langchain-pqsafe

from langchain.agents import AgentExecutor
from langchain_pqsafe import AgentPayTool

agent = AgentExecutor(
    tools=[AgentPayTool(spend_cap='100.00', currency='USD')],
    ...
)
# every payment the agent attempts is gated by a signed envelope

pip install langgraph-pqsafe

from langgraph.graph import StateGraph
from langgraph_pqsafe import spend_envelope_checkpoint

graph = StateGraph(State)
graph.add_node('pay', spend_envelope_checkpoint(make_payment))
# state transitions that move money require a signed mandate first

npm i @pqsafe/vercel-ai

import { generateText } from 'ai';
import { pqsafePay } from '@pqsafe/vercel-ai';

await generateText({
  model: openai('gpt-4o'),
  tools: { pqsafePay: pqsafePay({ spend_cap: '100.00' }) },
  prompt: 'Pay the invoice from acme.com',
});

pip install pydantic-ai-pqsafe

from pydantic_ai import Agent
from pydantic_ai_pqsafe import SpendEnvelopeTool

agent = Agent('openai:gpt-4o', tools=[SpendEnvelopeTool()])
# the SpendEnvelope schema is validated at the model boundary

pip install crewai-pqsafe

from crewai import Task
from crewai_pqsafe import with_spend_envelope

task = with_spend_envelope(
    Task(description='Reimburse the user'),
    spend_cap='50.00', currency='USD',
)

npm i @pqsafe/mastra

import { Agent } from '@mastra/core';
import { pqsafePayTool } from '@pqsafe/mastra';

const agent = new Agent({
  tools: { pqsafePay: pqsafePayTool({ spend_cap: '100.00' }) },
});

pip install autogen-pqsafe

from autogen import ConversableAgent
from autogen_pqsafe import register_spend_envelope

agent = ConversableAgent('cfo', llm_config={...})
register_spend_envelope(agent, shared_cap='500.00')
# shared budget across all agents in the conversation

pip install llamaindex-pqsafe

from llama_index.agent import ReActAgent
from llamaindex_pqsafe import AgentPayTool

agent = ReActAgent.from_tools([AgentPayTool(spend_cap='100.00')])

pip install anthropic-pqsafe

from anthropic import Anthropic
from anthropic_pqsafe import with_pqsafe_intercept

client = with_pqsafe_intercept(Anthropic(), spend_cap='100.00')
# intercepts Computer Use payments and gates them on a signed envelope

npm i @pqsafe/agent-pay

import { issue, verify } from '@pqsafe/agent-pay';

const envelope = await issue({
  agent_id: 'did:web:agents.example.com:agent-1',
  amount: '50.00', currency: 'USD',
  recipient: 'did:web:merchant.example.com:payee',
});

const result = await verify(envelope, publicKeys);
if (!result.valid) throw new Error('rejected');

What just happened

The SDK fetched the canonical test vectors, ran RFC 8785 JCS canonicalization on the mandate (without the signature field), SHA-256'd the canonical bytes to get a 32-byte fingerprint, and verified two signatures over that fingerprint: ECDSA P-256 (legacy compatibility) and ML-DSA-65 (FIPS 204 post-quantum). Both must pass.

When you mutated amount, the canonical bytes changed, the fingerprint changed, and both signatures stopped matching. There is no way to flip a field and re-use the original signature — you would need the issuer's private keys.

This is what makes the SpendEnvelope a cryptographic permission slip rather than a session token. The amount, the recipient, the currency, and the nonce are bound to the signature. Replay protection comes from the nonce registry (on-chain + edge cache). Revocation comes from a separate signed revoke list. Audit comes from the canonical envelope retention.

Why two signatures? ECDSA P-256 gives you universal verifier compatibility today. ML-DSA-65 gives you forward security through the post-quantum transition. The cost is ~3KB of signature bytes and ~0.03 ms of native verify time on top of ECDSA — see /bench.

Try the Tamper Explorer →

8 one-click mutations on a real envelope. See exactly which signature fails when which field changes.

Issue one in your browser →

Generate an ephemeral keypair and sign a SpendEnvelope client-side. No setup.

Compare to JWT / AP2 / Stripe Issuing →

Capability matrix, where each one wins, when post-quantum matters.

Read the AP2-PQ spec →

Wire-level details of the canonical envelope shape and dual-signature scheme.

Verify your first envelope in 60 seconds.

Install the SDK

Verify a test envelope

Reject a tampered one

Drop into your agent framework