Documentation

Quick Start

Step 1: Install

npm install @proofxhq/agentpass

Step 2: Register

const { Client, register } = require('@proofxhq/agentpass');

const account = await register({
  email: 'you@company.com',
  name: 'Your Name',
  password: 'SecurePass123!',
  company: 'Your Company'
});

// Save your API key securely
console.log('API Key:', account.apiKey);

Step 3: Create an Agent

const client = new Client({ apiKey: account.apiKey });

const agent = await client.createAgent({
  name: 'procurement-bot',
  scope: ['payments']
});

// IMPORTANT: Save the agent private key securely (shown only once)
console.log('Agent ID:', agent.id);
console.log('Private Key:', agent.agentPrivateKey); // Store in KMS/vault
console.log('Trust Score:', agent.trust.score);

Step 4: Make a Payment

const tx = await client.pay({
  agentId: agent.id,
  to: 'aws.amazon.com',
  amount: 5000,       // $50.00 in cents
  currency: 'usd',
  description: 'EC2 instance'
});

console.log('TX:', tx.transactionId);
console.log('Signed:', tx.verified);   // ECDSA P-256
console.log('Hash:', tx.hash);         // SHA-256 chain

Step 5: Prove Identity (for third-party stores)

// Agent proves it is who it claims to be
const proof = await client.proveIdentity(
  agent.id,
  agent.agentPrivateKey  // Never leaves your machine
);

console.log('Verified:', proof.verified);
console.log('Trust:', proof.trust.score);
console.log('Recommendation:', proof.recommendation);

Trust Levels

Agents start at L1 and earn higher trust through consistent, legitimate behaviour. Trust score is computed from 5 weighted dimensions.

Scoring Dimensions

What Changes Trust?

Identity Verification

Prevent agent impersonation with cryptographic challenge-response. Each agent has its own ECDSA P-256 key pair. The private key never leaves the developer's infrastructure.

How It Works

What Gets Caught

Key Management

API Reference

Agents

Payments

Trust

Identity

Wallet

Security

Every Transaction

• ECDSA P-256 signed -- non-repudiable proof of who authorised what
• Replay protected -- unique nonce per transaction, rejected if reused
• Hash-chained -- each transaction references the previous hash (tamper-evident)
• Anomaly scanned -- magnitude, velocity, timing, recipient, probing

Platform Protections

• Developer aggregate spend limits -- Sybil attack prevention
• Self-dealing detection -- circular payments earn zero trust
• Dormancy auto-demotion -- inactive agents lose trust
• Promotion rate limiting -- minimum days at each level
• Probing detection -- near-limit patterns blocked
• Challenge-response identity -- cryptographic impersonation prevention
• Rate limiting -- all endpoints protected

For Stores (Integrating Trust Checks)

One API call. No SDK needed. No auth required.

curl https://agentpass.co.uk/api/public/trust/agent_abc123

{
  "trust": { "score": 73, "level": 3 },
  "status": "ACTIVE",
  "recommendation": "ALLOW",
  "spendLimits": { "perTransaction": 100000, "daily": 500000 }
}

See it working: Demo Store | CloudByte Store (third-party example)

Error Handling

const { TrustLimitError, InsufficientFundsError, ReplayError } = require('@proofxhq/agentpass');

try {
  await client.pay({ agentId, to, amount: 999999, currency: 'usd' });
} catch (err) {
  if (err instanceof TrustLimitError) {
    // Payment exceeds trust level limit
  }
  if (err instanceof InsufficientFundsError) {
    // Wallet balance too low
  }
  if (err instanceof ReplayError) {
    // Duplicate nonce -- replay attack blocked
  }
}

Ready to start?

Free sandbox with $10,000 test balance. No credit card needed.

npm: @proofxhq/agentpass | IETF Draft | contact@agentsign.dev