{"openapi":"3.1.0","info":{"title":"Memwry API","version":"2.0.0","description":"Ephemeral working-memory storage service for AI agents with x402 cryptocurrency micropayments. The W is the write — it's the only thing that costs anything. Every GET endpoint is free and public.","contact":{"name":"Memwry Support","email":"jcabaluna12@gmail.com","url":"https://memwry.servitor.workers.dev"},"x-guidance":"Memwry is an ephemeral working-memory store for AI agents on Base using x402 micropayments. POST /mem/{agentId}/{key}/6h ($0.01) or /12h ($0.02) to store. Every GET endpoint is free and public. Free GET /mem/{agentId}/{key} to recall."},"servers":[{"url":"https://memwry.servitor.workers.dev","description":"Production Cloudflare Worker"}],"x-discovery":{"ownershipProofs":["0x47bA4b1360Acb4171C20273CFd7E11CEAAa20841","0x47bA4b1360Acb4171C20273CFd7E11CEAAa26c45"]},"x-agentcash-provenance":{"ownershipProofs":["0x47bA4b1360Acb4171C20273CFd7E11CEAAa20841","0x47bA4b1360Acb4171C20273CFd7E11CEAAa26c45"]},"x-agentcash-guidance":{"llmsTxtUrl":"https://memwry.servitor.workers.dev/llms.txt"},"paths":{"/mem/{agentId}/{key}/6h":{"post":{"summary":"Remember (Store) Memory — 6h Tier ($0.01 USDC)","description":"Store ephemeral working memory with 6-hour retention (21,600s TTL). Direct attached tier endpoint. Requires x402 payment ($0.01 USDC on Base).","security":[],"x-payment-protocol":"x402","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.01"},"protocols":[{"x402":{}}]},"parameters":[{"name":"agentId","in":"path","required":true,"example":"agent-123","schema":{"type":"string","example":"agent-123","pattern":"^[a-zA-Z0-9_-]{1,128}$"},"description":"Unique identifier for the calling agent (alphanumeric, hyphens, underscores; max 128 chars)."},{"name":"key","in":"path","required":true,"example":"task-context","schema":{"type":"string","example":"task-context","pattern":"^[a-zA-Z0-9_-]{1,128}$"},"description":"Scoped memory key under the agent namespace (alphanumeric, hyphens, underscores; max 128 chars)."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255,"example":"idem_agent-123_1789180713041_99d589a0-ea71-40d2-b32e-ef48c12268ed"},"description":"Unique request idempotency key (max 255 chars). Enforces a 24h deduplication window scoped to the request payload fingerprint. Retries with the same key replay the previous result without initiating a new x402 payment."},{"name":"PAYMENT-SIGNATURE","in":"header","required":false,"schema":{"type":"string"},"description":"EIP-3009 transferWithAuthorization signature, sent on the retry after a 402 PAYMENT-REQUIRED response. Required to complete the write; omitted on the first (unpaid) attempt."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Any structured JSON object to store in working memory (up to 512KB).","example":{"checkpoint":"step-3","summary":"analyzed contract"}}},"*/*":{"schema":{"type":"string","maxLength":524288,"description":"Any JSON value or raw text, max 512KB. Stored and returned verbatim, uninterpreted."}}}},"responses":{"200":{"description":"Memory stored, or idempotent replay returned","headers":{"PAYMENT-RESPONSE":{"schema":{"type":"string"},"description":"e.g. settled;txHash=0x... on first write, replayed on idempotent retry."},"X-Receipt":{"schema":{"type":"string"},"description":"Base64-encoded Engram receipt."},"X-Tier":{"schema":{"type":"string","enum":["6h"]},"description":"The tier written ('6h')."},"X-TTL-Seconds":{"schema":{"type":"string","example":"21600"},"description":"Active TTL in seconds."},"X-Price-USDC":{"schema":{"type":"string","example":"0.01"},"description":"Tier price in USDC."},"X-Expires-At":{"schema":{"type":"string","format":"date-time"},"description":"Exact timestamp when the memory expires."},"X-Idempotent-Replay":{"schema":{"type":"string","enum":["true"]},"description":"Present with value 'true' when this response is a cached replay from a previous idempotent request."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Engram"}}}},"400":{"description":"Malformed request or Idempotency-Key exceeds 255 characters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"idempotency_key_too_long"}}}}}},"402":{"description":"Payment required — retry with PAYMENT-SIGNATURE header ($0.01 USDC on Base)","headers":{"PAYMENT-REQUIRED":{"schema":{"type":"string"}},"X-Payment-Protocol":{"schema":{"type":"string","example":"x402"}},"X-Tier":{"schema":{"type":"string","example":"6h"}},"X-Price-USDC":{"schema":{"type":"string","example":"0.01"}},"X-TTL-Seconds":{"schema":{"type":"string","example":"21600"}}}},"409":{"description":"Idempotent request already in progress with this key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"idempotent_request_in_progress"}}}}}},"413":{"description":"Payload exceeds 512KB"},"422":{"description":"Idempotency key reused with a different payload or path","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"idempotency_key_reused"}}}}}},"502":{"description":"Settlement or write failed"}}}},"/mem/{agentId}/{key}/12h":{"post":{"summary":"Remember (Store) Memory — 12h Tier ($0.02 USDC)","description":"Store ephemeral working memory with 12-hour retention (43,200s TTL). Direct attached tier endpoint. Requires x402 payment ($0.02 USDC on Base).","security":[],"x-payment-protocol":"x402","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.02"},"protocols":[{"x402":{}}]},"parameters":[{"name":"agentId","in":"path","required":true,"example":"agent-123","schema":{"type":"string","example":"agent-123","pattern":"^[a-zA-Z0-9_-]{1,128}$"},"description":"Unique identifier for the calling agent (alphanumeric, hyphens, underscores; max 128 chars)."},{"name":"key","in":"path","required":true,"example":"task-context","schema":{"type":"string","example":"task-context","pattern":"^[a-zA-Z0-9_-]{1,128}$"},"description":"Scoped memory key under the agent namespace (alphanumeric, hyphens, underscores; max 128 chars)."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255,"example":"idem_agent-123_1789180713041_99d589a0-ea71-40d2-b32e-ef48c12268ed"},"description":"Unique request idempotency key (max 255 chars). Enforces a 24h deduplication window scoped to the request payload fingerprint. Retries with the same key replay the previous result without initiating a new x402 payment."},{"name":"PAYMENT-SIGNATURE","in":"header","required":false,"schema":{"type":"string"},"description":"EIP-3009 transferWithAuthorization signature, sent on the retry after a 402 PAYMENT-REQUIRED response. Required to complete the write; omitted on the first (unpaid) attempt."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Any structured JSON object to store in working memory (up to 512KB).","example":{"checkpoint":"step-3","summary":"analyzed contract"}}},"*/*":{"schema":{"type":"string","maxLength":524288,"description":"Any JSON value or raw text, max 512KB. Stored and returned verbatim, uninterpreted."}}}},"responses":{"200":{"description":"Memory stored, or idempotent replay returned","headers":{"PAYMENT-RESPONSE":{"schema":{"type":"string"},"description":"e.g. settled;txHash=0x... on first write, replayed on idempotent retry."},"X-Receipt":{"schema":{"type":"string"},"description":"Base64-encoded Engram receipt."},"X-Tier":{"schema":{"type":"string","enum":["12h"]},"description":"The tier written ('12h')."},"X-TTL-Seconds":{"schema":{"type":"string","example":"43200"},"description":"Active TTL in seconds."},"X-Price-USDC":{"schema":{"type":"string","example":"0.02"},"description":"Tier price in USDC."},"X-Expires-At":{"schema":{"type":"string","format":"date-time"},"description":"Exact timestamp when the memory expires."},"X-Idempotent-Replay":{"schema":{"type":"string","enum":["true"]},"description":"Present with value 'true' when this response is a cached replay from a previous idempotent request."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Engram"}}}},"400":{"description":"Malformed request or Idempotency-Key exceeds 255 characters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"idempotency_key_too_long"}}}}}},"402":{"description":"Payment required — retry with PAYMENT-SIGNATURE header ($0.02 USDC on Base)","headers":{"PAYMENT-REQUIRED":{"schema":{"type":"string"}},"X-Payment-Protocol":{"schema":{"type":"string","example":"x402"}},"X-Tier":{"schema":{"type":"string","example":"12h"}},"X-Price-USDC":{"schema":{"type":"string","example":"0.02"}},"X-TTL-Seconds":{"schema":{"type":"string","example":"43200"}}}},"409":{"description":"Idempotent request already in progress with this key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"idempotent_request_in_progress"}}}}}},"413":{"description":"Payload exceeds 512KB"},"422":{"description":"Idempotency key reused with a different payload or path","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"idempotency_key_reused"}}}}}},"502":{"description":"Settlement or write failed"}}}},"/mem/{agentId}/{key}":{"get":{"summary":"Recall Memory (Free & Public)","description":"Recall stored working memory by agentId and key. Free and public operation — no payment, no authentication, and no API keys required. Rate limited to 100 reads per hour per IP.","security":[],"x-public":true,"x-is-public":true,"x-free":true,"x-pricing":"free","x-price":"free","x-price-usdc":"free","x-status":"public","x-access":"public","x-payment-protocol":"none","x-auth-mode":"unprotected","parameters":[{"name":"agentId","in":"path","required":true,"example":"agent-123","schema":{"type":"string","example":"agent-123","pattern":"^[a-zA-Z0-9_-]{1,128}$"},"description":"Unique identifier for the calling agent (alphanumeric, hyphens, underscores; max 128 chars)."},{"name":"key","in":"path","required":true,"example":"task-context","schema":{"type":"string","example":"task-context","pattern":"^[a-zA-Z0-9_-]{1,128}$"},"description":"Scoped memory key under the agent namespace (alphanumeric, hyphens, underscores; max 128 chars)."}],"responses":{"200":{"description":"Stored memory returned verbatim (bytes in = bytes out)","headers":{"X-Payment-Status":{"schema":{"type":"string","example":"free"},"description":"Payment status for the operation ('free')."},"X-Public":{"schema":{"type":"string","example":"true"},"description":"Public access flag ('true')."},"X-Access":{"schema":{"type":"string","example":"public"},"description":"Access tier ('public')."},"X-Price-USDC":{"schema":{"type":"string","example":"free"},"description":"Price in USDC for recall operation ('free')."},"X-Agent-ID":{"schema":{"type":"string","example":"agent-123"},"description":"The agent ID associated with the memory."},"X-Expires-At":{"schema":{"type":"string","format":"date-time"},"description":"The exact timestamp when this memory self-destructs."},"X-Tier":{"schema":{"type":"string","enum":["6h","12h"]},"description":"The active tier duration of the stored memory ('6h' or '12h')."},"X-TTL-Seconds":{"schema":{"type":"string","example":"21600"},"description":"Remaining total TTL duration in seconds for the tier."}},"content":{"*/*":{"schema":{"type":"string"}}}},"404":{"description":"Memory not found or already forgotten (TTL expired)"},"429":{"description":"Read rate limit exceeded (100/hour/IP)"}}}}},"components":{"securitySchemes":{"WalletAuth":{"type":"apiKey","in":"header","name":"SIGN-IN-WITH-X","x-agentcash-auth-kind":"siwx","description":"Optional wallet authentication via SIWX"}},"schemas":{"Engram":{"type":"object","required":["service","receiptId","agentId","key","tier","amount","currency","network","txHash","paidAt","expiresAt","ttlSeconds"],"properties":{"service":{"type":"string","example":"memwry"},"receiptId":{"type":"string","example":"d3b07384-d113-4819-8671-ec5bb79116a4"},"agentId":{"type":"string","example":"agent-123"},"key":{"type":"string","example":"goal"},"tier":{"type":"string","enum":["6h","12h"],"example":"6h"},"amount":{"type":"string","example":"10000"},"currency":{"type":"string","example":"USDC"},"network":{"type":"string","example":"eip155:8453"},"txHash":{"type":"string","pattern":"^0x[a-fA-F0-9]{64}$","example":"0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcd"},"paidAt":{"type":"string","format":"date-time","example":"2026-08-23T09:42:18Z"},"expiresAt":{"type":"string","format":"date-time","example":"2026-08-23T15:42:18Z"},"ttlSeconds":{"type":"integer","example":21600}}}}}}