A2SPA - Developer Documentation

🎥 Tutorial Video

🚀 A2SPA Complete Walkthrough

Watch this comprehensive tutorial to learn how to set up agents, sign payloads, and monitor your A2SPA implementation step by step.

🎯

What You'll Learn:

Setting up your first A2SPA agent
Implementing cryptographic signing
Using the dashboard and monitoring tools
Best practices for secure agent communication

📌 Overview

A2SPA (Agent-to-Secure Payload Authorization) is a secure protocol that enables verified, cryptographically signed payloads between AI agents. This platform allows developers and non-technical users to create, manage, and monitor modular AI agents, all protected by A2SPA.

✅

Cryptographic Signatures

Every payload must be signed with the agent's private key

🔒

Agent Permission & Toggle Checks

Granular control over agent send/receive permissions

🔄

Nonce Replay Protection

Prevents replay attacks with unique nonce verification

📊

ROI Logging Per Agent

Track time saved and value generated by each agent

💰

Pay-as-you-go Billing

$0.01 per verification with transparent usage tracking

📋

Tamper-proof Audit Trail

Complete logging of all agent interactions and verifications

🚀 Getting Started

Sign Up

Navigate to /register
Input name, email, and password
Password strength meter guides you
On success, you're automatically logged in

Login

Go to /login
Input credentials to access your dashboard

Forgot Password

Go to /forgot_password
Submit your email to receive a reset link

💡

Pro Tip: Make sure to keep your agent private keys secure. They cannot be retrieved once lost.

🧠 Agent Creation

Use the dashboard or POST /api/create_agent to create agents with configurable permissions:

JSON

{
  "agent_name": "calendarAgent",
  "permissions": {
    "send": true,
    "receive": false
  },
  "enabled": true
}

✅

This returns:

public_key and private_key (PEM format)
agent_id (e.g., abc123_calendarAgent)

🔐

Important: Keep the private key secure. It cannot be retrieved again.

Agent Permissions Explained

Permission	Description
`send`	Can initiate actions or payloads
`receive`	Can be a target agent and receive payloads

🔐 Helps prevent abuse even if an agent is compromised.

🖊️ Signing Payloads

Each payload must be:

SHA-256 hashed
Signed with the agent's private key
Include timestamp + nonce

🔷 Example Payload:

JSON

{
  "agent_id": "abc123_calendarAgent",
  "target_agent_id": "def456_reminderAgent",
  "timestamp": "2025-08-07T13:50:00Z",
  "nonce": "abc123xyz",
  "input": "Reschedule meeting to Monday 10am",
  "output": "OK, rescheduled",
  "hash": "SHA256(payload)"
}

Sign the payload JSON (excluding hash and signature) using your private key and send both:

JSON

{
  "payload": { ... },
  "signature": "<hex_signature>"
}

Send this to:

HTTP

POST /api/verify_payload
Headers: { x-api-key: YOUR_API_KEY }

🐍 Python Example Code:

Python

import json
import uuid
from datetime import datetime, timezone
from a2spa_sdk.signer import compute_payload_hash, sign_payload

# Step 1: Create your raw payload (before hash/signature)
raw_payload = {
    "agent_id": "abc123_calendarAgent",
    "target_agent_id": "abc456_meetingAgent",
    "timestamp": datetime.now(timezone.utc).isoformat(),
    "nonce": str(uuid.uuid4()),  # Prevent replay attacks
    "input": "Reschedule call to Friday",
    "output": "OK, rescheduled to Friday"
}

# Step 2: Compute the hash
raw_payload["hash"] = compute_payload_hash(raw_payload)

# Step 3: Load private key and sign
with open("myagent.priv.pem", "r") as f:
    private_key = f.read()

signature = sign_payload(raw_payload, private_key)

🔌 API Usage

Endpoint: `/api/verify_payload`

Method: POST
Content-Type: application/json

JSON Request

{
  "agent_id": "abc123_agentName",
  "payload": {"text": "Summarize this"},
  "signature": "...",
  "hash": "...",
  "nonce": "...",
  "reply_to": "optional_payload_id"
}

Requirements:

Signature must match hash and payload
Nonce must be unique (replay protection)
Agent must have permission and be ON
Credits must be available

Sample Errors:

Error	Cause
Invalid API key	Bad or missing key
Signature verification failed	Payload not signed properly
Payload hash mismatch	Modified payload or wrong hash
Replay attack detected	Nonce already used
Permission denied	Agent cannot send/receive
Agent is toggled OFF	Agent not active
Payload timestamp too old	Must be within 2 minutes

🧭 API Endpoints Summary

Endpoint	Method	Description
/api/create_agent	POST	Create new agent
/api/verify_payload	POST	Submit signed payload
/api/delete_agent	POST	Remove agent
/api/toggle_agent_status	POST	Toggle agent ON/OFF
/api/agents	GET	List all agents
/billing/topup	POST	Add tokens
/api/logs	GET	Fetch last 50 logs
/api/errors	GET	Fetch last 50 errors
/api/roi_summary	GET	Daily ROI per agent
/api/logs_csv	GET	Export logs to CSV

🛡️ Security Features

🔁 Replay Protection

Each payload includes a nonce (unique random string)
Nonces are stored with 24-hour TTL
If reused → request is blocked

🚦 Agent Toggle & Permissions

You can toggle agents ON/OFF via /api/toggle_agent_status
You can define if agents can send or receive at creation time
If an agent is OFF or lacks permission → execution is denied

🔁

Replay Attacks: What Are They?
A replay attack is when someone reuses a valid payload to trigger it again. A2SPA blocks this silently and logs the attempt.

🚨 Common Mistakes to Avoid

Mistake	Fix
Reusing a nonce or timestamp	Use uuid4() and datetime.utcnow()
Sending wrong agent_id	Match dashboard agent exactly
Forgetting to hash the payload	Call compute_payload_hash()
Signing before adding the hash	Always hash first, then sign
Payload too old (>2 min)	Send immediately, use NTP-synced clocks
Agent is toggled OFF	Go to dashboard and toggle it ON

🔍 Key Terms for Beginners

Term	What It Means	Why It Matters
Nonce	One-time string (UUID)	Stops replay attacks
Hash	Fingerprint of the payload	Proves nothing changed
Signature	Encrypted proof of identity	Proves you sent it
API Key	Your agent's access ID	Tracks usage and billing

📊 Dashboard Features

The A2SPA dashboard provides comprehensive monitoring and management capabilities for your agents:

📈 Key Components

Agents Table: View all agents with toggle, delete, and copy buttons
ROI Chart: Track time saved and dollar value generated
Credit Alert Banners: Animated warnings for low balance
Verified Logs: Expandable entries with input/output/hash/signature
Error Logs: Common causes and timestamps for debugging

📋 Log Details

Each log entry contains:

Timestamp with precise timing
Agent name + ID (click-to-copy functionality)
Action status: ✅ VERIFIED, ⚠️ CREDIT_WARNING, ❌ ERROR
Expanded view: nonce, input, output, hash, signature, ROI
CSV export option for analysis

⚠️ Credit Status Indicators

Status	Balance	Indicator	API Access
Normal	>10 tokens	Green status	Full access
Warning	<10 tokens	⚠️ Yellow banner	Full access
Critical	0 tokens	🔴 Red banner	API disabled

💰 Billing & ROI

💳 Pricing Model

A2SPA uses a simple, transparent pay-as-you-go model:

Cost per verification: $0.01 (1 token)
Top-up options: Available via /billing/topup
Balance tracking: Real-time updates in dashboard
Usage stats: Detailed per-agent consumption

📈 ROI Tracking

Each agent can define its ROI profile to track value generation:

JSON - Custom ROI

{
  "roi": {
    "time_saved_minutes": 3,
    "value_usd": 0.08
  }
}

Default ROI fallback if not provided:

JSON - Default ROI

{ 
  "time_saved_minutes": 2, 
  "value_usd": 0.05 
}

📊

ROI Visibility: Track ROI across dashboard, CSV exports, and individual log entries. Example display: "📈 ROI: 2 min saved ($0.05)"

❓ Frequently Asked Questions

🔑 Account & Security

What happens if my balance hits 0?

Agent calls are blocked, a red alert is shown in the dashboard, but logs remain visible for review.

What if I lose my private key?

Private keys cannot be retrieved. You must create a new agent with fresh keypairs.

Can I reset my API key?

This feature is currently not available but will be added in a future release.

🤖 Agent Management

Can I run multiple agents?

Yes! Each agent has its own keypair, logs, toggle status, and independent tracking.

How do I disable an agent instantly?

Use the toggle switch in your dashboard to turn agents ON/OFF immediately.

Can I customize ROI values?

Yes, you can manually report ROI values per payload or leave blank to use defaults.

🔗 Agent Communication

Can agents respond to each other?

Yes! Use the reply_to field in payloads. Both agents must be A2SPA-enabled for verification.

How do agents chain together?

Each agent gets unique keypairs. Agent A signs payload → sends to A2SPA → Agent B verifies before execution. Full cryptographic chain of custody.

🚀 Future Features (Roadmap)

Key rotation and revocation system
Real-time payload explorer with graph visualization
Advanced developer usage analytics
Agent scheduling and auto-responder workflows
Enhanced dashboard with performance metrics

💡

Need Help?
Email: hello@aiblockchainventures.com
Website: https://aimodularity.com

🔐 A2SPA Developer Documentation

🎥 Tutorial Video

📌 Overview

🚀 Getting Started

Sign Up

Login

Forgot Password

🧠 Agent Creation

Agent Permissions Explained

🖊️ Signing Payloads

🔷 Example Payload:

🐍 Python Example Code:

🔌 API Usage

Endpoint: /api/verify_payload

Requirements:

Sample Errors:

🧭 API Endpoints Summary

🛡️ Security Features

🔁 Replay Protection

🚦 Agent Toggle & Permissions

🚨 Common Mistakes to Avoid

🔍 Key Terms for Beginners

📊 Dashboard Features

📈 Key Components

📋 Log Details

⚠️ Credit Status Indicators

💰 Billing & ROI

💳 Pricing Model

📈 ROI Tracking

❓ Frequently Asked Questions

🔑 Account & Security

🤖 Agent Management

🔗 Agent Communication

🚀 Future Features (Roadmap)

Endpoint: `/api/verify_payload`