Paycelot Documentation

Getting Started

What is Paycelot?

Paycelot is an intelligent payment delegation platform that enables organizations to grant controlled spending authority to AI agents and autonomous systems. It combines cryptographic agent identity, dynamic spending policies, and real-time transaction verification to create a secure framework for autonomous financial operations.

Key capabilities include:

• Agent-based spending delegation with granular control
• Dynamic spending policies with real-time evaluation
• Cryptographic proof of agent actions via Ed25519 signatures
• Trust scoring for behavioral anomaly detection
• Multi-currency support including USDC stablecoin
• Event sourcing for complete transaction audit trails

Quick Start: 3 Steps

Step 1: Register an Agent

Create an agent identity in the system:

curl -X POST https://paycelot.com/api/v1/agents \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "payment-processor-bot",
    "orgId": "org_123",
    "capabilities": ["payments", "settlements"]
  }'

Step 2: Create a Spending Policy

Define rules for what the agent can spend:

curl -X POST https://paycelot.com/api/v1/policies \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Daily Spend Limit",
    "agentId": "agent_456",
    "rules": {
      "dailyLimit": 10000,
      "perTransactionLimit": 500,
      "allowedVendors": ["vendor_1", "vendor_2"]
    }
  }'

Step 3: Issue a Payment Token

Create a scoped token for a specific transaction:

curl -X POST https://paycelot.com/api/v1/tokens \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "agent_456",
    "amount": 250.00,
    "currency": "USD",
    "expiryHours": 24,
    "scopes": ["payment"]
  }'

API Base URL

Authentication

API Key Authentication

For administrative and setup operations, use API key authentication by including the X-API-Key header:

curl -H "X-API-Key: sk_live_abc123def456ghi789" \
  https://paycelot.com/api/v1/agents

Agent Ed25519 Signature Authentication

Agents authenticate operations using Ed25519 digital signatures. Each request from an agent includes a cryptographic proof of identity:

# Sign a transaction with agent private key
import nacl.signing

# Load agent's signing key
signing_key = nacl.signing.SigningKey(agent_private_key)

# Create signature for transaction
transaction_data = {
    "agentId": "agent_456",
    "amount": 250.00,
    "nonce": 12345,
    "timestamp": "2024-01-15T10:30:00Z"
}

signature = signing_key.sign(str(transaction_data))

# Include signature in request
headers = {
    "X-Agent-Signature": signature.signature.hex(),
    "X-Agent-Id": "agent_456"
}

Agent Management

Agent Identity & Lifecycle

Agents are cryptographically verified entities with their own identity, permissions, and trust profile. Each agent has:

• Public Key: Ed25519 public key for signature verification
• Private Key: Ed25519 private key (stored securely by agent operator)
• Trust Score: 0-1000 rating based on transaction history
• Status: active, suspended, or revoked
• Capabilities: List of operations the agent can perform

Register an Agent

POST /api/v1/agents

{
  "name": "payment-processor-bot",
  "orgId": "org_123",
  "capabilities": ["payments", "settlements"],
  "publicKey": "8a3f9b2c1d4e5f6g7h8i9j0k1l2m3n4o"
}

Response:
{
  "id": "agent_456",
  "name": "payment-processor-bot",
  "status": "active",
  "trustScore": 500,
  "createdAt": "2024-01-15T10:00:00Z"
}

List Agents

GET /api/v1/agents?status=active&limit=50&offset=0

Get Agent Details

GET /api/v1/agents/{agentId}

Key Rotation

Rotate an agent's signing keys to maintain security:

POST /api/v1/agents/{agentId}/rotate-keys

{
  "newPublicKey": "new_public_key_value",
  "signature": "signed_with_old_key"
}

Spending Policies

Policy Structure

Spending policies define conditions and actions that govern agent transactions. A policy evaluates each request and either approves or denies it based on defined rules.

Policy Components

• Rules: Conditions that must be met (daily limit, vendor allowlist, time-of-day)
• Actions: What to do when rule is violated (deny, approve, escalate)
• Evaluation: Real-time checking during transaction processing

Create a Policy

POST /api/v1/policies

{
  "name": "Daily Spend Limit",
  "agentId": "agent_456",
  "rules": {
    "dailyLimit": 10000,
    "perTransactionLimit": 500,
    "allowedVendors": ["vendor_1", "vendor_2"],
    "allowedTimeWindow": {
      "start": "09:00",
      "end": "17:00"
    }
  }
}

Evaluate Policy

Check if a transaction would be approved under current policies:

POST /api/v1/policies/evaluate

{
  "agentId": "agent_456",
  "amount": 250.00,
  "vendor": "vendor_1",
  "timestamp": "2024-01-15T14:30:00Z"
}

Response:
{
  "approved": true,
  "policies": ["policy_789"],
  "remainingDaily": 9750,
  "reason": "All policies satisfied"
}

Payment Tokens

What are Scoped Payment Tokens?

Payment tokens are cryptographic credentials that grant temporary, limited spending authority to an agent. They are scoped to specific amounts, currencies, and time windows, providing fine-grained control over autonomous spending.

Token Lifecycle

• Created: Token issued with initial amount and expiration
• Active: Available for use until expiration or exhaustion
• Used: Amount consumed in transactions
• Expired: Time window passed or amount exhausted

Issue a Payment Token

POST /api/v1/tokens

{
  "agentId": "agent_456",
  "amount": 250.00,
  "currency": "USD",
  "expiryHours": 24,
  "scopes": ["payment"],
  "description": "Vendor payment Q1 2024"
}

Response:
{
  "id": "token_abc123",
  "agentId": "agent_456",
  "amount": 250.00,
  "remaining": 250.00,
  "status": "active",
  "expiresAt": "2024-01-16T10:30:00Z"
}

Validate Token

GET /api/v1/tokens/{tokenId}/validate

Response:
{
  "valid": true,
  "remaining": 150.00,
  "expiresAt": "2024-01-16T10:30:00Z"
}

Settlements

Multi-Party Settlement (Saga Pattern)

Settlements coordinate complex financial operations across multiple parties using the saga pattern, ensuring atomicity and rollback capability if any step fails.

Create a Settlement

POST /api/v1/settlements

{
  "settlementId": "settlement_xyz",
  "parties": [
    {
      "agentId": "agent_456",
      "amount": 1000.00,
      "direction": "debit"
    },
    {
      "agentId": "agent_789",
      "amount": 1000.00,
      "direction": "credit"
    }
  ]
}

Execute Settlement

POST /api/v1/settlements/{settlementId}/execute

{
  "signature": "signed_authorization"
}

Response:
{
  "status": "completed",
  "transactionHash": "0x1234567890abcdef",
  "completedAt": "2024-01-15T10:35:00Z"
}

Rollback Settlement

If a settlement fails, rollback all changes:

POST /api/v1/settlements/{settlementId}/rollback

Audit Trail

Event Sourcing Model

All financial operations are logged as immutable events. This provides a complete transaction trace and audit trail for compliance and debugging.

Query Events

GET /api/v1/audit/events?agentId=agent_456&type=payment&limit=50

Response:
{
  "events": [
    {
      "id": "event_001",
      "timestamp": "2024-01-15T10:30:00Z",
      "type": "payment",
      "agentId": "agent_456",
      "amount": 250.00,
      "status": "approved",
      "transactionHash": "0xabcd1234"
    }
  ]
}

Transaction Trace

Get full history of a specific transaction:

GET /api/v1/audit/transactions/{transactionId}

Trust Scores

Trust Score Calculation (0-1000)

Trust scores are dynamic ratings that reflect an agent's reliability and adherence to policies. Higher scores unlock additional capabilities and higher transaction limits.

Scoring Factors

• Transaction History: Success rate and consistency of transactions
• Policy Adherence: Compliance with all defined policies
• Dispute Rate: Frequency of disputed or reversed transactions
• Anomaly Detection: Deviation from typical transaction patterns
• Account Age: Time since agent was registered

Get Trust Score

GET /api/v1/trust/{agentId}

Response:
{
  "agentId": "agent_456",
  "score": 850,
  "level": "high",
  "factors": {
    "transactionHistory": 95,
    "policyAdherence": 100,
    "disputeRate": 2,
    "anomalyScore": 5,
    "accountAge": 180
  },
  "updatedAt": "2024-01-15T10:30:00Z"
}

Crypto & Virtual Cards

Product Roadmap

Phase 1: Virtual Cards with Guardrails

Initial launch with traditional card infrastructure and real-time policy enforcement.

• Virtual card creation with per-card spending limits
• Real-time policy evaluation on each transaction
• Automatic declines for policy violations
• Merchant category restrictions

Phase 2: Intent Verification (Job Plans)

Enhanced autonomy with structured transaction planning.

• Agents submit job plans describing intended transactions
• Human reviewers approve plans before execution
• Automatic execution within approved parameters
• Higher trust scores unlock faster approvals

Phase 3: Stablecoin (USDC) Transfers

Direct blockchain transfers for high-volume operations.

• USDC transfers on Polygon and other chains
• Instant settlement without intermediaries
• Lower transaction costs for high-volume agents

FedNow Instant Settlement

Direct integration with FedNow for real-time ACH transfers.

• Sub-second settlement to bank accounts
• 24/7 availability
• Full compliance with banking regulations

Create Virtual Card

POST /api/v1/crypto/cards

{
  "agentId": "agent_456",
  "cardLimit": 5000.00,
  "currency": "USD",
  "cardType": "virtual"
}

Response:
{
  "cardId": "card_virt_123",
  "pan": "4111111111111111",
  "status": "active",
  "limit": 5000.00,
  "balance": 5000.00
}

Webhooks

Event Types

Subscribe to these events for real-time notifications:

• agent.created - New agent registered
• agent.status_changed - Agent status updated
• policy.created - New policy defined
• policy.evaluated - Policy evaluation result
• token.created - Payment token issued
• token.used - Token partially or fully consumed
• settlement.completed - Settlement finished
• settlement.failed - Settlement encountered error

Webhook Payload

{
  "id": "webhook_evt_001",
  "type": "policy.evaluated",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "agentId": "agent_456",
    "approved": true,
    "amount": 250.00,
    "policies": ["policy_789"]
  }
}

Setup Webhook

POST /api/v1/webhooks

{
  "url": "https://your-domain.com/webhooks/paycelot",
  "events": ["policy.evaluated", "settlement.completed"],
  "secret": "whsec_your_secret_key"
}

SDKs

Python SDK

Install via pip:

pip install paycelot

Usage example:

from paycelot import PaycelotClient

client = PaycelotClient(api_key="sk_live_abc123")

# Register agent
agent = client.agents.create(
    name="payment-bot",
    org_id="org_123",
    capabilities=["payments"]
)

# Issue token
token = client.tokens.create(
    agent_id=agent.id,
    amount=250.00,
    expiry_hours=24
)

TypeScript/JavaScript SDK

Install via npm:

npm install @paycelot/sdk

Usage example:

import { PaycelotClient } from '@paycelot/sdk';

const client = new PaycelotClient({
  apiKey: 'sk_live_abc123'
});

// Register agent
const agent = await client.agents.create({
  name: 'payment-bot',
  orgId: 'org_123',
  capabilities: ['payments']
});

Go SDK

Install via go get:

go get github.com/paycelot/paycelot-go

API Reference

All Endpoints