{"openapi":"3.1.0","info":{"title":"Streamlivr x402 agent API","version":"1.0.0","summary":"Public creator, content and music metadata, paid per request over x402 on Celo.","description":"Streamlivr sells African and global creator, brand, music, content and platform metadata over x402 on Celo. Agents can search and page through public creator and brand profiles, public content and the music catalog, at one cent per creator credited. Every settled payment is attributed back to the creators whose rows were served: a post pays whoever owns its audio rather than whoever posted it, a recording pays the artist who owns it rather than the accounts that used it, and a row with no Streamlivr owner is retained by the platform.","contact":{"name":"Streamlivr support","url":"https://streamlivr.com","email":"support@streamlivr.com"},"termsOfService":"https://docs.streamlivr.com/legal/terms-of-service","license":{"name":"Streamlivr Terms of Service","url":"https://docs.streamlivr.com/legal/terms-of-service"},"x-logo":{"url":"https://streamlivr.com/assets/STREAMLIVR%20ICON%20(1).png"}},"externalDocs":{"description":"Quick start, pricing and on-chain proof","url":"https://github.com/streamlivr/streamlivr-x402-celo"},"servers":[{"url":"https://api.streamlivr.com"}],"tags":[{"name":"Paid (x402)","description":"Every call settles an x402 exact-scheme USDC transfer on Celo before data is returned."},{"name":"Free","description":"Discovery and pricing. No payment."}],"paths":{"/api/v1/agent/ping":{"get":{"operationId":"x402_ping","summary":"Payment connectivity check","description":"Returns liveness and the settlement network the API is running on. Use it to confirm a buyer wallet, facilitator key, and x402 client all work before paying for data.","tags":["Paid (x402)"],"parameters":[],"security":[{"x402":[]}],"responses":{"200":{"description":"The requested data, with the settlement in the `PAYMENT-RESPONSE` header.","headers":{"PAYMENT-RESPONSE":{"description":"Base64 x402 settlement response, including the transaction hash.","schema":{"type":"string"}},"x-no-charge":{"description":"Set when nothing was settled, for example `empty-page`.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object"},"example":{"ok":true,"paid":true,"network":"eip155:42220","assetSymbol":"USDC"}}}},"400":{"description":"Invalid query. Never settled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment required. The x402 v2 requirements are base64 JSON in the `PAYMENT-REQUIRED` header and are repeated as JSON in the body. Sign them with any x402 client and repeat the request with the `PAYMENT-SIGNATURE` header.","headers":{"PAYMENT-REQUIRED":{"description":"Base64-encoded x402 PaymentRequired object.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}}},"x-x402":{"scheme":"exact","network":"eip155:42220","asset":"USDC","assetAddress":"0xcebA9300f2b948710d2653dD7B07f33A8B32118C","decimals":6,"payTo":"0x4503F32dFF9e54Ee4c0Fd9BE25bCC662abB4c4Bf","facilitator":"https://api.x402.celo.org","billedPer":"request","minimumAtomic":"10000","minimum":"0.01","maximumAtomic":"10000","maximum":"0.01","rule":"0.01 USDC per request."}}},"/api/v1/agent/listings":{"get":{"operationId":"creator_listings","summary":"Creator and brand directory","description":"Public creator and brand profiles: name, bio, avatar, country, follower counts, verification and account age. Searchable by name, bio, hashtag and country with ?q=. Combine with ?limit=, ?verified=, ?minFollowers= and ?sort=followers|newest. The response includes the total and nextCursor. Priced per creator credited. One cent in USDC per creator credited, with a one cent minimum per request. A page that credits 50 creators costs $0.50. The 402 invoice carries the exact amount before anything is signed.","tags":["Paid (x402)"],"parameters":[{"name":"q","in":"query","required":false,"description":"Free-text search. Matches names, titles, bios, hashtags, country names and country codes on that route. Omit to list everything.","schema":{"type":"string"},"example":"lagos"},{"name":"limit","in":"query","required":false,"description":"Rows to return, 1-200, default 10. This is the cost control: the invoice is one cent per creator the page credits, so a bigger page costs more.","schema":{"type":"integer","minimum":0},"example":10},{"name":"cursor","in":"query","required":false,"description":"nextCursor from the previous page. Omit for the first page.","schema":{"type":"string"},"example":"eyJpZCI6ImNtbWdnYnRpazAwMDBxcnFiem9udHZzeTM4In0"},{"name":"verified","in":"query","required":false,"description":"Filter public creators by verified status. Omit for both.","schema":{"type":"boolean"},"example":true},{"name":"minFollowers","in":"query","required":false,"description":"Minimum public follower count, 0-2147483647.","schema":{"type":"integer","minimum":0},"example":1000},{"name":"sort","in":"query","required":false,"description":"Follower count descending (default) or newest account first.","schema":{"type":"string","enum":["followers","newest"]},"example":"followers"}],"security":[{"x402":[]}],"responses":{"200":{"description":"The page that was invoiced. A page with no rows is served without settling and carries `x-no-charge` headers.","headers":{"PAYMENT-RESPONSE":{"description":"Base64 x402 settlement response, including the transaction hash.","schema":{"type":"string"}},"x-no-charge":{"description":"Set when nothing was settled, for example `empty-page`.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object"},"example":{"creators":[{"id":"cmmggbkik0000rqbzontvsy38","username":"grant","displayName":"ekegrant59","bio":"Afrobeats producer, Lagos","avatarUrl":"https://assets.example.com/avatars/creator.jpg","countryCode":"NG","followerCount":2,"followingCount":1,"isVerified":false}],"page":{"total":2431,"limit":50,"returned":1,"hasMore":true,"nextCursor":"eyJpZCI6ImNtbWdnYnRpazAwMDBxcnFiem9udHZzeTM4In0","truncated":true},"query":{"q":"lagos","limit":50}}}}},"400":{"description":"Invalid query. Never settled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment required. The x402 v2 requirements are base64 JSON in the `PAYMENT-REQUIRED` header and are repeated as JSON in the body. Sign them with any x402 client and repeat the request with the `PAYMENT-SIGNATURE` header.","headers":{"PAYMENT-REQUIRED":{"description":"Base64-encoded x402 PaymentRequired object.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}}},"x-x402":{"scheme":"exact","network":"eip155:42220","asset":"USDC","assetAddress":"0xcebA9300f2b948710d2653dD7B07f33A8B32118C","decimals":6,"payTo":"0x4503F32dFF9e54Ee4c0Fd9BE25bCC662abB4c4Bf","facilitator":"https://api.x402.celo.org","billedPer":"creator credited","minimumAtomic":"10000","minimum":"0.01","maximumAtomic":"2000000","maximum":"2","rule":"One cent in USDC per creator credited, with a one cent minimum per request. A page that credits 50 creators costs $0.50. The 402 invoice carries the exact amount before anything is signed."}}},"/api/v1/agent/posts":{"get":{"operationId":"public_posts","summary":"Public content feed","description":"Published public content from every public account: title, caption, hashtags, media type and length, engagement counts, and thumbnail. Each row labels the audio owner and attribution; borrowed sound credits its owner. Searchable by title, caption, tag or the public creator's country with ?q=. Combine with ?limit= and ?sort=newest|views, and follow nextCursor for more. Priced per creator credited. One cent in USDC per creator credited, with a one cent minimum per request. A page that credits 50 creators costs $0.50. The 402 invoice carries the exact amount before anything is signed.","tags":["Paid (x402)"],"parameters":[{"name":"q","in":"query","required":false,"description":"Free-text search. Matches names, titles, bios, hashtags, country names and country codes on that route. Omit to list everything.","schema":{"type":"string"},"example":"lagos"},{"name":"limit","in":"query","required":false,"description":"Rows to return, 1-200, default 10. This is the cost control: the invoice is one cent per creator the page credits, so a bigger page costs more.","schema":{"type":"integer","minimum":0},"example":10},{"name":"cursor","in":"query","required":false,"description":"nextCursor from the previous page. Omit for the first page.","schema":{"type":"string"},"example":"eyJpZCI6ImNtbWdnYnRpazAwMDBxcnFiem9udHZzeTM4In0"},{"name":"sort","in":"query","required":false,"description":"Newest first (default) or public view count descending.","schema":{"type":"string","enum":["newest","views"]},"example":"views"}],"security":[{"x402":[]}],"responses":{"200":{"description":"The page that was invoiced. A page with no rows is served without settling and carries `x-no-charge` headers.","headers":{"PAYMENT-RESPONSE":{"description":"Base64 x402 settlement response, including the transaction hash.","schema":{"type":"string"}},"x-no-charge":{"description":"Set when nothing was settled, for example `empty-page`.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object"},"example":{"posts":[{"id":"cmvideo0000rqbzontvsy38","creatorId":"cmmggbkik0000rqbzontvsy38","title":"Lagos at night","description":"Shot on the way home from the studio","hashtags":["afrobeats","lagos"],"mediaType":"VIDEO","durationSeconds":21,"aspectRatio":"9:16","thumbnailUrl":"https://assets.example.com/thumbs/post.jpg","videoUrl":"https://assets.example.com/videos/post.mp4","viewCount":1820,"likeCount":140,"commentCount":12,"shareCount":4,"repostCount":3,"isAiGenerated":false,"isLivestreamVod":false,"createdAt":"2026-05-02T18:04:00.000Z"}],"page":{"total":6120,"limit":50,"returned":1,"hasMore":true,"nextCursor":"eyJpZCI6ImNtdmlkZW8wMDAwcURxYnphbnR2c3kzOCJ9","truncated":true},"query":{"q":"afrobeats","limit":50}}}}},"400":{"description":"Invalid query. Never settled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment required. The x402 v2 requirements are base64 JSON in the `PAYMENT-REQUIRED` header and are repeated as JSON in the body. Sign them with any x402 client and repeat the request with the `PAYMENT-SIGNATURE` header.","headers":{"PAYMENT-REQUIRED":{"description":"Base64-encoded x402 PaymentRequired object.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}}},"x-x402":{"scheme":"exact","network":"eip155:42220","asset":"USDC","assetAddress":"0xcebA9300f2b948710d2653dD7B07f33A8B32118C","decimals":6,"payTo":"0x4503F32dFF9e54Ee4c0Fd9BE25bCC662abB4c4Bf","facilitator":"https://api.x402.celo.org","billedPer":"creator credited","minimumAtomic":"10000","minimum":"0.01","maximumAtomic":"2000000","maximum":"2","rule":"One cent in USDC per creator credited, with a one cent minimum per request. A page that credits 50 creators costs $0.50. The 402 invoice carries the exact amount before anything is signed."}}},"/api/v1/agent/catalog":{"get":{"operationId":"music_catalog","summary":"Music and audio metadata","description":"Music and audio metadata for African and global repertoire: title, artist, ISRC, artwork, and a playable preview clip when the source provides one. Each row carries a \"label\" block that names its owner and how many public posts draw on it, and an \"attribution\" note. A recording is credited to the artist who owns it, never to the accounts whose posts used it; a recording with no Streamlivr owner is retained by the platform. Searchable by title or artist with ?q= and paginated. Matches how the Streamlivr app indexes audio for video, so agent results line up with in-app search. Priced per creator credited and attributed to each one when the payment settles. One cent in USDC per creator credited, with a one cent minimum per request. A page that credits 50 creators costs $0.50. The 402 invoice carries the exact amount before anything is signed.","tags":["Paid (x402)"],"parameters":[{"name":"q","in":"query","required":false,"description":"Free-text search. Matches names, titles, bios, hashtags, country names and country codes on that route. Omit to list everything.","schema":{"type":"string"},"example":"lagos"},{"name":"limit","in":"query","required":false,"description":"Rows to return, 1-200, default 10. This is the cost control: the invoice is one cent per creator the page credits, so a bigger page costs more.","schema":{"type":"integer","minimum":0},"example":10},{"name":"cursor","in":"query","required":false,"description":"nextCursor from the previous page. Omit for the first page.","schema":{"type":"string"},"example":"eyJpZCI6ImNtbWdnYnRpazAwMDBxcnFiem9udHZzeTM4In0"}],"security":[{"x402":[]}],"responses":{"200":{"description":"The page that was invoiced. A page with no rows is served without settling and carries `x-no-charge` headers.","headers":{"PAYMENT-RESPONSE":{"description":"Base64 x402 settlement response, including the transaction hash.","schema":{"type":"string"}},"x-no-charge":{"description":"Set when nothing was settled, for example `empty-page`.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object"},"example":{"tracks":[{"id":"tr_01","title":"Lagos Nights","artist":"Ada","isrc":"NGAAA2600001","coverUrl":"https://cdn-images.dzcdn.net/images/cover/example/500x500-000000-80-0-0.jpg","previewUrl":"https://cdnt-preview.dzcdn.net/api/1/1/example/preview.mp3?hdnea=exp=1790000000~acl=/api/*~hmac=example","creatorIds":["cr_01"]}],"page":{"total":5013,"limit":50,"returned":1,"hasMore":true,"nextCursor":"eyJpZCI6InRyXzAxIn0","truncated":true},"query":{"q":"lagos","limit":50}}}}},"400":{"description":"Invalid query. Never settled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment required. The x402 v2 requirements are base64 JSON in the `PAYMENT-REQUIRED` header and are repeated as JSON in the body. Sign them with any x402 client and repeat the request with the `PAYMENT-SIGNATURE` header.","headers":{"PAYMENT-REQUIRED":{"description":"Base64-encoded x402 PaymentRequired object.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}}},"x-x402":{"scheme":"exact","network":"eip155:42220","asset":"USDC","assetAddress":"0xcebA9300f2b948710d2653dD7B07f33A8B32118C","decimals":6,"payTo":"0x4503F32dFF9e54Ee4c0Fd9BE25bCC662abB4c4Bf","facilitator":"https://api.x402.celo.org","billedPer":"creator credited","minimumAtomic":"10000","minimum":"0.01","maximumAtomic":"2000000","maximum":"2","rule":"One cent in USDC per creator credited, with a one cent minimum per request. A page that credits 50 creators costs $0.50. The 402 invoice carries the exact amount before anything is signed."}}},"/api/v1/agent/creator/{id}":{"get":{"operationId":"creator_profile","summary":"Creator profile","description":"One public creator or brand profile by id, with the counts of their published content and catalogued tracks. One creator, so one cent, which is the cheapest way to buy when the agent already knows which profile it needs.","tags":["Paid (x402)"],"parameters":[{"name":"id","in":"path","required":true,"description":"Streamlivr creator id, taken from the listings, posts or catalog response.","schema":{"type":"string"},"example":"cmmggbkik0000rqbzontvsy38"}],"security":[{"x402":[]}],"responses":{"200":{"description":"The requested data, with the settlement in the `PAYMENT-RESPONSE` header.","headers":{"PAYMENT-RESPONSE":{"description":"Base64 x402 settlement response, including the transaction hash.","schema":{"type":"string"}},"x-no-charge":{"description":"Set when nothing was settled, for example `empty-page`.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object"},"example":{"id":"cmmggbkik0000rqbzontvsy38","username":"grant","displayName":"ekegrant59","bio":"Afrobeats producer, Lagos","avatarUrl":"https://assets.example.com/avatars/creator.jpg","countryCode":"NG","isVerified":false,"followerCount":2,"followingCount":1,"createdAt":"2026-01-14T09:20:00.000Z","stats":{"publishedVideos":12,"catalogTracks":4,"agentAccess":"public"}}}}},"400":{"description":"Invalid query. Never settled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment required. The x402 v2 requirements are base64 JSON in the `PAYMENT-REQUIRED` header and are repeated as JSON in the body. Sign them with any x402 client and repeat the request with the `PAYMENT-SIGNATURE` header.","headers":{"PAYMENT-REQUIRED":{"description":"Base64-encoded x402 PaymentRequired object.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}},"404":{"description":"No public creator with that id. Never settled."}},"x-x402":{"scheme":"exact","network":"eip155:42220","asset":"USDC","assetAddress":"0xcebA9300f2b948710d2653dD7B07f33A8B32118C","decimals":6,"payTo":"0x4503F32dFF9e54Ee4c0Fd9BE25bCC662abB4c4Bf","facilitator":"https://api.x402.celo.org","billedPer":"request","minimumAtomic":"10000","minimum":"0.01","maximumAtomic":"10000","maximum":"0.01","rule":"0.01 USDC per request."}}},"/api/v1/agent/pricing":{"get":{"operationId":"get_pricing","summary":"Price list","description":"The price rule, asset, network and worked examples. Free.","tags":["Free"],"security":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/agent/stats":{"get":{"operationId":"get_stats","summary":"Inventory stats","description":"Counts of public creators, posts and tracks, with the busiest countries and hashtags. Free.","tags":["Free"],"security":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/agent/reputation":{"get":{"operationId":"get_reputation","summary":"Reputation","description":"ERC-8004 reputation for the agent plus settled volume counters. Free.","tags":["Free"],"security":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/.well-known/agent.json":{"get":{"operationId":"get_agent_card","summary":"A2A agent card","description":"A2A agent card with x402 and ERC-8004 detail. Free.","tags":["Free"],"security":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/.well-known/mcp.json":{"get":{"operationId":"get_mcp_card","summary":"MCP server card","description":"MCP server card listing the paid tools. Free.","tags":["Free"],"security":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}}},"components":{"securitySchemes":{"x402":{"type":"apiKey","in":"header","name":"PAYMENT-SIGNATURE","description":"x402 v2 payment payload, base64. Omit it to receive the 402 invoice for the exact request. There is no API key: the signed payment is the only credential."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"reason":{"type":"string"}}},"PaymentRequired":{"type":"object","required":["x402Version","accepts"],"properties":{"x402Version":{"type":"integer","const":2},"error":{"type":"string"},"resource":{"type":"object","properties":{"url":{"type":"string"},"description":{"type":"string"},"mimeType":{"type":"string"}}},"accepts":{"type":"array","items":{"type":"object","properties":{"scheme":{"type":"string","const":"exact"},"network":{"type":"string","example":"eip155:42220"},"amount":{"type":"string","description":"Atomic units of the asset (6 decimals)."},"asset":{"type":"string","example":"0xcebA9300f2b948710d2653dD7B07f33A8B32118C"},"payTo":{"type":"string","example":"0x4503F32dFF9e54Ee4c0Fd9BE25bCC662abB4c4Bf"},"maxTimeoutSeconds":{"type":"integer"},"extra":{"type":"object"}}}},"extensions":{"type":"object"}}}}}}