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 lets AI agents and developers search and license music from our catalog of 8,700+ fully cleared songs, plus partner catalogs. Personal (non-commercial) licenses cover social media and digital use, and business licenses come from the full rate card: branded social media, commercials, film, television, trailers, and more. Catalog endpoints are public. Licenses are paid in USDC on Base.

✓ Search and discovery endpoints are fully public: no API key, no account, no authentication.

🔓
Authentication

No authentication is required. Licensing is payment-gated: you declare the Base wallet you will pay from, send the exact USDC amount, and the API confirms the transfer on-chain. No API keys, no OAuth, no account.

⚡
Rate Limits

Endpoint Group	Limit	Window
Catalog Search, Get Track	60 requests	per minute / per IP
AI Search	60 requests	per minute / per IP
Licensing (options, license, verify)	10 requests	per minute / per IP

💎
Payments (USDC on Base)

Licenses are paid in USDC on Base (chain ID 8453). Prices are in USD and paid as the same amount of USDC. No memo or calldata is needed: the payment is matched by the sending wallet and the exact amount, and must arrive within 15 minutes of starting the license.

Network

Base Mainnet

Chain ID

8453

Token

USDC

USDC Contract

0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913

Receiving Wallet

0x86ACb1Beb5283aBB1E15C852178C0E5e881a10bD

⚠ Send exactly the amount in the payment response, from the same wallet you gave as paying_wallet. A different wallet, amount, or network can't be matched to your license.

🔍
Catalog Endpoints

GET /catalog/search Search the full catalog

Search 8,700+ songs plus partner catalogs. Each result includes metadata, an MP3 preview, available formats, and a license URL. The response also includes a results_url that opens every match on onchainmusic.com. If your filters return nothing, the API broadens the search and sets meta.fallback.

Query Parameters

Parameter	Type	Required	Description
description	string	recommended	Primary search field. Pass 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	Genre. Values include 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 (for example Indie, Contemporary)
instrumental	Yes / No	optional	`Yes` = no vocals `No` = has vocals
bpm_min	integer	optional	Minimum BPM (1 to 300)
bpm_max	integer	optional	Maximum BPM (1 to 300)
tempo	string	optional	Tempo label (for example Medium, Fast, Slow)
key	string	optional	Key signature (for example 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

💡 Use description as the primary search field. Mood and energy words (upbeat, dark, epic) belong in description, not 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",
      "source": "onchain",
      "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-audio.s3.../mp3s/...",
      "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,
    "sources": { "onchain": 150, "partner": 18 },
    "results_url": "https://onchainmusic.com/agent/results?s=..."
  }
}

ℹ Track ids are strings: "417" for OnChain Music tracks, "partner_82" for partner tracks. Always pass them exactly as returned. When meta.fallback is true, tell the user these are the closest matches.

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

Full metadata for one track, with standard license pricing and available formats.

Path Parameters

Parameter	Type	Required	Description
id	string	required	Track id from search, for example `417` or `partner_82`

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. The API translates it into structured search parameters and runs the catalog search. 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, as the user wrote it. 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 and results_url */ },
  "ai": {
    "original_phrase": "epic orchestral trailer music with vocals",
    "translated_params": {
      "genre": "Orchestral",
      "description": "epic orchestral cinematic trailer vocals",
      "instrumental": "No"
    }
  }
}

🛒
Licensing Endpoints

1. Personal or business?

→

2. POST with paying_wallet

→

3. Send USDC on Base

→

4. GET /license/verify/{payment_id}

→

5. Download files + agreement

💡 First ask whether the license is personal (non-commercial) or business. Personal: license with social_media or all_digital. Business: get the license options for the track, then license with the rate card endpoint.

⚖ Starting a license accepts the license agreement at the terms_url in the response. Answers about sensitive content or remixing never block a license; they're printed on the agreement, and those uses still need written approval. Only tracks whose artists opted in to AI agent licensing can be licensed through this API.

GET /license/options The rate card

License options with prices. personal lists the non-commercial licenses. business is the rate card, organized as medium, category, territory, and term, with prices by tier. With track_id, it also says whether that track can be licensed and adds price_usd, the track's exact price, to every option.

Query Parameters

Parameter	Type	Required	Description
track_id	string	optional	Track id from search. Adds that track's prices.

Example Request

curl

curl "https://onchainmusic.com/api/v1/agent/license/options?track_id=417"

Example Response

json

{
  "personal": [
    { "license_type": "social_media", "name": "Social Media", "price_usd": 10 },
    { "license_type": "all_digital", "name": "All Digital", "price_usd": 35 }
  ],
  "business": [
    {
      "medium": "Commercials",
      "description": "TV, radio, and online advertising campaigns",
      "categories": [
        {
          "category": "Online",
          "territories": [
            {
              "territory": "Worldwide",
              "terms": [
                {
                  "term": "1 Year",
                  "term_months": 12,
                  "allows_custom_term": true,
                  "tier_prices_usd": { "1": 500, "2": 750, "3": 1000 },
                  "price_usd": 750
                }
              ]
            }
          ]
        }
      ]
    }
  ],
  "track": { "id": "417", "licensable": true, "message": null }
}

Example values only. Live prices come from the endpoint.

POST /license/{track_id}/{license_type} Personal (non-commercial) license

Starts a personal (non-commercial) license and returns payment instructions: the payment_id, exact USDC amount, receiving wallet, and terms_url.

Path Parameters

Parameter	Type	Required	Description
track_id	string	required	Track id from search, for example `417` or `partner_82`
license_type	string	required	`social_media` ($10) or `all_digital` ($35)

Request Body (JSON)

Field	Type	Required	Description
paying_wallet	string	required	The Base wallet the USDC will be sent from
licensee_name	string	optional	Person or company that will hold the license. Printed on the agreement.
project_title	string	optional	Project or production title. Printed on the agreement.
usage	string	optional	How the music will be used
email	string	optional	Receives the license email with download links
country	string	optional	Two-letter country code of the licensee. Some partner tracks are country-restricted.

Query Parameters

Parameter	Type	Required	Description
mode	string	optional	Pass `gpt` to receive 200 instead of 402, for clients that can't read 402 responses

Response Codes

Status	Meaning
402	Payment required, with payment instructions
200	Same payment instructions, when `?mode=gpt` is passed
409	This track is licensed by custom quote only
422	Validation error, or the track isn't available for AI agent licensing

Example Request

curl

curl -X POST "https://onchainmusic.com/api/v1/agent/license/417/social_media" \
  -H "Content-Type: application/json" \
  -d '{"paying_wallet": "0xYourWalletAddress", "email": "[email protected]"}'

Example Response (402)

json

{
  "status": "payment_required",
  "payment": {
    "x402Version": "2",
    "accepts": [{ "scheme": "exact", "network": "base", "payTo": "0x86ACb1Beb5283aBB1E15C852178C0E5e881a10bD", "maxAmountRequired": "5000000" }],
    "payment_id": "OCM-Q000123",
    "expires_at": "2026-10-26T16:39:40-07:00",
    "payment_details": {
      "chain": "base",
      "chain_id": 8453,
      "token": "USDC",
      "receiving_address": "0x86ACb1Beb5283aBB1E15C852178C0E5e881a10bD",
      "amount_usdc": 10,
      "paying_wallet": "0xyourwalletaddress"
    },
    "track": { "id": "417", "title": "Chase the Sunshine Full", "license_type": "social_media" },
    "license": { "medium": "Social Media", "category": "Creator Content", "territory": "Worldwide", "term": "Perpetual" },
    "terms_url": "https://onchainmusic.com/licenses/quotes/OCM-Q000123/agreement-preview?...",
    "verify_url": "https://onchainmusic.com/api/v1/agent/license/verify/OCM-Q000123"
  }
}

POST /license/quote Business license from the rate card

Starts a business license for any option in the business list from /license/options. The price depends on the track's tier. Responses are the same as the personal license endpoint.

Request Body (JSON)

Field	Type	Required	Description
licensee_type	string	optional	business (default) or personal
track_id	string	required	Track id from search
medium	string	required	From /license/options, for example Commercials
category	string	required	From /license/options
territory	string	required	From /license/options
term	string	required	From /license/options, for example 1 Year
custom_months	integer	optional	1 to 36, only where allows_custom_term is true. Priced in proportion to the 1 Year price.
paying_wallet	string	required	The Base wallet the USDC will be sent from
licensee_name, project_title, usage, email, country	string	optional	Same as the standard license endpoint

Example Request

curl

curl -X POST "https://onchainmusic.com/api/v1/agent/license/quote" \
  -H "Content-Type: application/json" \
  -d '{"track_id": "417", "medium": "Commercials", "category": "Online", "territory": "Worldwide", "term": "1 Year", "paying_wallet": "0xYourWalletAddress", "licensee_name": "Acme Inc.", "project_title": "Spring Campaign"}'

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

Poll after sending payment. Once the USDC transfer is confirmed on Base, the license is issued and this endpoint returns the license number, download links for every available format, the license agreement PDF, and a signed license document.

Response Codes

Status	Meaning
200	License issued
202	Waiting for payment (`awaiting_payment`), or preparing the license (`payment_confirmed`)
410	The payment window expired. Start a new license.

Example Response (license issued)

json

{
  "status": "license_issued",
  "payment_id": "OCM-Q000123",
  "license_number": "OCM-L000123",
  "issued_at": "2026-10-26T16:26:06-07:00",
  "license_document": {
    "license_id": "OCM-L000123",
    "licensor": "OnChain Music, LLC",
    "track": { "id": "417", "title": "Chase the Sunshine Full", "artist": "Evgeny Kiselevich" },
    "license": { "medium": "Social Media", "category": "Creator Content", "territory": "Worldwide", "term": "Perpetual", "exclusivity": "non-exclusive" },
    "payment": { "amount_usdc": 10, "chain": "base", "transaction_hash": "0x..." },
    "signature": "e583..."
  },
  "downloads": {
    "mp3": "https://onchainmusic.com/licenses/OCM-L000123/download/mp3?...",
    "wav": "https://onchainmusic.com/licenses/OCM-L000123/download/wav?...",
    "aif": "https://onchainmusic.com/licenses/OCM-L000123/download/aif?..."
  },
  "license_pdf_url": "https://onchainmusic.com/licenses/OCM-L000123/agreement?...",
  "links_expire_at": "2026-11-25T16:26:07-08:00"
}

⏱ Poll every 5 to 10 seconds. Confirmation usually takes 30 to 60 seconds after the transaction lands on Base. Download and agreement links expire after 30 days, so save the files.

💰
License Pricing

Personal Social Media

$10 USDC

Personal, non-commercial videos on social platforms

TikTok
Instagram Reels
YouTube
X / Twitter
Facebook

Personal All Digital

$35 USDC

Non-commercial digital use

Personal websites
Podcasts
Streaming
Online video

Both personal licenses are perpetual, non-exclusive, and worldwide. Business licenses (branded social media, commercials, film, television, trailers, and more) are priced by medium, territory, term, and the track's tier: see /license/options. Every license comes with a license agreement PDF and a license document signed with HMAC-SHA256.

🌐
Agent Discovery

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

Standard agent discovery endpoint. Returns capabilities, the licensing flow, payment details, standard license prices, and links to the rate card and 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, 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. Gives LLMs a concise description of the OnChain Music platform and API.

url

https://onchainmusic.com/llms.txt

🔌
MCP Server

The same search and licensing is available as a Model Context Protocol server, with no authentication. To license through MCP, ask personal or business, call get_license_options for prices, then initiate_license, then verify_license after payment.

json

{
  "mcpServers": {
    "onchain-music": {
      "type": "url",
      "url": "https://onchainmusic.com/api/mcp"
    }
  }
}

🤖
ChatGPT

In ChatGPT, OnChain Music helps people discover music in plain English: search, track details, and a link to browse and preview every match. Licensing is completed on onchainmusic.com, where each track has a License button with checkout by card or USDC.

💡 Building your own GPT or agent with OpenAPI actions? Append ?mode=gpt to license calls to receive 200 instead of 402, since GPT actions can't read 402 responses.

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

Personal Social Media

Personal All Digital

🌐
Agent Discovery

🔌
MCP Server

🤖
ChatGPT

Social

Customer Service

Music Supervisors & Creators

OnChain Music

Developers & AI

Learn

Partners

Agent API Documentation

📡 Overview

🔓 Authentication

⚡ Rate Limits

💎 Payments (USDC on Base)

🔍 Catalog Endpoints

🛒 Licensing Endpoints

💰 License Pricing

Personal Social Media

Personal All Digital

🌐 Agent Discovery

🔌 MCP Server

🤖 ChatGPT

Social

Customer Service

Music Supervisors & Creators

OnChain Music

Developers & AI

Learn

Partners

Agreement

Download Track

📡
Overview

🔓
Authentication

⚡
Rate Limits

💎
Payments (USDC on Base)

🔍
Catalog Endpoints

🛒
Licensing Endpoints

💰
License Pricing

🌐
Agent Discovery

🔌
MCP Server

🤖
ChatGPT