io.github.Christebob/meta-stamp-pockets

Pull licensed creator content from a specific pocket by ID. Use this tool when an AI agent needs to retrieve verified, provenance-tracked content for generation, RAG, and inference use. Training use requires a separate training license — see training_use in the agreement terms. Do NOT use for browsing or discovery — use search_pockets or list_pockets instead. Requires a valid Bearer token for authentication; unauthenticated requests return HTTP 402. Successful pulls trigger a metered charge at the pocket's own price (quoted as owner_price on the receipt; $0.0025 platform default only when a pocket sets none) and the transaction is logged for creator royalty distribution. The pocket_id parameter is a 24-character hex string identifying the specific content pocket to pull from. Returns the full content payload with provenance metadata including creator attribution and license terms. Every call returns a receipt of the same shape (receipt_id, outcome, reason, amount_paid, terms, content_hash) with a public verify_url: on success under 'receipt' in the result (outcome 'delivered'), on an HTTP 402 refusal under 'receipt' in the error body (outcome 'refused', reason 'registration_required' when no valid API key is presented, 'payment_required' when the wallet balance is too low or the card charge fails). A pocket whose rights holder has closed its catalog is refused for every caller, with or without a key, as a normal result (not a 402) with reason 'catalog_closed', owner_price 'not_for_sale' and the receipt under 'receipt'; nothing is delivered or charged. A listing-only pocket (delivery 'listing' in search results) has no file: its pull is charged the owner's per-pull price like any other and returns delivery 'listing' with 'content' set to the listing object {title, isrc, owner, terms, link} and no download URL. content_hash is the sha256 hex of the delivered 'content' field only: a string is hashed as its UTF-8 bytes, an object as UTF-8 JSON with sorted keys and no whitespace.

List all available content pockets in the Meta-Stamp Pockets catalog, optionally filtered by creator. Use this tool when an AI agent needs to browse the full catalog or see everything available from a specific creator. Prefer search_pockets when looking for specific topics. Does NOT retrieve content — use pull_content with the returned pocket_id to access actual content. Works without authentication; anonymous results omit content_url and creator_id, which are returned only with a valid Bearer token (pkt_ API key). The optional creator_id parameter filters results to a single creator's pockets and requires an API key (anonymous calls using it are refused with an api_key_required error and a registration_url). Returns a paginated list of pockets with IDs, titles, descriptions, creators, content types, and pricing tiers. Each row also carries catalog_id, access ('open' or 'closed') and delivery ('file' or 'listing'); closed-catalog and listing rows never include content_url. Unlisted pockets are never listed; they stay reachable by pocket_id (pull_content) or by an exact isrc in search_pockets.

Search the Meta-Stamp Pockets catalog by keyword, creator email, or content category. Use this tool when an AI agent needs to discover available licensed content before pulling it. Ideal for finding relevant pockets when the agent knows what topic or creator it needs but not the specific pocket ID. Does NOT retrieve content — use pull_content with the returned pocket_id to access actual content. Works without authentication for query, isrc and content_type; anonymous results omit content_url and creator_id, which are returned only with a valid Bearer token (pkt_ API key). The query parameter is matched as a literal keyword and accepts natural language search terms or category keywords; the creator_email parameter restricts results to a single creator by their email address and requires an API key (anonymous calls using it are refused with an api_key_required error and a registration_url). The isrc parameter is an exact full-ISRC lookup. Provide at least one of query, creator_email or isrc. Returns matching pockets with their IDs, titles, descriptions, creators, content types, and pricing tiers. Each row also carries catalog_id, access ('open' or 'closed') and delivery ('file' or 'listing'). Closed-catalog rows cannot be pulled and never include content_url; listing rows show title, isrc and owner and never include content_url. Unlisted pockets are excluded from results unless found by an exact isrc match. Use the limit parameter to control page size.