Documentation

Everything you need to integrate Veles Protocol into your autonomous systems.

Quick Start

1. Create an Account

2. Create a Capability

Go to Console → New Capability. Link it to your note, set death conditions (time, spend ceiling), and copy the key.

vv_live_abc123def456...

3. Use in Your Agent

Set the API key as an environment variable and make HTTP calls:

export VELES_API_KEY=vv_live_abc123...

API Reference

POST/api/v1/x402

Make x402 payments through Veles Protocol. We handle 402 Payment Required negotiation via ZK-SNARK notes.

Headers

Authorization: Bearer vv_live_xxx
Content-Type: application/json

Request Body

{
  "url": "https://api.example.com/paid-endpoint",
  "method": "POST",
  "headers": { "Custom-Header": "value" },
  "body": { "prompt": "Hello world" }
}

Response

{
  "success": true,
  "status": 200,
  "data": { /* response from target API */ },
  "cost": 0.05,
  "balance": 49.95
}

Error Codes

401Invalid or missing API key

402Insufficient balance in linked note

403API key revoked or spending limit exceeded

404No note linked to API key

500Internal error (payment failed, target unreachable)

Fleet Commander API

Enable autonomous agents to manage their own swarms. Create a "commander" API key with management permissions, then use it to programmatically create worker keys, allocate budgets, and monitor fleet health.

Capabilities

✓ Create/revoke API keys programmatically

✓ Bulk create up to 500 keys at once

✓ Set spending limits per agent

✓ Track usage and fleet health

✓ Hierarchical key tracking (parent → child)

✓ Custom metadata per agent

Endpoints

GET/POST /api/v1/fleet/keys

GET/PATCH/DELETE /api/v1/fleet/keys/:id

POST/DELETE /api/v1/fleet/keys/bulk

GET/POST /api/v1/fleet/notes

GET /api/v1/fleet/stats

Create Worker Fleet

# Authenticate with commander key (must have canManage: true)
curl -X POST https://velesprotocol.xyz/api/v1/fleet/keys/bulk \
  -H "Authorization: Bearer vv_live_commander_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "tiers": [
      { "prefix": "worker", "count": 50, "spendLimitDaily": 5, "expiresAt": "7d" },
      { "prefix": "supervisor", "count": 5, "spendLimitDaily": 50 }
    ]
  }'

# Response includes all 55 keys ready for distribution
{
  "success": true,
  "count": 55,
  "keys": [
    { "name": "worker-001", "key": "vv_live_...", "tier": "worker" },
    ...
  ]
}

Full Autonomy Mode

Agents with their own wallets can be fully autonomous — no human setup required. The agent creates its own account, funds its own notes, and manages its own fleet.

Two Paths to Autonomy

Path A: Agent Creates Account

• Agent has its own wallet
• Uses /api/v1/auth/wallet to register
• Gets commander key automatically
• Funds notes via API

Path B: Operator Links Wallet

• Sign up with email first
• Link wallet via /api/auth/link-wallet
• Create commander key in dashboard
• Agent uses same Fleet API

Requirements

• Agent has access to a wallet private key
• Agent wallet holds USDC on supported chains
• Agent has @prxvt/sdk installed for on-chain deposits

Bootstrap Flow

1. GET /api/v1/auth/wallet?address=0x... → Get nonce

2. Sign SIWE message with wallet

3. POST /api/v1/auth/wallet → Get commander API key

4. Use @prxvt/sdk to deposit USDC on-chain

5. POST /api/v1/fleet/notes/deposit → Store funded note

6. Create worker keys, manage fleet, make payments

Full Autonomy Bootstrap (Node.js)

import { SiweMessage } from 'siwe';
import { ethers } from 'ethers';
import { deposit, encryptNote } from '@prxvt/sdk';

const WALLET_PRIVATE_KEY = process.env.AGENT_WALLET_KEY;
const wallet = new ethers.Wallet(WALLET_PRIVATE_KEY);

// 1. Get nonce
const nonceRes = await fetch(`https://velesprotocol.xyz/api/v1/auth/wallet?address=${wallet.address}`);
const { nonce } = await nonceRes.json();

// 2. Create and sign SIWE message
const siweMessage = new SiweMessage({
  domain: 'velesprotocol.xyz',
  address: wallet.address,
  statement: 'Sign in to Veles Protocol',
  uri: 'https://velesprotocol.xyz',
  version: '1',
  chainId: 1,
  nonce,
});
const message = siweMessage.prepareMessage();
const signature = await wallet.signMessage(message);

// 3. Authenticate and get commander key
const authRes = await fetch('https://velesprotocol.xyz/api/v1/auth/wallet', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ message, signature }),
});
const { commanderKey } = await authRes.json();
console.log('Commander key:', commanderKey.key);

// 4. Deposit USDC on-chain (requires wallet to have USDC)
const notePassword = crypto.randomUUID();
const { encrypted, balance } = await deposit('base-sepolia', 100, WALLET_PRIVATE_KEY, notePassword);

// 5. Store the funded note
const noteRes = await fetch('https://velesprotocol.xyz/api/v1/fleet/notes/deposit', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${commanderKey.key}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    label: 'Agent Budget',
    chain: 'base-sepolia',
    userEncryptedNote: encrypted,
    notePassword,
    balance,
  }),
});
const { note } = await noteRes.json();

// 6. Create worker keys
const keyRes = await fetch('https://velesprotocol.xyz/api/v1/fleet/keys', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${commanderKey.key}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'worker-001',
    noteId: note.id,
    spendLimitDaily: 10,
    expiresAt: '7d',
  }),
});

console.log('Agent is now fully autonomous! 🚀');

Code Examples

Python

import requests
import os

API_KEY = os.environ["VELES_API_KEY"]

response = requests.post(
    "https://velesprotocol.xyz/api/v1/x402",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "url": "https://ai-api.example.com/chat",
        "method": "POST",
        "body": {"prompt": "Summarize this document"}
    }
)

result = response.json()
print(f"Response: {result['data']}")
print(f"Cost: {result['cost']} USDC")

JavaScript / Node.js

const response = await fetch("https://velesprotocol.xyz/api/v1/x402", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.VELES_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    url: "https://ai-api.example.com/chat",
    method: "POST",
    body: { prompt: "Summarize this document" }
  })
});

const { data, cost, balance } = await response.json();
console.log(`Response: ${data}`);
console.log(`Cost: $${cost}, Remaining: $${balance}`);

cURL

curl -X POST https://velesprotocol.xyz/api/v1/x402 \
  -H "Authorization: Bearer vv_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://ai-api.example.com/chat",
    "method": "POST",
    "body": {"prompt": "Hello"}
  }'

Security Model

Worker Key Capabilities

• API key (vv_live_xxx)
• Make x402 payment calls
• Subject to spending limits
• Can be revoked instantly
• Time-bound expiration

Commander Key Capabilities

• All worker capabilities, plus:
• Create/revoke child keys
• Manage spending notes
• View fleet statistics
• Bulk operations

What Agents Never Have Access To

• Raw spending note data
• Note encryption passwords
• Wallet private keys

• On-chain fund transfers
• Account deletion
• Subscription management