Documentation

API documentation

Programmatic access to AgentBuy asset discovery, previews, licensing, and x402 USDC settlement — built for autonomous AI agents.

Overview

AgentBuy exposes a Model Context Protocol (MCP) server over HTTP JSON-RPC. Agents discover assets via semantic search, evaluate free watermarked previews, purchase licenses via x402 (HTTP 402) in USDC on Solana, and receive unwatermarked delivery URLs — all without a human checkout flow.

For the full MCP tool reference, purchase flow, and examples, see the MCP documentation.

Base URL

Production: https://agentbuy.shop

Authentication

Buyer agents can call MCP search and purchase endpoints without a bearer token. Pick a stable agent id and send it on purchase requests:

Agent identity (required for purchase tools)

x-agent-identifiers: ["my-buyer-agent-v1"]
Content-Type: application/json

Search works without this header. For purchase_license, pass x-agent-identifiers or agent_identifier in tool arguments. Paid assets use x402 USDC payment to fulfill.

Internal worker routes (e.g. POST /api/mcp/upload) still require CONTENT_WORKER_SECRET as Authorization: Bearer ….

HTTP endpoints

Endpoint	Method	Purpose
/api/mcp	POST	MCP Streamable HTTP + legacy JSON-RPC (tools/list, tools/call, initialize)
/api/mcp	GET	Health check, or Streamable HTTP session (with mcp-session-id)
/api/mcp	DELETE	End Streamable HTTP session
/api/mcp/license/purchase	POST	Purchase license via x402 (402 challenge → PAYMENT-SIGNATURE → grant)
/api/mcp/invoice	POST	Legacy: create memo-based license invoice (flag off only)
/api/mcp/verify	POST	Legacy: verify memo payment and fulfill grant (flag off only)
/api/mcp/upload	POST	Ingest a new asset (worker / content pipeline)
/api/preview/[assetId]	GET	Watermarked preview proxy for agent evaluation

Optional request headers

Header	Description
x-agent-identifiers	JSON array of agent IDs, e.g. ["my-agent-v1"]. Required for purchase_license; optional for search.
x-repository-id	Scope search/usage to a specific asset repository UUID.
x-subscription-id	Associate usage with a client subscription UUID.

Typical agent workflow

Discover — call search_assets with a semantic query
Evaluate — fetch watermarked_cdn_url or thumbnail_url from search results (free)
License — call purchase_license with asset_id and license_id
Pay — for paid tiers, handle HTTP 402 and sign x402 USDC payment (retry with PAYMENT-SIGNATURE)
Fulfill — receive cdn_url and source_download_url in the grant response

CLI testing

Run a semantic search from your terminal (requires a local dev server):

npm run mcp:search -- "sunset beach warm colors"

End-to-end purchase test on Solana devnet:

npm run test:payment-e2e -- --query "sunset beach" --paid-only

Read the MCP docs →