# Pitch402

Agent-native paid playlist pitching on Base + x402 + Spotify.

A curator opens a 100-spot playlist. An artist or agent buys a numbered spot with USDC
via x402. Buying a spot places the track on the curator's own Spotify playlist.

## Prices (USDC, per cycle, editable by the curator)

- spot 1: 10 USDC
- spots 2-3: 5 USDC
- spots 4-10: 3 USDC
- spots 11-100: 1 USDC

## Term multipliers

- cycle: 1x
- 3m: 3x
- 1y: 10x

Price is snapshotted at payment. A paid spot is never repriced. When a spot is
taken, the quote endpoint returns the next free spot and its price. When all
100 spots are filled, buys close and a next-cycle waitlist opens.

## Networks

- Base Sepolia (base-sepolia, eip155:84532): USDC 0x036CbD53842c5426634e7929541eC2318f3dCF7e; settlement live via https://x402.org/facilitator
- HashKey Chain Testnet (hsk-testnet, eip155:133): USDC address TBD; no confirmed facilitator — spots cannot be bought on this network

Default network is base-sepolia. Choose another with ?network=<id> on a quote,
or a "network" field in the buy body. Prices are the same USDC amounts on every
network. Settlement is verified on Base Sepolia only.

## Endpoints

- GET https://pitch402-hackathon.vercel.app/api/v1/playlists
- GET https://pitch402-hackathon.vercel.app/api/v1/playlists/{id}
- GET https://pitch402-hackathon.vercel.app/api/v1/playlists/{id}/quote?spot=N
- GET https://pitch402-hackathon.vercel.app/api/v1/playlists/{id}/quote?next=1
- POST https://pitch402-hackathon.vercel.app/api/v1/playlists/{id}/spots/{n}   (x402 gated)
- GET https://pitch402-hackathon.vercel.app/api/v1/receipts/{id}
- POST https://pitch402-hackathon.vercel.app/api/v1/receipts/{id}/place        (retry a failed Spotify write, free)
- GET https://pitch402-hackathon.vercel.app/.well-known/agent.json

Curator only, once per cycle:

- GET https://pitch402-hackathon.vercel.app/api/v1/curator/spotify/connect?playlist={id}

## Agent skill

https://pitch402-hackathon.vercel.app/skill.md — a drop-in skill file. An agent that can install skills can
fetch this and it will know how to buy without further instruction:

  curl -o .claude/skills/pitch402/SKILL.md https://pitch402-hackathon.vercel.app/skill.md

## Integration guide

https://pitch402-hackathon.vercel.app/agents — how an agent buys a spot, with runnable snippets, the wallet
policy we use, and what Pitch402 does not claim.

## Start here

GET https://pitch402-hackathon.vercel.app/api/v1/playlists/demo/quote?next=1

The response carries next_action.url — POST to it to buy the quoted spot.

## What buying does

Paying for spot N adds your track to the curator's own Spotify playlist and
returns a receipt. The receipt's "spotify" block reports what actually
happened:

- status "placed"  — the track is on the playlist, at "position" (zero-based,
                     and not the same number as the spot)
- status "failed"  — payment succeeded, the Spotify write did not. The spot is
                     yours and held. POST the "retry_url" to try again.
- status "skipped" — no curator playlist is connected to this cycle yet, so
                     there was nothing to write to.

You never need a Spotify account. Only the curator authorizes Spotify, once.

## Payment

x402. Base Sepolia (eip155:84532) settles through https://x402.org/facilitator.
HashKey Chain Testnet (eip155:133) is advertised for network coverage, but no
facilitator is confirmed for it, so payments there cannot settle yet — use the
demo payment header on that network, or pay on Base Sepolia.
USDC has 6 decimals.

## What we do not claim

- Settlement on HashKey Chain Testnet. It is listed for network coverage only;
  live facilitator settle is verified on Base Sepolia.
- Curator-owned playlists only. Never Spotify editorial placement.
- No stream counts and no royalty figures. The Spotify Web API exposes no
  playlist-attributed plays. Any future estimate comes from curator-uploaded
  Spotify for Artists data and is labeled Estimate.
- No guaranteed algorithmic streams.