{"openapi":"3.0.0","info":{"title":"Snack Money API","version":"1.0.0","description":"The **Snack Money API** enables seamless microtransaction and reward distribution for social networks and other platforms.  \nIt is designed for scenarios where you need to send small amounts of USDC to individual users or groups, validate payments, and automate content-based reward payouts.\n\n---\n\n## Features\n\n- **Single Payments** – Send USDC payments directly to a single recipient via `/payments/pay`.\n- **Batch Payments** – Send USDC to multiple recipients in one request via `/payments/batch-pay`.\n- **Payment Validation** – Validate payment status and details using `/payments/validate`.\n- **Reward Distribution** – Create and confirm reward distribution orders based on content engagement using `/rewards/create-distribution` and `/rewards/confirm-distribution`.\n- **Supports Multiple Identities** – Payments can be made to recipients identified via:\n  - Twitter\n  - Farcaster\n  - Domain names\n- **X402-Compliant** – Payment-required responses include full X-PAYMENT header details for compliance.\n\n---\n\n## Authentication\n\nSome endpoints require the `PAYMENT-SIGNATURE` header for processing.\nThe header contains payment details that comply with the [X402 payment protocol](https://x402.org/).\n\n---\n\n## Error Handling\n\nThe API returns standardized error responses:\n- **400** – Validation errors\n- **402** – Payment required\n- **500** – Internal server errors\n\n---\n\n## Example Use Cases\n\n- Reward social media users for likes, comments, or reposts.\n- Facilitate tipping between content creators and followers.\n- Batch transfer funds to multiple recipients with one API call.\n"},"components":{"schemas":{"PaymentResponse":{"type":"object","properties":{"code":{"type":"number","enum":[200]},"msg":{"type":"string"},"data":{"type":"object","properties":{"txn_id":{"type":"number","example":1762890982975},"amount":{"type":"number","example":0.01},"receipt":{"type":"string","format":"uri","example":"https://snack.money/twitter/0xmesuthere?txn=1762890982975"}},"required":["txn_id","amount","receipt"]}},"required":["code","msg","data"]},"ValidationError":{"type":"object","properties":{"code":{"type":"number","enum":[400]},"msg":{"type":"string","default":"Validation failed"},"error":{"nullable":true}},"required":["code"]},"PaymentRequired":{"type":"object","properties":{"x402Version":{"type":"number","default":1},"code":{"type":"number","enum":[402]},"msg":{"type":"string","default":"PAYMENT-SIGNATURE header is required"},"accepts":{"type":"array","items":{"type":"object","properties":{"scheme":{"type":"string","default":"exact"},"network":{"type":"string","default":"base"},"maxAmountRequired":{"type":"string","example":"1030000"},"resource":{"type":"string","default":"https://snack.money"},"description":{"type":"string"},"mimeType":{"type":"string"},"payTo":{"type":"string","default":"0x1223d566f05Ea54E5854434C4552c9f5C2259e0f"},"maxTimeoutSeconds":{"type":"number","default":60},"asset":{"type":"string","default":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"},"extra":{"type":"object","properties":{"name":{"type":"string","default":"USD Coin"},"version":{"type":"string","default":"2"}}}},"required":["maxAmountRequired","extra"]}}},"required":["code","accepts"]},"InternalServerError":{"type":"object","properties":{"code":{"type":"number","enum":[500]},"msg":{"type":"string","default":"Internal server error"},"error":{"nullable":true,"example":"Something went wrong"}},"required":["code"]},"PaymentRequest":{"type":"object","properties":{"amount":{"type":"number","minimum":0.01,"maximum":10,"example":1},"currency":{"type":"string","enum":["USDC"],"default":"USDC","example":"USDC"},"receiver":{"type":"string","minLength":1,"example":"snackmoney"},"description":{"type":"string","nullable":true,"example":"Description about the payment"},"transaction_hash":{"type":"string","nullable":true,"example":"Transaction Hash"},"meta":{"type":"object","properties":{"snack_name":{"type":"string","nullable":true},"snack_emoji":{"type":"string","nullable":true},"snack_amount":{"type":"number","nullable":true},"source_wallet":{"type":"string","nullable":true},"snack_quantity":{"type":"number","nullable":true},"sender_username":{"type":"string","nullable":true},"sender_identity":{"type":"string","nullable":true},"agent_name":{"type":"string","nullable":true},"content_url":{"type":"string","nullable":true}}}},"required":["amount","receiver"]},"BatchPaymentResponse":{"type":"object","properties":{"code":{"type":"number","enum":[200]},"msg":{"type":"string","default":"Payment sent successfully to users"},"settlement_attempt_id":{"type":"string","example":"attempt_1762889082833_abc123"},"data":{"type":"array","items":{"type":"object","properties":{"txn_id":{"type":"number","example":1751194593304},"username":{"type":"string","example":"snackmoney"},"receipt":{"type":"string","format":"uri","example":"https://snack.money/transaction/1751194593304"}},"required":["txn_id","username","receipt"]}}},"required":["code","data"]},"BatchPaymentRequest":{"type":"object","properties":{"currency":{"type":"string","enum":["USDC"],"default":"USDC","example":"USDC"},"receivers":{"type":"array","items":{"type":"object","properties":{"receiver":{"type":"string","minLength":1,"example":"snackmoney"},"amount":{"type":"number","minimum":0.01,"maximum":10,"example":0.5}},"required":["receiver","amount"]},"minItems":1,"maxItems":100},"description":{"type":"string","nullable":true,"example":"A description about the payment"},"meta":{"type":"object","properties":{"snack_name":{"type":"string","nullable":true},"snack_emoji":{"type":"string","nullable":true},"snack_amount":{"type":"number","nullable":true},"source_wallet":{"type":"string","nullable":true},"snack_quantity":{"type":"number","nullable":true},"agent_name":{"type":"string","nullable":true}}}},"required":["receivers"]},"AgentCreateAndFundResponse":{"type":"object","properties":{"success":{"type":"boolean"},"agentId":{"type":"string"},"name":{"type":"string"},"enabledFeatures":{"type":"array","items":{"type":"string","enum":["like","repost","reply","quote","mention"]}},"url":{"type":"string","format":"uri"},"mascotUrl":{"type":"string","nullable":true,"format":"uri"},"createdAt":{"type":"number"}},"required":["success","agentId","name","enabledFeatures","url","createdAt"]},"AgentCreateAndFundRequest":{"type":"object","properties":{"config":{"type":"object","properties":{"platform":{"type":"string","enum":["x","farcaster"],"default":"x"},"ownerAccount":{"type":"object","properties":{"username":{"type":"string"},"platform":{"type":"string","enum":["x","farcaster"]},"socialUserId":{"type":"string"},"followerCount":{"type":"number"}},"required":["username","platform"]},"members":{"type":"array","items":{"type":"object","properties":{"username":{"type":"string"},"platform":{"type":"string","enum":["x","farcaster"]},"followerCount":{"type":"number"}},"required":["username"]}},"rewardDistribution":{"type":"object","properties":{"mode":{"type":"string","enum":["open","restricted"],"default":"open"}}},"dynamicRewardsEnabled":{"type":"boolean","default":true},"socialConfig":{"type":"object","properties":{"isMyFollower":{"type":"boolean","default":false},"amIFollowing":{"type":"boolean","default":false},"isVerified":{"type":"boolean","default":false},"minFollowers":{"type":"number","minimum":0,"default":0},"minAccountAgeDays":{"type":"number","minimum":0,"default":0},"interactions":{"type":"object","properties":{"like":{"type":"number","minimum":0,"maximum":10,"default":0.01},"repost":{"type":"number","minimum":0,"maximum":10,"default":0.02},"reply":{"type":"number","minimum":0,"maximum":10,"default":0.05},"quote":{"type":"number","minimum":0,"maximum":10,"default":0.03},"mention":{"type":"number","minimum":0,"maximum":10,"default":0.1},"sentimentThreshold":{"type":"number","minimum":1,"maximum":10,"default":7}}}}}}}}}},"parameters":{}},"paths":{"/payments/farcaster/pay":{"post":{"tags":["Payments","Farcaster"],"summary":"Pay to farcaster user","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequest"},"example":{"amount":1,"currency":"USDC","receiver":"snackmoney","description":"Payment to Farcaster user"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentResponse"}}}},"400":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"402":{"description":"Payment Required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}},"500":{"description":"Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerError"}}}}}}},"/payments/x/pay":{"post":{"tags":["Payments","X"],"summary":"Pay to X user","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequest"},"example":{"amount":1,"currency":"USDC","receiver":"snackmoneyapp","description":"Payment to X user"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentResponse"}}}},"400":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"402":{"description":"Payment Required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}},"500":{"description":"Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerError"}}}}}}},"/payments/email/pay":{"post":{"tags":["Payments","Email"],"summary":"Pay to user via email","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequest"},"example":{"amount":1,"currency":"USDC","receiver":"tips@snack.money","description":"Payment via email"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentResponse"}}}},"400":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"402":{"description":"Payment Required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}},"500":{"description":"Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerError"}}}}}}},"/payments/web/pay":{"post":{"tags":["Payments","Web"],"summary":"Pay to user via domain name/url","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequest"},"example":{"amount":1,"currency":"USDC","receiver":"snack.money","description":"Payment to web domain"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentResponse"}}}},"400":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"402":{"description":"Payment Required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}},"500":{"description":"Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerError"}}}}}}},"/payments/github/pay":{"post":{"tags":["Payments","Github"],"summary":"Pay to github user","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequest"},"example":{"amount":1,"currency":"USDC","receiver":"mesutcelik","description":"Payment to Github user"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentResponse"}}}},"400":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"402":{"description":"Payment Required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}},"500":{"description":"Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerError"}}}}}}},"/payments/farcaster/batch-pay":{"post":{"tags":["Payments","Farcaster"],"summary":"Batch pay to farcaster users","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchPaymentRequest"},"example":{"currency":"USDC","receivers":[{"receiver":"snackmoney","amount":1},{"receiver":"anotheruser","amount":0.5}],"description":"Batch payment to Farcaster users"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchPaymentResponse"}}}},"400":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"402":{"description":"Payment Required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}},"500":{"description":"Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerError"}}}}}}},"/payments/x/batch-pay":{"post":{"tags":["Payments","X"],"summary":"Batch pay to X users","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchPaymentRequest"},"example":{"currency":"USDC","receivers":[{"receiver":"snackmoneyapp","amount":1},{"receiver":"anotheruser","amount":0.5}],"description":"Batch payment to X users"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchPaymentResponse"}}}},"400":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"402":{"description":"Payment Required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}},"500":{"description":"Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerError"}}}}}}},"/payments/email/batch-pay":{"post":{"tags":["Payments","Email"],"summary":"Batch pay to users via email","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchPaymentRequest"},"example":{"currency":"USDC","receivers":[{"receiver":"tips@snack.money","amount":1},{"receiver":"user@example.com","amount":0.5}],"description":"Batch payment via email"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchPaymentResponse"}}}},"400":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"402":{"description":"Payment Required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}},"500":{"description":"Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerError"}}}}}}},"/payments/web/batch-pay":{"post":{"tags":["Payments","Web"],"summary":"Batch pay to users via domain names","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchPaymentRequest"},"example":{"currency":"USDC","receivers":[{"receiver":"snack.money","amount":1},{"receiver":"example.com","amount":0.5}],"description":"Batch payment to web domains"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchPaymentResponse"}}}},"400":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"402":{"description":"Payment Required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}},"500":{"description":"Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerError"}}}}}}},"/payments/github/batch-pay":{"post":{"tags":["Payments","Github"],"summary":"Batch pay to users via github users","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchPaymentRequest"},"example":{"currency":"USDC","receivers":[{"receiver":"mesutcelik","amount":1},{"receiver":"jrsarath","amount":0.5}],"description":"Batch payment to Github users"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchPaymentResponse"}}}},"400":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"402":{"description":"Payment Required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}},"500":{"description":"Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerError"}}}}}}},"/payments/validate":{"get":{"tags":["Payments"],"summary":"Validate payment","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequest"},"example":{"amount":1,"currency":"USDC","receiver":"snackmoney","description":"Payment validation"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentResponse"}}}},"400":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"402":{"description":"Payment Required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}},"500":{"description":"Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerError"}}}}}}},"/agent/create":{"post":{"tags":["Agents"],"summary":"Create a new agent","description":"Creates a new agent with the specified configuration. Costs 0.03 USDC (3 cents) creation fee. The payer wallet becomes the agent owner. Agent name and personality are auto-generated by AI. After creation, customers (including the owner) must call agent.hire to use the agent.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentCreateAndFundRequest"},"example":{"config":{"socialConfig":{"interactions":{"like":0.01,"repost":0.02,"reply":0.05,"quote":0.03,"mention":0.1,"sentimentThreshold":7}}}}}}},"responses":{"201":{"description":"Agent created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentCreateAndFundResponse"},"example":{"success":true,"agentId":"agent_1704067200000_abc123","name":"generous-dolphin-5678","enabledFeatures":["boost","mention"],"url":"https://snack.money/agents/agent_1704067200000_abc123","mascotUrl":"https://storage.googleapis.com/...","createdAt":1704067200000}}}},"400":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"402":{"description":"Payment Required - 0.03 USDC creation fee","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}},"500":{"description":"Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerError"}}}}}}}}}