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 iAgentMart-Windows
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.

While running, it also writes a token-free local discovery marker to ~/.iagentmart/discovery.json so AI tools can find the runtime without storing keys in shell history.

Installation Details

Download the latest packaged release for your platform. No Docker required for normal users.

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

Local Data

• .env.local stores local secrets and runtime configuration.
• .iagentmart-runtime/ stores the private Node.js runtime downloaded by the launcher when needed.
• plugins/ stores installed local plugin packages and copied manifests.
• prisma/dev.db is the local SQLite database for wallets, services, service calls, payments, ledger entries, and audit logs.

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.

Discovery & MCP

New local AI tools should discover iAgentMart before they receive an Agent API key:

cat ~/.iagentmart/discovery.json
curl http://localhost:3000/.well-known/iagentmart.json
curl http://localhost:3000/api/agent/v1

MCP-capable clients connect with the same Agent API key created from the local console's AI Connection flow.

curl http://localhost:3000/api/mcp \
  -H "Authorization: Bearer <agent_api_key>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

The MCP endpoint exposes search, get, call, order, payment, and dynamic iagentmart_service_* tools for installed active services. Calls still pass through wallet, budget, payment, download-risk, order-history, and audit checks.

Default MCP safety limits are 240 JSON-RPC requests per minute and 120 service calls per minute per Agent API key.

Local Runtime API Reference

REST API for the self-hosted iAgentMart runtime. These routes run in the local app/server, not in the public Cloudflare Pages website.

Local runtime routes require Authorization: Bearer with an active agent API key.

Agent Status

Checks whether the agent connection is ready to discover, buy, and call services. The response includes agent, wallet, service, payment, marketplace, and next-action readiness state.

Search Services

Search active services. Supports q, category, chainId, assetId, limit, and cursor parameters.

Get Service Detail

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

Marketplace Plugins

Search downloadable plugins in the configured marketplace. Free plugins install locally; paid or ambiguous matches return nextAction for local approval.

Call Service

Execute a service call. Requires Idempotency-Key header.

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

Submit Payment Transaction

Verify Payment

Get Payment Status

Get Budget

Get Logs

Local Automation API

Localhost-only automation routes let desktop AI tools install or remove local plugins without carrying an Agent API key. They are rate-limited and never auto-pay; paid or ambiguous matches return a local approval URL.

{
  "intent": "install",
  "query": "image converter"
}

Supported intents include install, buy, delete, remove, and uninstall. Use marketplaceServiceId when search results are ambiguous.

Read-only local service metadata for installed active free services. These routes do not call seller URLs or download seller-provided content.

Admin API

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

Agent clients also support rotate-key, pause, activate, and revoke action endpoints.

/api/seller/services is currently a seller-facing alias for the admin-protected service listing model.

Local Payment API

Manage payments, submit transaction hashes, and verify on-chain confirmations in the self-hosted runtime. These endpoints are not implemented by the hosted website marketplace API.

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

Wallet API

Create and manage local multi-address wallets. Wallet list/detail responses never return encrypted keystores; export is explicit.

Use /api/admin/wallet-security to set up and unlock the local wallet password before AI auto-payment can use signing wallets.

TypeScript SDK

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

Basic Usage

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

const discovery = await discoverIAgentMart({
  baseUrl: "http://127.0.0.1:3000",
});

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

const status = await client.getStatus();

// 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, fulfillment contract, and entry point.

V1 Profile

New manifests should target the compact V1 profile. Older manifests without manifestVersion may still be treated as V1 by local runtimes, but explicit versions must match exactly.

{
  "$schema": "https://iagentmart.com/schemas/iagentmart-manifest.v1.schema.json",
  "manifestVersion": "iagentmart.manifest.v1"
}

Required Fields

• Recommended $schema and manifestVersion=iagentmart.manifest.v1
• name, displayName, version, author, category
• permissions[] — short declared capability identifiers and descriptions. Seller text is not a safety boundary.
• pricing.type (free or per_call); free services use an empty acceptedPayments array, paid services include at least one complete pricing.acceptedPayments[] quote
• inputSchema, outputSchema — JSON Schema for validation
• fulfillment.type, fulfillment.requiredOutputFields[], and optional fulfillment.sensitiveOutput
• entry.type (mock or http), optional entry.method (GET or POST), entry.url for HTTP services. Hosted services use HTTPS; local plugin runtimes may use localhost HTTP.
• Optional runtime metadata for native local HTTP plugins: type, start, defaultPort, healthPath, endpointPath, and agentGuidePath

Accepted Payments

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

New agents should send paymentOptionId copied from paymentOptions[].id. selectedPayment is still accepted for compatibility, but mixing payment fields across options is rejected.

Local Runtime Payment Flow

The public website stores seller-declared payment options and redacts paid fulfillment URLs from public marketplace responses. The self-hosted runtime is responsible for creating payment requests, verifying chain activity, and unlocking paid service execution or downloads.

1. Agent calls POST /api/agent/v1/services/:id/call with paymentOptionId
2. Policy engine evaluates budget, derived permission gates, permissions, and wallet policy
3. If a service URL appears to return a local file or attachment, iAgentMart returns nextAction.type=confirm_service_url_download before the agent proceeds
4. If auto-pay is enabled and wallet is unlocked, payment is submitted automatically
5. Otherwise, a requires_payment response returns payment instructions
6. Agent or user submits txId via POST /api/agent/v1/payments/:id/submit-tx
7. Payment worker verifies on-chain: payer, recipient, amount, asset, finality
8. On confirmation: ledger entry created, service executed, result returned

Chain Configuration

Current open-source builds support EVM chains through eip155:* and Sui through sui:*. Solana support is temporarily disabled until its JavaScript SDK dependency risk is resolved or isolated.

Configure RPC endpoints and finality requirements via environment variables:

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

CRYPTO_REQUIRED_FINALITY={"eip155:1":"finalized","eip155:8453":"confirmed","sui: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
• Local automation endpoints are localhost-only and rate-limited
• HTTP proxy enforces HTTPS-only, blocks private IPs, prevents DNS rebinding
• Service URLs that appear to return local downloads require explicit user confirmation
• 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 local policy checks before payment or execution:

1. Agent Client exists and is active
2. Idempotency key check (replay if already processed)
3. Service exists and is active
4. Input matches the service's JSON Schema
5. Runtime-derived permission gate is within the agent's maxRiskLevel
6. Service not in blockedServiceIds
7. Service in allowedServiceIds (if set)
8. Category in allowedCategories (if set)
9. Sensitive permission types are blocked in V1, regardless of seller-provided labels
10. Free services can proceed without payment
11. Paid service payment option matches acceptedPayments
12. Selected payment chain has an active bound local wallet payer
13. Chain/asset allowed for agent
14. Per-transaction limit check
15. Daily spend limit check
16. Monthly spend limit check
17. Wallet policy and auto-pay evaluation decide whether payment is manual or automatic

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.