{"openapi":"3.1.0","info":{"title":"Pa1m Reddit","description":"Reddit data API for AI agents — pay-per-request via x402 USDC on Base","version":"1.0.0","x-guidance":"Pa1m Reddit gives AI agents access to Reddit data and actions via a clean REST API. No Reddit account needed for read operations — pay per call in USDC on Base via x402.\n\n## Read endpoints ($0.01 each — no Reddit account needed)\nGET /posts?subreddit=python&sort=hot&limit=25 — fetch posts from any subreddit\nGET /search?q=openai&sort=new&t=week — search Reddit globally or within a subreddit\nGET /comments?permalink=/r/python/comments/abc/title/ — full comment tree by permalink\nGET /comments/{post_id} — full comment tree by post ID (e.g. 1sgjld3)\nGET /user/{username} — user profile: karma, account flags, profile info\nGET /user/{username}/comments?sort=top&limit=25 — user's recent comments\n\n## Write endpoints (require Reddit session cookies from POST /login)\nPOST /login {\"username\": \"...\", \"password\": \"...\"} → session cookies ($0.05)\nPOST /comment {\"post_url\": \"...\", \"text\": \"...\", \"reddit_session\": \"...\", \"loid\": \"...\"} ($0.05)\nPOST /vote {\"thing_id\": \"t3_xxx\", \"direction\": \"up\", \"reddit_session\": \"...\", \"loid\": \"...\"} ($0.02)\nPOST /dm {\"to_username\": \"...\", \"message\": \"...\", \"reddit_session\": \"...\", \"loid\": \"...\"} ($0.10)\n\n## Pagination\nAll listing endpoints support cursor-based pagination via the 'after' query parameter. Pass the 'after' value from the previous response to get the next page.","contact":{"email":"merchants@hypa1m.xyz"}},"paths":{"/.well-known/agent.json":{"get":{"summary":"Agent Info","operationId":"agent_info__well_known_agent_json_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[]}},"/health":{"get":{"summary":"Health","operationId":"health_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[]}},"/llms.txt":{"get":{"summary":"Llms Txt","operationId":"llms_txt_llms_txt_get","responses":{"200":{"description":"Successful Response","content":{"text/plain":{"schema":{"type":"string"}}}}},"security":[]}},"/posts":{"get":{"summary":"Subreddit Posts — $0.01","description":"Fetch posts from any subreddit with sorting and pagination. No Reddit account needed. Sorting options: hot (trending now), new (most recent), top (most upvoted), rising (gaining momentum), controversial (most debated), best (Reddit's personalized ranking). Use t= parameter (hour/day/week/month/year/all) with sort=top or sort=controversial. Paginate by passing the 'after' cursor from the previous response. Up to 100 posts per call. Example: GET /posts?subreddit=MachineLearning&sort=top&t=week&limit=50","operationId":"get_posts_posts_get","parameters":[{"name":"subreddit","in":"query","required":true,"schema":{"type":"string","description":"Subreddit name without r/ prefix","title":"Subreddit"},"description":"Subreddit name without r/ prefix"},{"name":"sort","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"hot | new | top | rising | controversial | best","default":"hot","title":"Sort"},"description":"hot | new | top | rising | controversial | best"},{"name":"t","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Time window for top/controversial: hour | day | week | month | year | all","title":"T"},"description":"Time window for top/controversial: hour | day | week | month | year | all"},{"name":"limit","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":100,"minimum":1},{"type":"null"}],"default":25,"title":"Limit"}},{"name":"after","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Pagination cursor (t3_xxx)","title":"After"},"description":"Pagination cursor (t3_xxx)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"402":{"description":"Payment Required"}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.010000"},"protocols":[{"x402":{}},{"mpp":{"method":"tempo","intent":"charge","currency":"USD"}}]}}},"/search":{"get":{"summary":"Search Reddit Posts — $0.01","description":"Search Reddit posts globally or restrict to a specific subreddit. Mirrors the Posts tab on reddit.com/search. Sorting: relevance (default — highest upvoted may outrank closest match on broad queries), new (strict chronological), hot, top, comments. Tip: use sort=new with t=week for recent topical results; sort=relevance for best match. Set nsfw=true to include adult content. Paginate with 'after' cursor. Example: GET /search?q=Claude+API&sort=new&t=month&limit=25","operationId":"search_posts_search_get","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","description":"Search query","title":"Q"},"description":"Search query"},{"name":"subreddit","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Restrict to a subreddit (without r/ prefix)","title":"Subreddit"},"description":"Restrict to a subreddit (without r/ prefix)"},{"name":"sort","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"relevance | new | hot | top | comments","default":"relevance","title":"Sort"},"description":"relevance | new | hot | top | comments"},{"name":"t","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"hour | day | week | month | year | all","title":"T"},"description":"hour | day | week | month | year | all"},{"name":"nsfw","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Include NSFW content","default":false,"title":"Nsfw"},"description":"Include NSFW content"},{"name":"limit","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":100,"minimum":1},{"type":"null"}],"default":25,"title":"Limit"}},{"name":"after","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Pagination cursor","title":"After"},"description":"Pagination cursor"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"402":{"description":"Payment Required"}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.010000"},"protocols":[{"x402":{}},{"mpp":{"method":"tempo","intent":"charge","currency":"USD"}}]}}},"/comments":{"get":{"summary":"Post Comments by Permalink — $0.01","description":"Fetch the full comment tree for a Reddit post using its permalink URL. Returns top-level comments with nested replies, upvote counts, and author metadata. Use this when you have the full Reddit URL. Permalink format: /r/{subreddit}/comments/{post_id}/{title}/ Example: GET /comments?permalink=/r/python/comments/1abc123/my_post_title/","operationId":"get_comments_by_permalink_comments_get","parameters":[{"name":"permalink","in":"query","required":true,"schema":{"type":"string","description":"Reddit post permalink, e.g. /r/python/comments/abc/title/","title":"Permalink"},"description":"Reddit post permalink, e.g. /r/python/comments/abc/title/"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"402":{"description":"Payment Required"}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.010000"},"protocols":[{"x402":{}},{"mpp":{"method":"tempo","intent":"charge","currency":"USD"}}]}}},"/comments/{post_id}":{"get":{"summary":"Post Comments by Post ID — $0.01","description":"Fetch the full comment tree for a Reddit post using its short alphanumeric post ID. Same response as the permalink endpoint — use this when you have the ID, not the full URL. Post IDs can be extracted from Reddit URLs: reddit.com/r/x/comments/{post_id}/... Example: GET /comments/1abc123","operationId":"get_comments_by_id_comments__post_id__get","parameters":[{"name":"post_id","in":"path","required":true,"schema":{"type":"string","description":"Reddit post ID like 1sgjld3","title":"Post Id"},"description":"Reddit post ID like 1sgjld3"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"402":{"description":"Payment Required"}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.010000"},"protocols":[{"x402":{}},{"mpp":{"method":"tempo","intent":"charge","currency":"USD"}}]}}},"/user/{username}":{"get":{"summary":"User Profile — $0.01","description":"Fetch a Reddit user's public profile. Returns link karma, comment karma, account age, gold/mod/employee status flags, verified email flag, icon URL, and profile description. Example: GET /user/spez","operationId":"get_user_user__username__get","parameters":[{"name":"username","in":"path","required":true,"schema":{"type":"string","description":"Reddit username without u/ prefix","title":"Username"},"description":"Reddit username without u/ prefix"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"402":{"description":"Payment Required"}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.010000"},"protocols":[{"x402":{}},{"mpp":{"method":"tempo","intent":"charge","currency":"USD"}}]}}},"/user/{username}/comments":{"get":{"summary":"User Comment History — $0.01","description":"Fetch a Reddit user's recent comments. Each item includes subreddit, upvote score, parent post title, comment body, and creation timestamp. Sort by new (default), top, or controversial. Paginate with the 'after' cursor. Example: GET /user/spez/comments?sort=top&limit=10","operationId":"get_user_comments_user__username__comments_get","parameters":[{"name":"username","in":"path","required":true,"schema":{"type":"string","description":"Reddit username without u/ prefix","title":"Username"},"description":"Reddit username without u/ prefix"},{"name":"sort","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"new | top | controversial","default":"new","title":"Sort"},"description":"new | top | controversial"},{"name":"limit","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":100,"minimum":1},{"type":"null"}],"default":25,"title":"Limit"}},{"name":"after","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Pagination cursor","title":"After"},"description":"Pagination cursor"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"402":{"description":"Payment Required"}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.010000"},"protocols":[{"x402":{}},{"mpp":{"method":"tempo","intent":"charge","currency":"USD"}}]}}},"/login":{"post":{"summary":"Reddit Login — $0.05","description":"Authenticate a Reddit account and receive session cookies needed for write operations (comment, vote, DM). Cookies are valid until revoked by Reddit. For accounts with 2FA, pass totp_secret to generate the TOTP code automatically. Body: {\"username\": \"...\", \"password\": \"...\", \"totp_secret\": \"...\" (optional)}","operationId":"login_login_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoginRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"402":{"description":"Payment Required"}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.050000"},"protocols":[{"x402":{}},{"mpp":{"method":"tempo","intent":"charge","currency":"USD"}}]}}},"/comment":{"post":{"summary":"Post Comment — $0.05","description":"Submit a top-level comment on a Reddit post. Requires session cookies from POST /login (reddit_session + loid fields). Body: {\"post_url\": \"https://reddit.com/r/...\", \"text\": \"...\", \"reddit_session\": \"...\", \"loid\": \"...\"}","operationId":"post_comment_comment_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommentRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"402":{"description":"Payment Required"}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.050000"},"protocols":[{"x402":{}},{"mpp":{"method":"tempo","intent":"charge","currency":"USD"}}]}}},"/vote":{"post":{"summary":"Vote — $0.02","description":"Upvote or downvote a Reddit post or comment. thing_id format: t3_xxx for posts, t1_xxx for comments. direction: up | down | none (none removes your vote). Requires session cookies from POST /login. Body: {\"thing_id\": \"t3_abc123\", \"direction\": \"up\", \"reddit_session\": \"...\", \"loid\": \"...\"}","operationId":"vote_vote_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VoteRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"402":{"description":"Payment Required"}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.020000"},"protocols":[{"x402":{}},{"mpp":{"method":"tempo","intent":"charge","currency":"USD"}}]}}},"/dm":{"post":{"summary":"Send Direct Message — $0.10","description":"Send a private message to a Reddit user. Pass to_username (e.g. 'spez') or to_user_t2 (Reddit internal ID like t2_xxx). Requires session cookies from POST /login. Body: {\"to_username\": \"spez\", \"message\": \"Hello!\", \"reddit_session\": \"...\", \"loid\": \"...\"}","operationId":"send_dm_dm_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DMRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"402":{"description":"Payment Required"}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.100000"},"protocols":[{"x402":{}},{"mpp":{"method":"tempo","intent":"charge","currency":"USD"}}]}}}},"components":{"schemas":{"CommentRequest":{"properties":{"post_url":{"type":"string","title":"Post Url"},"text":{"type":"string","title":"Text"},"reddit_session":{"type":"string","title":"Reddit Session"},"loid":{"type":"string","title":"Loid"},"csrf_token":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Csrf Token"},"token_v2":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Token V2"}},"type":"object","required":["post_url","text","reddit_session","loid"],"title":"CommentRequest"},"DMRequest":{"properties":{"to_username":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"To Username"},"to_user_t2":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"To User T2"},"message":{"type":"string","title":"Message"},"reddit_session":{"type":"string","title":"Reddit Session"},"loid":{"type":"string","title":"Loid"},"csrf_token":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Csrf Token"}},"type":"object","required":["message","reddit_session","loid"],"title":"DMRequest"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"LoginRequest":{"properties":{"username":{"type":"string","title":"Username"},"password":{"type":"string","title":"Password"},"totp_secret":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Totp Secret"}},"type":"object","required":["username","password"],"title":"LoginRequest"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"VoteRequest":{"properties":{"thing_id":{"type":"string","title":"Thing Id"},"direction":{"type":"string","title":"Direction"},"reddit_session":{"type":"string","title":"Reddit Session"},"loid":{"type":"string","title":"Loid"},"csrf_token":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Csrf Token"}},"type":"object","required":["thing_id","direction","reddit_session","loid"],"title":"VoteRequest"}}}}