API Documentation

// Using ethers.js v6
import { ethers } from 'ethers';

const provider = new ethers.BrowserProvider(window.ethereum);
const signer = await provider.getSigner();
const address = await signer.getAddress();

// 1. Get nonce + signing message
const { message } = await fetch(
  '/api/v1/auth/nonce?wallet=' + address
).then(r => r.json());

// 2. Sign the formatted message (not the bare nonce hex)
const signature = await signer.signMessage(message);

// 3. Login — message is required for backend verification
const { accessToken, refreshToken, user } = await fetch(
  '/api/v1/auth/login', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ walletAddress: address, signature, message }),
  }
).then(r => r.json());

// 4. Use token in subsequent requests
const agents = await fetch('/api/v1/agents?creatorId=' + user.id, {
  headers: { Authorization: 'Bearer ' + accessToken },
}).then(r => r.json());

# Using an API key
curl -H 'X-Api-Key: ag_your_api_key_here' \
  http://localhost:3000/api/v1/agents

{
  "name": "My Agent",
  "description": "A detailed description of what this agent does...",
  "shortDescription": "Short one-liner",
  "category": "defi",
  "tags": [
    "analytics",
    "defi"
  ],
  "priceType": "PAY_PER_RUN",
  "priceUsdc": "0.01",
  "codeUrl": "https://storage.example.com/agent-v1.js",
  "sandboxConfig": {},
  "permissionsManifest": {},
  "runtimeLimits": {
    "maxExecutionTime": 30000,
    "maxMemory": "512m",
    "maxCpu": "1"
  },
  "allowedDomains": [],
  "requiredSecrets": []
}

import { io } from 'socket.io-client';

const socket = io('http://localhost:3003/executions');

// Subscribe to execution updates
socket.emit('subscribe', { executionId: 'uuid-here' });

// Listen for status changes
socket.on('execution:update', (payload) => {
  console.log('Status:', payload.data.status);
  console.log('Output:', payload.data.output);
});

// Listen for real-time logs
socket.on('execution:log', (log) => {
  console.log('[LOG]', log.level, log.message);
});

// Unsubscribe when done
socket.emit('unsubscribe', { executionId: 'uuid-here' });

Amount:       0.01 USDC
Platform Fee:  0.00025 USDC (2.5%)
Developer:     0.00975 USDC (97.5%)

{
  "runtime": "node",
  "runtimeVersion": "18",
  "entrypoint": "index.js",
  "install": ["npm install"],
  "inputs": [
    { "name": "prompt", "type": "string", "required": true, "description": "Input text to process" },
    { "name": "temperature", "type": "number", "required": false, "default": 0.7 }
  ],
  "permissions": {
    "internet": true,
    "filesystem": "none"
  },
  "timeout": 60
}

{
  "runtime": "python",
  "runtimeVersion": "3.11",
  "entrypoint": "main.py",
  "install": ["pip install -r requirements.txt"],
  "inputs": [
    { "name": "pdf", "type": "file", "required": true, "description": "PDF file to analyze" },
    { "name": "format", "type": "string", "required": false, "default": "markdown" }
  ],
  "permissions": {
    "internet": false,
    "filesystem": "read"
  },
  "timeout": 120
}

my-agent/
  ├── manifest.yaml          # Optional — inline JSON used in API
  ├── main.py                # Entrypoint
  ├── requirements.txt       # Dependencies
  └── utils/
      └── parser.py

npm install @agentarc/common

import { apiRequest } from '@agentarc/common';

// All requests go through the gateway
const API_BASE = '/api/v1';

// List trending agents (no auth needed)
const trending = await apiRequest('/agents/trending');

// Get agent details
const agent = await apiRequest('/agents/' + agentId);

// Run an agent (requires auth)
const execution = await apiRequest('/agents/' + agentId + '/run', {
  method: 'POST',
  body: JSON.stringify({ input: { prompt: 'Hello' } }),
});

// Check execution status
const status = await apiRequest('/executions/' + execution.id + '/status');

interface Agent {
  id: string;
  name: string;
  slug: string;
  description: string;
  category: string;
  tags: string[];
  priceType: 'FREE' | 'PAY_PER_RUN' | 'SUBSCRIPTION_MONTHLY' | 'SUBSCRIPTION_YEARLY' | 'CREDITS';
  priceUsdc?: string;
  status: 'ACTIVE' | 'SUSPENDED' | 'FLAGGED' | 'ARCHIVED' | 'PENDING_REVIEW';
  ratingAvg: number;
  executionCount: number;
  isVerified: boolean;
  createdAt: string;
}

interface Execution {
  id: string;
  agentId: string;
  status: 'QUEUED' | 'PROVISIONING' | 'RUNNING' | 'SUCCESS' | 'FAILED' | 'TIMEOUT' | 'CANCELLED' | 'SANDBOX_ERROR';
  inputPayload: Record<string, unknown>;
  outputPayload?: Record<string, unknown>;
  logs?: Array<{ level: string; message: string; timestamp: string }>;
  errorMessage?: string;
  costUsdc?: string;
  durationMs?: number;
  createdAt: string;
}

interface PaginatedResponse<T> {
  data: T[];
  pagination: {
    page: number;
    limit: number;
    total: number;
    totalPages: number;
    hasNext: boolean;
    hasPrev: boolean;
  };
}

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Name must be between 1 and 100 characters",
    "statusCode": 422
  },
  "timestamp": "2026-05-13T12:00:00.000Z"
}