AgentPort API Reference

AgentPort wraps any Hermes agent with authentication, rate limiting, cryptographic receipts, and on-chain payment routing. This page documents every endpoint, environment variable, and internal algorithm.

Caller → AgentPort Gateway → Hermes Agent
         ↓
   [auth check]         validates x-api-key or x-payment-tx
   [rate limit]         sliding-window counter per key
   [proxy call]         POST hermesUrl/hermesPath with caller body
   [receipt gen]        sha256(callId:agentId:ts:reqHash:resHash)
   [log to db]          INSERT INTO calls(...)
         ↓
   Response + X-AgentPort-Receipt header

agents
  id            TEXT  PK        8-char UUID prefix
  name          TEXT
  hermes_url    TEXT            base URL of the upstream Hermes instance
  hermes_path   TEXT  DEFAULT /api/chat
  description   TEXT
  is_public     INT   0|1       listed in the public registry
  pricing_mode  TEXT  free|per_call
  price_per_call TEXT           AGNP amount string
  created_at    INT             Unix ms

api_keys
  key           TEXT  PK        "ap_" + 32 random base64url chars
  agent_id      TEXT            FK → agents.id
  label         TEXT
  rate_limit_per_hour  INT
  is_active     INT   0|1       0 = revoked (soft-delete)
  created_at    INT

calls
  id            TEXT  PK        full UUID
  agent_id      TEXT
  api_key       TEXT  nullable
  request_hash  TEXT            sha256 of raw request body
  response_hash TEXT            sha256 of upstream response body
  receipt_hash  TEXT            sha256 of the receipt preimage
  status_code   INT
  duration_ms   INT
  payment_tx    TEXT            x402 transaction hash if applicable
  created_at    INT

# 1. Register your Hermes agent
curl -X POST https://your-gateway.vercel.app/admin/agents \
  -H "x-admin-secret: $ADMIN_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "name":         "my-analyst",
    "hermesUrl":    "https://my-hermes.up.railway.app",
    "hermesPath":   "/api/chat",
    "description":  "Financial data analyst",
    "isPublic":     true,
    "pricingMode":  "per_call",
    "pricePerCall": "0.01"
  }'
# → { "agentId": "a1b2c3d4", "endpoint": "/v1/agents/a1b2c3d4/run" }

# 2. Issue an API key for a caller
curl -X POST https://your-gateway.vercel.app/admin/agents/a1b2c3d4/keys \
  -H "x-admin-secret: $ADMIN_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "label": "partner-1", "rateLimitPerHour": 500 }'
# → { "key": "ap_xxxxxxxxxxxxxxxxxxxxxxxxxxxx", ... }

# 3. Call the agent
curl -X POST https://your-gateway.vercel.app/v1/agents/a1b2c3d4/run \
  -H "x-api-key: ap_xxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "messages": [{ "role": "user", "content": "Analyze AGNP liquidity" }] }'
# ← 200 OK
# X-AgentPort-Receipt: eyJ2IjoiMSIsImNhbGxJZCI6...
# X-AgentPort-Duration-Ms: 284
# X-RateLimit-Remaining: 499

# 1. Create a Turso database
turso db create agentport

# 2. Get credentials
turso db show agentport          # → TURSO_DB_URL
turso db tokens create agentport # → TURSO_AUTH_TOKEN

# 3. Set env vars in Vercel
vercel env add TURSO_DB_URL
vercel env add TURSO_AUTH_TOKEN
vercel env add ADMIN_SECRET
vercel env add GATEWAY_PUBLIC_URL  # e.g. https://agentport-xyz.vercel.app
vercel env add PAYMENT_WALLET      # your Base wallet address

# 4. Deploy
vercel --prod

# railway.toml (in apps/gateway/)
[build]
  builder    = "NIXPACKS"
  buildCommand = "pnpm build"

[deploy]
  startCommand = "node dist/index.js"
  healthcheckPath = "/health"

# Set env vars in the Railway dashboard:
# PORT, ADMIN_SECRET, DB_PATH (or TURSO_*), GATEWAY_PUBLIC_URL

cd apps/gateway
pnpm build                     # compiles TypeScript → dist/
node dist/index.js             # or: pm2 start dist/index.js --name agentport

# With a .env file:
# tsx watch --env-file=.env src/index.ts   (dev)
# node dist/index.js                        (production, after build)

# Correct
curl -H "x-admin-secret: $ADMIN_SECRET" https://your-gateway.vercel.app/admin/stats

# Missing → 401
{ "error": "Unauthorized" }

# Call a paid agent with an API key
curl -X POST https://your-gateway.vercel.app/v1/agents/:agentId/run \
  -H "x-api-key: ap_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "messages": [{ "role": "user", "content": "Hello" }] }'

X-RateLimit-Limit:     500        # your key's per-hour budget
X-RateLimit-Remaining: 497        # calls left in the current window
X-RateLimit-Reset:     1716048000 # Unix timestamp (seconds) when the window fully resets

HTTP 429 Too Many Requests
X-RateLimit-Limit:     500
X-RateLimit-Remaining: 0
X-RateLimit-Reset:     1716048000

{ "error": "Rate limit exceeded" }

{
  "v":            "1",             // receipt version
  "callId":       "uuid-v4",       // unique call identifier
  "agentId":      "a1b2c3d4",      // 8-char agent ID
  "timestamp":    1716048000000,   // Unix ms when call was processed
  "requestHash":  "sha256hex...",  // sha256 of the raw JSON request body
  "responseHash": "sha256hex...",  // sha256 of the upstream response body
  "receiptHash":  "sha256hex..."   // binding hash — see algorithm below
}

receiptHash = sha256(
  callId + ":" + agentId + ":" + timestamp + ":" + requestHash + ":" + responseHash
)

// TypeScript
import { createHash } from 'crypto'
import { Buffer } from 'buffer'

function verifyReceipt(encoded: string): boolean {
  const r = JSON.parse(Buffer.from(encoded, 'base64url').toString('utf8'))
  const expected = createHash('sha256')
    .update(`${r.callId}:${r.agentId}:${r.timestamp}:${r.requestHash}:${r.responseHash}`)
    .digest('hex')
  return expected === r.receiptHash
}

# Python
import hashlib, base64, json

def verify_receipt(encoded: str) -> bool:
    r = json.loads(base64.urlsafe_b64decode(encoded + "=="))
    preimage = f"{r['callId']}:{r['agentId']}:{r['timestamp']}:{r['requestHash']}:{r['responseHash']}"
    expected = hashlib.sha256(preimage.encode()).hexdigest()
    return expected == r['receiptHash']

# The receipt is in the X-AgentPort-Receipt response header
RECEIPT=$(curl -si ... | grep -i "x-agentport-receipt" | awk '{print $2}')

# Decode it
echo $RECEIPT | python3 -c "
import sys, base64, json
raw = sys.stdin.read().strip()
data = json.loads(base64.urlsafe_b64decode(raw + '=='))
print(json.dumps(data, indent=2))
"

HTTP/1.1 402 Payment Required
X-Payment-Required:  true
X-Price:             0.01 AGNP
X-Payment-Methods:   api-key,x402
X-Payment-Address:   0x95ccfd2b81a9667b0cc979992632f98fc853eba3
X-Payment-Token:     0x95ccfd2b81a9667b0cc979992632f98fc853eba3
X-Payment-Chain:     base

{
  "error": "Payment required",
  "pricing": {
    "mode": "per_call",
    "pricePerCall": "0.01",
    "currency": "AGNP",
    "methods": ["api-key", "x402"],
    "paymentAddress": "0x...",
    "tokenContract": "0x95ccfd2b81a9667b0cc979992632f98fc853eba3",
    "chain": "base",
    "chainId": 8453
  }
}

{
  "messages": [
    { "role": "user",      "content": "What is the price of ETH?" },
    { "role": "assistant", "content": "..." },   // optional — for multi-turn
    { "role": "user",      "content": "And BTC?" }
  ]
}

HTTP/1.1 200 OK
X-AgentPort-Receipt:      eyJ2IjoiMSIsImNhbGxJZCI...
X-AgentPort-Call-Id:      a3f9b1c2-fd1e-4df2-930b-1a2b3c4d5e6f
X-AgentPort-Duration-Ms:  284
X-RateLimit-Limit:        500
X-RateLimit-Remaining:    497
X-RateLimit-Reset:        1716048000

// Body is the raw Hermes response, passed through unchanged

404  { "error": "Agent not found" }
402  { "error": "Payment required", "pricing": { ... } }
429  { "error": "Rate limit exceeded" }
502  Upstream Hermes call failed (gateway-level error)

GET /v1/agents

{
  "agents": [
    {
      "id":            "a1b2c3d4",
      "name":          "My Analyst",
      "description":   "Financial data analyst",
      "pricing_mode":  "per_call",
      "price_per_call":"0.01",
      "created_at":    1716048000000
    }
  ]
}

GET /v1/agents/a1b2c3d4/receipts?limit=20&page=1

{
  "receipts": [
    {
      "id":            "uuid",
      "receipt_hash":  "sha256hex...",
      "request_hash":  "sha256hex...",
      "response_hash": "sha256hex...",
      "status_code":   200,
      "duration_ms":   284,
      "created_at":    1716048000000
    }
  ],
  "total": 142,
  "page":  1,
  "limit": 20
}

POST /v1/receipts/verify
Content-Type: application/json

{ "receipt": "eyJ2IjoiMSIsImNhbGxJZCI6..." }

// Response
{
  "valid": true,
  "receipt": {
    "v":            "1",
    "callId":       "a3f9b1c2-...",
    "agentId":      "a1b2c3d4",
    "timestamp":    1716048000000,
    "requestHash":  "3f8a2b9c...",
    "responseHash": "9c2e5d8b...",
    "receiptHash":  "1a4b7e2c..."
  },
  "onChain": {
    "found":      true,
    "callId":     "a3f9b1c2-...",
    "statusCode": 200,
    "durationMs": 284,
    "timestamp":  1716048000000
  }
}

// Invalid receipt
{ "valid": false, "receipt": { ... }, "onChain": { "found": false } }

GET /health

{ "status": "ok", "version": "0.1.0", "name": "AgentPort" }

POST /admin/agents
x-admin-secret: <secret>

{
  "name":          "My Analyst",
  "hermesUrl":     "https://my-hermes.up.railway.app",
  "hermesPath":    "/api/chat",
  "description":   "A helpful financial analyst",
  "isPublic":      true,
  "pricingMode":   "per_call",
  "pricePerCall":  "0.01"
}

// 201 Created
{
  "agentId":  "a1b2c3d4",
  "name":     "My Analyst",
  "endpoint": "/v1/agents/a1b2c3d4/run"
}

GET /admin/agents
x-admin-secret: <secret>

{
  "agents": [
    {
      "id":             "a1b2c3d4",
      "name":           "My Analyst",
      "hermes_url":     "https://my-hermes.up.railway.app",
      "hermes_path":    "/api/chat",
      "description":    "...",
      "is_public":      1,
      "pricing_mode":   "per_call",
      "price_per_call": "0.01",
      "created_at":     1716048000000
    }
  ]
}

PATCH /admin/agents/a1b2c3d4
x-admin-secret: <secret>

{ "pricePerCall": "0.05", "description": "Updated description" }

// 200 OK
{ "updated": true }

DELETE /admin/agents/a1b2c3d4
x-admin-secret: <secret>

// 200 OK
{ "deleted": true }

POST /admin/agents/a1b2c3d4/keys
x-admin-secret: <secret>

{ "label": "partner-1", "rateLimitPerHour": 500 }

// 201 Created
{
  "key":              "ap_ojE8S1SzH6i_rrnef7vQ-gmeR-MTd8i8xxxxxxxxxx",
  "agentId":          "a1b2c3d4",
  "label":            "partner-1",
  "rateLimitPerHour": 500
}

GET /admin/agents/a1b2c3d4/keys
x-admin-secret: <secret>

{
  "keys": [
    {
      "key":              "ap_ojE8S1SzH6i_...",
      "label":            "partner-1",
      "rate_limit_per_hour": 500,
      "is_active":        1,
      "created_at":       1716048000000
    }
  ]
}

DELETE /admin/keys/ap_ojE8S1SzH6i_rrnef7vQ-gmeR-MTd8i8xxxxxxxxxx
x-admin-secret: <secret>

// 200 OK
{ "revoked": true }

GET /admin/stats
x-admin-secret: <secret>

{
  "totalCalls":    1042,
  "totalAgents":   3,
  "totalKeys":     7,
  "successCalls":  1038,
  "successRate":   99,           // percentage, 0–100
  "avgDurationMs": 284,
  "recentCalls": [
    {
      "id":            "uuid",
      "agent_id":      "a1b2c3d4",
      "status_code":   200,
      "duration_ms":   284,
      "receipt_hash":  "sha256hex...",
      "created_at":    1716048000000
    }
  ],
  "callsByAgent": [
    { "agent_id": "a1b2c3d4", "total": 1042, "avg_ms": 284 }
  ]
}

{ "error": "Human-readable error message" }

const GATEWAY = 'https://your-gateway.vercel.app'
const API_KEY  = 'ap_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
const AGENT_ID = 'a1b2c3d4'

async function callAgent(message: string) {
  const res = await fetch(`${GATEWAY}/v1/agents/${AGENT_ID}/run`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': API_KEY,
    },
    body: JSON.stringify({
      messages: [{ role: 'user', content: message }],
    }),
  })

  if (!res.ok) {
    if (res.status === 429) throw new Error('Rate limit exceeded')
    if (res.status === 402) throw new Error('Payment required')
    throw new Error(`Agent error: ${res.status}`)
  }

  const receipt = res.headers.get('x-agentport-receipt')
  const durationMs = res.headers.get('x-agentport-duration-ms')
  const remaining  = res.headers.get('x-ratelimit-remaining')

  const body = await res.json()
  return { body, receipt, durationMs, remaining }
}

// Verify a receipt locally (no gateway trust required)
import { createHash } from 'crypto'

function verifyReceipt(encoded: string): boolean {
  const r = JSON.parse(Buffer.from(encoded, 'base64url').toString('utf8'))
  const hash = createHash('sha256')
    .update(`${r.callId}:${r.agentId}:${r.timestamp}:${r.requestHash}:${r.responseHash}`)
    .digest('hex')
  return hash === r.receiptHash
}

import requests, hashlib, base64, json

GATEWAY  = "https://your-gateway.vercel.app"
API_KEY  = "ap_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
AGENT_ID = "a1b2c3d4"

def call_agent(message: str) -> dict:
    res = requests.post(
        f"{GATEWAY}/v1/agents/{AGENT_ID}/run",
        headers={
            "Content-Type": "application/json",
            "x-api-key": API_KEY,
        },
        json={"messages": [{"role": "user", "content": message}]},
    )

    if res.status_code == 429:
        raise RuntimeError("Rate limit exceeded")
    if res.status_code == 402:
        raise RuntimeError(f"Payment required: {res.json()}")
    res.raise_for_status()

    receipt     = res.headers.get("x-agentport-receipt")
    duration_ms = res.headers.get("x-agentport-duration-ms")
    remaining   = res.headers.get("x-ratelimit-remaining")

    return {
        "body":        res.json(),
        "receipt":     receipt,
        "duration_ms": duration_ms,
        "remaining":   remaining,
    }

def verify_receipt(encoded: str) -> bool:
    r = json.loads(base64.urlsafe_b64decode(encoded + "=="))
    preimage = f"{r['callId']}:{r['agentId']}:{r['timestamp']}:{r['requestHash']}:{r['responseHash']}"
    expected = hashlib.sha256(preimage.encode()).hexdigest()
    return expected == r["receiptHash"]

# Usage
result = call_agent("What is the price of ETH?")
print(result["body"])
print("Receipt valid:", verify_receipt(result["receipt"]))

# Full round-trip: call + verify receipt
RECEIPT=$(curl -si \
  -X POST https://your-gateway.vercel.app/v1/agents/a1b2c3d4/run \
  -H "x-api-key: ap_xxx" \
  -H "Content-Type: application/json" \
  -d '{"messages":[{"role":"user","content":"Hello"}]}' \
  | grep -i "x-agentport-receipt:" | awk '{print $2}' | tr -d '\r')

# Verify the receipt
curl -X POST https://your-gateway.vercel.app/v1/receipts/verify \
  -H "Content-Type: application/json" \
  -d "{\"receipt\":\"$RECEIPT\"}" | python3 -m json.tool