Get started with Obol

Obol turns a listen into a payment to the artist, settled in USDC on-chain. This guide covers how it works, how to play and pay, how artists get listed and paid, how to run it yourself, and the API.

Overview

Obol pays artists per listen, in real time, on-chain. There are two ways value moves:

Pay-per-play uses an HTTP 402 payment gate so anyone can press play and pay the artist a USDC nanopayment on Arc. The agent watches a self-hosted listening history and settles a payment per scrobble. Both produce a real on-chain transaction you can verify.

How it works

A play (or a scrobble) is matched to an artist, a USDC transfer is sent to that artist's wallet through Circle, the transfer settles on Arc, and the on-chain transaction hash is recorded against the payment. Unclaimed artists accrue earnings in escrow against their MusicBrainz identity until they claim a wallet.

Pay-per-play (x402)

The /listen page is the simplest way to see Obol work. Press play on a track and watch the handshake: the request hits a 402, a USDC payment settles on Arc, the proof is verified, and the track unlocks.

Under the hood, the gate is a real HTTP 402 endpoint. A request with no payment returns the amount, recipient, and asset; a request carrying a verified on-chain proof returns the unlocked resource.

# Challenge: ask for the resource, get payment requirements
curl -i https://<host>/api/x402/track/cipher
# HTTP/1.1 402 Payment Required
# { "x402Version": 1, "accepts": [{ "scheme": "arc-onchain", "payTo": "0x..", ... }] }

The agent

For self-hosted libraries, connect a Navidrome or Subsonic server on the dashboard. The agent reads your listening, resolves each track's artist via MusicBrainz, and when the match is ambiguous it asks an LLM to pick the real performer and records the reasoning. It then queues and settles a USDC payment per listen.

Trigger a run manually from the dashboard, turn on Auto-run, or let the scheduled run handle it. A per-listen rate and a daily spend cap keep spending under your control.

For artists

On the For Artists page you can search your name, see how much USDC is waiting for you in escrow, and claim it to a wallet. You can also list your own tracks: add a name, a wallet, and your catalog, and your tracks go live on the Listen page and pay you on-chain.

Every artist gets a public receipt page with a verifiable on-chain ledger of every payment received.

Quick start

Run Obol locally with a free Postgres database, a Groq key, and Circle sandbox credentials.

npm install
cp .env.example .env          # fill in the values
npx prisma db push            # sync schema to your database
node scripts/gen-audio.mjs    # generate sample audio
node scripts/seed-tracks.mjs  # seed the catalog
npm run dev                   # http://localhost:3000

See the deployment guide for Vercel and Docker instructions.

API reference

The main endpoints:

GET  /api/x402/catalog          # list playable tracks
GET  /api/x402/track/:id        # 402 gate (payment requirements)
POST /api/x402/play/:id         # play + pay + unlock (streamed)
POST /api/agent/run             # run the payment agent (streamed)
GET  /api/agent/status          # lifetime stats + recent payments
GET  /api/artist/escrow?mbId=   # escrow balance for an artist
POST /api/artist/claim          # claim an artist to a wallet
POST /api/artist/onboard        # list an artist + tracks
GET  /api/health                # liveness + database check

FAQ

Do I need a wallet to listen? No. Payments settle through managed wallets behind the app.

Is this real money? Settlement runs on Arc Testnet today. Mainnet follows a security review.

How do artists get paid if they haven't signed up? Earnings accrue in escrow against their MusicBrainz identity and release when they claim a wallet.

What music plays? The catalog uses sample audio for demonstration; production catalogs would use licensed recordings.