Documentation

Welcome to the iAgentMart developer documentation. This guide covers installation, API usage, service manifests, and the payment flow for integrating external AI agents.

Quick Start

Get iAgentMart running in under a minute:

macOS

tar -xzf iAgentMart-macOS.tar.gz && cd iagentmart-macos
./iAgentMart-macOS.command

Linux

tar -xzf iAgentMart-Linux.tar.gz && cd iagentmart-linux
./iAgentMart-Linux.sh

Windows (PowerShell)

Expand-Archive -Force iAgentMart-Windows.zip -DestinationPath .
cd iAgentMart-Windows\iagentmart-windows
powershell -ExecutionPolicy Bypass -File .\iAgentMart-Windows.ps1

The launcher creates .env.local, initializes SQLite, and starts the server at http://127.0.0.1:3000.

Installation Details

Download the latest release from GitHub Releases. No Docker required.

Requirements

• Internet access on first run (for Node.js runtime download if needed)
• At least 4 GB RAM recommended for first-time setup
• Node.js 20.19.0+ (auto-downloaded if missing)

Optional Flags

./iAgentMart-macOS.command --port=3108 --hostname=127.0.0.1
./iAgentMart-Linux.sh --no-worker
./iAgentMart-Linux.sh --no-open

Configuration

iAgentMart uses environment variables in .env.local (auto-generated on first run):

Authentication

iAgentMart uses two authentication models:

Agent API Keys

External agents authenticate with Authorization: Bearer <agent_api_key>. Keys are generated once and stored as hashes.

curl -H "Authorization: Bearer am_your_key_here" \
  http://127.0.0.1:3000/api/agent/v1/services/search

Admin Authentication

The local console uses a password set on first run. The internal ADMIN_TOKEN protects admin API routes.

Agent API Reference

REST API for external AI agents. All routes require Authorization: Bearer with an active agent API key.

Search Services

Search the service marketplace. Supports q, category, limit, and cursor parameters.

Get Service Detail

Returns service details including paymentOptions[] with chain, asset, amount, and recipient info.

Call Service

Execute a service call. Requires Idempotency-Key header.

{
  "input": { "prompt": "hello" },
  "paymentOptionId": "opt_base_usdc_001"
}

Submit Payment Transaction

Get Payment Status

Get Budget

Get Logs

Admin API

Administrative endpoints for managing the local instance. Require admin bearer authorization.

Payment API

Manage payments, submit transaction hashes, and verify on-chain confirmations.

{
  "txId": "0xabc123...",
  "chainId": "eip155:8453",
  "assetId": "eip155:8453/erc20:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "verifyNow": true
}

Wallet API

Create and manage local multi-address wallets.

TypeScript SDK

The IAgentMartClient provides a type-safe interface for AI agents.

Basic Usage

import { IAgentMartClient } from "./iagentmart-client";

const client = new IAgentMartClient({
  baseUrl: "http://127.0.0.1:3000",
  apiKey: "am_your_key",
});

// Search services
const { services } = await client.searchServices();

// Auto-pay and call
const result = await client.callServiceAuto({
  serviceId: services[0].id,
  input: { prompt: "analyze this data" },
  paymentPreference: { assetSymbol: "USDC" },
});

Admin Client

import { IAgentMartAdminClient } from "./iagentmart-client";

const admin = new IAgentMartAdminClient({
  baseUrl: "http://127.0.0.1:3000",
  adminToken: process.env.ADMIN_TOKEN,
});

const wallets = await admin.listWallets();
const payments = await admin.listPayments({ status: "submitted" });

Service Manifests

Services are defined by machine-readable JSON manifests. A manifest declares the service's identity, pricing, permissions, schemas, and entry point.

Required Fields

• name, displayName, version, author, category, riskLevel
• permissions[] — from the allowed permission list
• pricing.type (free or per_call) and pricing.acceptedPayments[]
• inputSchema, outputSchema — JSON Schema for validation
• fulfillment.type, fulfillment.requiredOutputFields[]
• entry.type (mock or http), entry.url, entry.method

Accepted Payments

{
  "acceptedPayments": [
    {
      "chainId": "eip155:8453",
      "assetId": "eip155:8453/erc20:0x833589fCD...",
      "assetSymbol": "USDC",
      "assetDecimals": 6,
      "amountBaseUnits": "1000000",
      "recipientAddress": "0xYourAddress..."
    }
  ]
}

Payment Flow

1. Agent calls POST /api/agent/v1/services/:id/call with paymentOptionId
2. Policy engine evaluates budget, risk, permissions, and wallet policy
3. If auto-pay is enabled and wallet is unlocked, payment is submitted automatically
4. Otherwise, a requires_payment response returns payment instructions
5. Agent or user submits txId via POST /api/payments/:id/submit-tx
6. Payment worker verifies on-chain: payer, recipient, amount, asset, finality
7. On confirmation: ledger entry created, service executed, result returned

Chain Configuration

Configure RPC endpoints and finality requirements via environment variables:

CRYPTO_RPC_URLS={"eip155:1":"https://eth-rpc.example","eip155:8453":"https://base-rpc.example","solana:mainnet":"https://solana-rpc.example"}

CRYPTO_REQUIRED_FINALITY={"eip155:1":"finalized","eip155:8453":"confirmed","solana:mainnet":"confirmed"}

Supported Chain Namespaces

Security Model

• Private keys never leave the local machine; stored encrypted with scrypt-derived keys
• Agents cannot access private keys or bypass the policy engine
• Wallet must be unlocked by the user before AI auto-payment is allowed
• HTTP proxy enforces HTTPS-only, blocks private IPs, prevents DNS rebinding
• Seller output is never trusted for payment authorization
• All idempotency enforced via unique constraints on txId and idempotency keys

Policy Engine

Every service call passes through a 17-step evaluation pipeline:

1. Agent Client exists and is active
2. Idempotency key check (replay if already processed)
3. Service exists and is active
4. Risk level within agent's maxRiskLevel
5. Service not in blockedServiceIds
6. Service in allowedServiceIds (if set)
7. Category in allowedCategories (if set)
8. Critical permissions check (e.g., shell_exec blocked by default)
9. HTTP endpoint enabled, HTTPS, not in blocked ranges
10. Payment option matches acceptedPayments
11. Chain/asset allowed for agent
12. Per-transaction limit check
13. Daily spend limit check
14. Wallet policy and auto-pay evaluation

FAQ

Is iAgentMart a hosted service?

No. iAgentMart is fully self-hosted. It runs on your machine, uses your local SQLite database, and manages your own wallet keys.

Does it support fiat payments?

V1 is crypto-only. No credit cards, Stripe, PayPal, or bank transfers. USDC/USDT stablecoins are the recommended payment method.

Can agents access my private keys?

No. Agents interact through the policy engine and never have direct access to wallet keys. Keys are encrypted locally and require user-initiated unlock.

What happens if a service fails after payment?

The call is recorded as service_failed. Admins can retry the service execution without re-confirming payment. V1 does not provide automated refunds.

Can I use my own RPC endpoints?

Yes. Configure CRYPTO_RPC_URLS with your preferred RPC providers for each chain.