LIVE API v1

Agent API Documentation

A fully public REST API for AI agents and developers to search, discover, and license music from the OnChain Music catalog.

            Base URL
            https://onchainmusic.com/api/v1/agent
        

📡
Overview

The OnChain Music Agent API gives AI agents and developers full access to search and license music from our catalog of 5,000+ fully cleared tracks. All catalog endpoints are public — no API key required. Licensing is gated by USDC payment on the Base blockchain.

✓ All catalog search and discovery endpoints are fully public — no API key, no account, no authentication required.

🔓
Authentication

No authentication is required to search the catalog. Licensing is payment-gated — agents verify payment by sending USDC on Base from a specified wallet address. The API verifies on-chain transfers automatically using Alchemy. No API keys, no OAuth, no account needed.

⚡
Rate Limits

Endpoint Group	Limit	Window
Catalog Search	60 requests	per minute / per IP
AI Search	60 requests	per minute / per IP
License Initiation	10 requests	per minute / per IP

💎
Payments (USDC on Base)

All licenses are purchased with USDC on Base (chain ID 8453). No memo or calldata is required. Payments are verified by matching the sender's wallet address to on-chain USDC transfers sent to the platform wallet.

Network

Base Mainnet

Chain ID

8453

Token

USDC

USDC Contract

0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913

Receiving Wallet

0x86ACb1Beb5283aBB1E15C852178C0E5e881a10bD

⚠ Always send payment from the same wallet address you provide to the license endpoint. Verification matches by sender address — no memo or transaction hash needed.

🔍
Catalog Endpoints

GET /catalog/search Search the full catalog

Search 5,000+ fully cleared tracks available for sync licensing. All results include pricing, preview links, and license purchase URLs. The API applies smart fallback logic — if your filters return zero results, it automatically broadens the search to always return something useful.

Query Parameters

Parameter	Type	Required	Description
description	string	recommended	Primary search field. Pass descriptive style, mood, energy, or use-case words. Each word is searched individually across Description, Keywords, Category, and more. Example: `epic orchestral trailer`
genre	string	optional	Exact genre match. Values: Rock, Hip Hop, Electronica, Orchestral, Jazz, Country, Pop, Cinematic, Ambient, Folk, R&B, Soul, Blues, Funk, Latin, World, Classical, Electronic, Holiday
subgenre	string	optional	Subgenre filter (e.g. Indie, Contemporary)
instrumental	Yes / No	optional	`Yes` = no vocals `No` = has vocals
bpm_min	integer	optional	Minimum BPM (1–300)
bpm_max	integer	optional	Maximum BPM (1–300)
tempo	string	optional	Tempo label (e.g. Medium, Fast, Slow)
key	string	optional	Key signature (e.g. C Maj, A min)
keywords	string	optional	Search the Keywords field directly
per_page	integer	optional	Results per page (default: 20, max: 50)
page	integer	optional	Page number for pagination. Vary this for result variety.

💡 Always use description as the primary search field for style-based queries. Mood and energy words (upbeat, dark, epic) belong in description. Never use a separate mood parameter.

Example Request

curl

curl "https://onchainmusic.com/api/v1/agent/catalog/search?description=epic+orchestral+trailer&genre=Orchestral&instrumental=Yes&per_page=5"

Example Response

json

{
  "data": [
    {
      "id": 417,
      "title": "Chase the Sunshine Full",
      "duration": "3:40",
      "artists": [{ "id": 239, "name": "Evgeny Kiselevich" }],
      "genre": "Rock",
      "subgenre": "Indie",
      "bpm": 120,
      "instrumental": true,
      "description": "Anthemic, Excited, Lively, Euphoric...",
      "artwork_url": "https://onchainmusic-audio.s3...",
      "preview_url": "https://onchainmusic.com/epitome-music/aspire/chase-the-sunshine-full",
      "formats_available": { "mp3": true, "wav": true, "aif": true },
      "license_purchase_url": "https://onchainmusic.com/api/v1/agent/license/417/social_media"
    }
  ],
  "meta": {
    "total": 168,
    "per_page": 5,
    "current_page": 1,
    "last_page": 34,
    "fallback": false
  }
}

ℹ When meta.fallback is true, the API relaxed your filters to return results. Tell the user: "Here are the closest matches I found."

GET /catalog/tracks/{id} Get a single track

Retrieve full metadata and pricing for a single track by its ID. Returns all available format info, license options, and the direct preview URL.

Path Parameters

Parameter	Type	Required	Description
id	integer	required	Track ID from a catalog search result

Example Request

curl

curl "https://onchainmusic.com/api/v1/agent/catalog/tracks/417"

POST /ai-search Natural language music search

Send a plain English description of the music you need. GPT-4o-mini translates the phrase into structured search parameters, then runs the catalog search internally. Returns the same response as /catalog/search plus an ai object showing the translation.

Request Body (JSON)

Field	Type	Required	Description
phrase	string	required	Natural language music description. Example: "I need an upbeat indie rock track for a TV commercial"
per_page	integer	optional	Results per page (default: 10)

Example Request

curl

curl -X POST "https://onchainmusic.com/api/v1/agent/ai-search" \
  -H "Content-Type: application/json" \
  -d '{"phrase": "epic orchestral trailer music with vocals", "per_page": 5}'

AI Translation Object in Response

json

{
  "data": [ /* same structure as /catalog/search */ ],
  "meta": { /* pagination */ },
  "ai": {
    "original_phrase": "epic orchestral trailer music with vocals",
    "translated_params": {
      "genre": "Orchestral",
      "description": "epic orchestral cinematic trailer vocals",
      "instrumental": "No"
    }
  }
}

🛒
Licensing Endpoints

💡 The full licensing flow: Initiate → Send USDC on Base → Poll Verify → Receive License Document + Download URLs. No account required — just a Base wallet.

1. POST /license/{id}/{type}

→

2. Send USDC on Base

→

3. GET /license/verify/{payment_id}

→

4. Download Files

POST /license/{track_id}/{license_type} Initiate a license purchase

Initiates a license for a specific track. Returns payment instructions including the USDC amount and receiving wallet address. Send the payment on Base then poll the verify endpoint.

Path Parameters

Parameter	Type	Required	Description
track_id	integer	required	Track ID from catalog search
license_type	string	required	`social_media` or `all_digital`

Query Parameters

Parameter	Type	Required	Description
paying_wallet	string	required	The Base wallet address that will send the USDC payment
mode	string	optional	Pass `gpt` when calling from a ChatGPT GPT to receive a 200 response instead of 402

Response Codes

Status	Meaning
402	Payment required. Response includes payment_id, amount_usdc, and receiving_wallet
200	Returned when `?mode=gpt` is passed. Same payment info, ChatGPT-compatible

Example Request

curl

curl -X POST "https://onchainmusic.com/api/v1/agent/license/417/social_media?paying_wallet=0xYourWalletAddress&mode=gpt"

Example Response

json

{
  "payment_id": "pay_abc123",
  "amount_usdc": "5.00",
  "receiving_wallet": "0x86ACb1Beb5283aBB1E15C852178C0E5e881a10bD",
  "network": "base",
  "chain_id": 8453,
  "token": "USDC",
  "instructions": "Send 5.00 USDC on Base from your wallet. No memo needed.",
  "verify_url": "https://onchainmusic.com/api/v1/agent/license/verify/pay_abc123"
}

GET /license/verify/{payment_id} Poll for license status

Poll this endpoint after sending payment. Once the USDC transfer is detected on-chain, the license is issued and this endpoint returns a signed license document and download URLs for all available audio formats.

Example Response (license issued)

json

{
  "license_issued": true,
  "license_type": "social_media",
  "track_id": 417,
  "track_title": "Chase the Sunshine Full",
  "amount_paid": "5.00",
  "currency": "USDC",
  "download_urls": {
    "mp3": "https://onchainmusic-audio.s3...",
    "wav": "https://onchainmusic-audio.s3...",
    "aif": "https://onchainmusic-audio.s3..."
  },
  "license_document_url": "https://onchainmusic-audio.s3.../license_417_pay_abc123.json"
}

⏱ Poll every 5–10 seconds. Verification typically completes within 30–60 seconds of the transaction confirming on Base. Stop polling after 5 minutes if no license is issued.

💰
License Pricing

Social Media License

$5 USDC

Non-commercial creator use on social platforms

TikTok
Instagram Reels
YouTube (non-monetized)
X / Twitter
Facebook

All Digital License

$35 USDC

Full commercial digital use

Online advertising
Mobile apps & games
Podcasts & streaming
Websites & digital media
Commercial YouTube

All licenses are perpetual, non-exclusive, and worldwide. License documents are cryptographically signed with HMAC-SHA256 and stored on S3.

🌐
Agent Discovery

GET /.well-known/agent.json Agent discovery manifest

Standard agent discovery endpoint. Returns capabilities, preferred flows, payment networks, and links to the OpenAPI spec.

url

https://onchainmusic.com/.well-known/agent.json

GET /api/docs/openapi.json OpenAPI 3.1 specification

Full OpenAPI 3.1.0 specification. Used by the ChatGPT GPT Store and compatible with any OpenAPI-aware agent framework.

urls

https://onchainmusic.com/api/docs/openapi.json
https://onchainmusic.com/api/docs/openapi.yaml

GET /llms.txt LLM context file

Plain text file following the llms.txt standard. Provides LLMs with a concise description of the OnChain Music platform and API for use in system prompts and context windows.

url

https://onchainmusic.com/llms.txt

🤖
ChatGPT GPT

OnChain Music has a published GPT in the ChatGPT GPT Store that provides a conversational interface for music discovery and licensing. Users can describe the music they need in plain English and the GPT handles search, recommendations, and USDC payment guidance.

✓ Search for "OnChain Music Licensing" in the ChatGPT GPT Store to try it directly.

💡 When building your own GPT or agent integration, always append ?mode=gpt to license endpoint calls to receive a 200 response instead of 402 — required for ChatGPT tool call compatibility.

OnChain Music Agent API v1 — All tracks fully cleared for sync licensing ← Back to Search

Agent API Documentation

📡
Overview

🔓
Authentication

⚡
Rate Limits

💎
Payments (USDC on Base)

🔍
Catalog Endpoints

🛒
Licensing Endpoints

💰
License Pricing

Social Media License

All Digital License

🌐
Agent Discovery

🤖
ChatGPT GPT

Social

Customer Service

OnChain Music

Developers & AI

Partners

Agent API Documentation

📡 Overview

🔓 Authentication

⚡ Rate Limits

💎 Payments (USDC on Base)

🔍 Catalog Endpoints

🛒 Licensing Endpoints

💰 License Pricing

Social Media License

All Digital License

🌐 Agent Discovery

🤖 ChatGPT GPT

Social

Customer Service

OnChain Music

Developers & AI

Partners

Agreement

Download Track

📡
Overview

🔓
Authentication

⚡
Rate Limits

💎
Payments (USDC on Base)

🔍
Catalog Endpoints

🛒
Licensing Endpoints

💰
License Pricing

🌐
Agent Discovery

🤖
ChatGPT GPT