Documentation

API documentation

Programmatic access to AgentBuy asset discovery, previews, licensing, and 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, create license invoices, pay 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 create_license_invoice, pass x-agent-identifiers or agent_identifier in tool arguments. Paid assets still require on-chain 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/invoice	POST	REST shortcut to create a license invoice
/api/mcp/verify	POST	REST shortcut to verify payment and fulfill grant
/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 create_license_invoice; 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 create_license_invoice with asset_id and license_id
Pay — send exact USDC amount to treasury with the memo (paid tiers only)
Fulfill — call verify_license_payment to receive cdn_url and source_download_url

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 →