{"openapi":"3.1.0","info":{"title":"Agent Eternal Memory","version":"0.2.0","description":"Persistent storage for autonomous agents. Data survives VM restarts, tier downgrades, and death.","contact":{"url":"https://eternal-memory.xyz"},"license":{"name":"MIT"}},"servers":[{"url":"https://api.eternal-memory.xyz","description":"Production (Base mainnet)"}],"security":[{"erc8004":[]}],"components":{"securitySchemes":{"erc8004":{"type":"apiKey","in":"header","name":"Authorization","description":"ERC-8004 wallet signature. Format: `ERC8004 <base64-encoded JSON>`. The JSON contains: agentId (address), method, path, timestamp, nonce, and an EIP-712 signature over those fields."}},"schemas":{"StoredEntry":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"agent_id":{"type":"string","description":"Wallet address (lowercase)"},"namespace":{"type":"string","default":"default"},"key":{"type":"string"},"data_type":{"type":"string","enum":["kv","blob","vector"]},"blob_size_bytes":{"type":"integer","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"last_accessed_at":{"type":"string","format":"date-time"},"expires_at":{"type":"string","format":"date-time"}}},"PaymentRequirements":{"type":"object","description":"x402 v2 payment requirements returned in the payment-required header (base64 JSON) and response body.","properties":{"scheme":{"type":"string","enum":["exact"]},"network":{"type":"string","example":"eip155:8453","description":"CAIP-2 network identifier"},"amount":{"type":"string","description":"USDC atomic units (6 decimals). $0.001 = \"1000\""},"asset":{"type":"string","description":"USDC contract address"},"payTo":{"type":"string","description":"Payee wallet address"},"maxTimeoutSeconds":{"type":"integer","default":60},"extra":{"type":"object","properties":{"name":{"type":"string","example":"USD Coin"},"version":{"type":"string","example":"2"}}}}},"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}},"paths":{"/v1/store":{"post":{"summary":"Store data","description":"Store a key-value pair, blob, or vector embedding. Cost: $0.001 base + $0.001/KB.","tags":["Storage"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["key"],"properties":{"key":{"type":"string","description":"Unique key within the namespace"},"value":{"description":"Any JSON value (for kv and vector types)"},"namespace":{"type":"string","default":"default"},"embedding":{"type":"array","items":{"type":"number"},"description":"Float vector for semantic search (any dimension). Requires embeddedWith when provided."},"embeddingText":{"type":"string","description":"Text to embed server-side using all-MiniLM-L6-v2 (384-dim). Mutually exclusive with embedding. Surcharge: $0.0005."},"embeddedWith":{"type":"string","description":"Model name used to generate the client-side embedding (e.g. \"openai/text-embedding-3-small\"). Required when embedding is provided."},"dataType":{"type":"string","enum":["kv","blob","vector"],"description":"Auto-detected if omitted"},"blob":{"type":"string","format":"byte","description":"Base64-encoded binary data"},"ttlDays":{"type":"integer","minimum":1,"description":"Auto-expire after N days"}}}}}},"parameters":[{"name":"X-Idempotency-Key","in":"header","schema":{"type":"string"},"description":"Deduplicate writes within 24 hours"}],"responses":{"200":{"description":"Stored successfully","content":{"application/json":{"schema":{"type":"object","properties":{"stored":{"type":"boolean"},"entry":{"$ref":"#/components/schemas/StoredEntry"},"cost_usdc":{"type":"string","example":"0.00100000"}}}}}},"402":{"description":"Payment required. Read the `payment-required` header (base64 JSON) for PaymentRequirements, sign an EIP-3009 TransferWithAuthorization, and retry with the `payment-signature` header.","headers":{"payment-required":{"description":"Base64-encoded PaymentRequirements JSON","schema":{"type":"string"}}}}}}},"/v1/retrieve/{key}":{"get":{"summary":"Retrieve data","description":"Retrieve a stored value by key. Cost: $0.0005.","tags":["Storage"],"parameters":[{"name":"key","in":"path","required":true,"schema":{"type":"string"}},{"name":"namespace","in":"query","schema":{"type":"string","default":"default"}},{"name":"agent_id","in":"query","schema":{"type":"string"},"description":"Read from another agent (requires lineage grant)"}],"responses":{"200":{"description":"Entry found","content":{"application/json":{"schema":{"type":"object","properties":{"entry":{"$ref":"#/components/schemas/StoredEntry"},"data":{"description":"The stored value (JSON for kv/vector, base64 string for blob)"},"cost_usdc":{"type":"string"}}}}}},"402":{"description":"Payment required"},"403":{"description":"No lineage access to the target agent"},"404":{"description":"Key not found"}}}},"/v1/query":{"post":{"summary":"Semantic search","description":"Search stored vectors by cosine similarity. Send queryText for server-side embedding (recommended, +$0.0005 surcharge) or provide your own embedding with embeddedWith. Cost: $0.001 base.","tags":["Search"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"embedding":{"type":"array","items":{"type":"number"},"description":"Query vector (any dimension). Requires embeddedWith for model tracking."},"queryText":{"type":"string","description":"Text to embed server-side using all-MiniLM-L6-v2 (384-dim). Mutually exclusive with embedding. Surcharge: $0.0005."},"embeddedWith":{"type":"string","description":"Model name for the provided embedding. Used to filter results by matching model."},"namespace":{"type":"string","default":"default"},"limit":{"type":"integer","minimum":1,"maximum":100,"default":10},"threshold":{"type":"number","minimum":0,"maximum":1,"default":0,"description":"Minimum cosine similarity"}}}}}},"responses":{"200":{"description":"Search results sorted by similarity","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/StoredEntry"},{"type":"object","properties":{"similarity":{"type":"number","description":"Cosine similarity (0-1)"},"value":{"description":"The stored JSON value"}}}]}}}}}}},"402":{"description":"Payment required"}}}},"/v1/list":{"get":{"summary":"List entries","description":"List stored entries with pagination and filtering. Use `include=values` to return stored values inline (useful for bulk namespace restore). Cost: $0.0005.","tags":["Storage"],"parameters":[{"name":"namespace","in":"query","schema":{"type":"string"}},{"name":"dataType","in":"query","schema":{"type":"string","enum":["kv","blob","vector"]}},{"name":"prefix","in":"query","schema":{"type":"string"},"description":"Filter keys by prefix"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":1000,"default":100}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}},{"name":"include","in":"query","schema":{"type":"string","enum":["values"]},"description":"Include stored values in response (blob data still requires individual retrieve)"}],"responses":{"200":{"description":"Paginated entry list","content":{"application/json":{"schema":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/StoredEntry"}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}}}}}},"402":{"description":"Payment required"}}}},"/v1/delete/{key}":{"delete":{"summary":"Delete entry","description":"Delete a stored entry by key. Free operation.","tags":["Storage"],"parameters":[{"name":"key","in":"path","required":true,"schema":{"type":"string"}},{"name":"namespace","in":"query","schema":{"type":"string","default":"default"}}],"responses":{"200":{"description":"Deletion result","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean"}}}}}}}}},"/v1/share":{"post":{"summary":"Grant lineage access","description":"Grant another agent read/write/inherit access to your memory. Cost: $0.001.","tags":["Lineage"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["granteeId","accessLevel"],"properties":{"granteeId":{"type":"string","description":"Wallet address of the grantee agent"},"namespace":{"type":"string","description":"Limit grant to a specific namespace"},"keyPattern":{"type":"string","default":"*","description":"Glob pattern for key matching"},"accessLevel":{"type":"string","enum":["read","write","inherit"]}}}}}},"responses":{"201":{"description":"Grant created"},"402":{"description":"Payment required"}}},"get":{"summary":"List grants","description":"List all active lineage grants for the authenticated agent. Free.","tags":["Lineage"],"responses":{"200":{"description":"Active grants","content":{"application/json":{"schema":{"type":"object","properties":{"grants":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"owner_id":{"type":"string"},"grantee_id":{"type":"string"},"namespace":{"type":"string","nullable":true},"key_pattern":{"type":"string"},"access_level":{"type":"string"},"granted_at":{"type":"string","format":"date-time"},"revoked_at":{"type":"string","format":"date-time","nullable":true}}}}}}}}}}}},"/v1/share/{grantId}":{"delete":{"summary":"Revoke grant","description":"Revoke a lineage access grant. Free operation.","tags":["Lineage"],"parameters":[{"name":"grantId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Revocation result","content":{"application/json":{"schema":{"type":"object","properties":{"revoked":{"type":"boolean"}}}}}}}}},"/v1/export":{"get":{"summary":"Export all data","description":"Export all stored entries as JSON. Cost: $0.01 flat. Excluded from free tier — always requires payment.","tags":["Storage"],"parameters":[{"name":"namespace","in":"query","schema":{"type":"string"},"description":"Filter by namespace"}],"responses":{"200":{"description":"Array of all stored entries with data","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/StoredEntry"}}}}},"402":{"description":"Payment required"}}}},"/v1/status":{"get":{"summary":"Usage status","description":"Get storage statistics and cumulative usage costs. Free operation.","tags":["Account"],"responses":{"200":{"description":"Storage and usage summary","content":{"application/json":{"schema":{"type":"object","properties":{"storage":{"type":"object","properties":{"totalEntries":{"type":"integer"},"totalSizeBytes":{"type":"integer"},"namespaces":{"type":"array","items":{"type":"string"}},"oldestEntry":{"type":"string","format":"date-time","nullable":true},"newestEntry":{"type":"string","format":"date-time","nullable":true}}},"usage":{"type":"object","properties":{"totalCostUsdc":{"type":"number"},"totalOperations":{"type":"integer"},"byOperation":{"type":"object","additionalProperties":{"type":"object","properties":{"count":{"type":"integer"},"cost":{"type":"number"}}}}}}}}}}}}}},"/sdk-browser.js":{"get":{"summary":"Browser SDK bundle","description":"Pre-built browser-compatible SDK bundle (ESM, no Node.js built-ins). Uses WebCrypto for encryption. For use in browsers, Cloudflare Workers, Deno, and WASM environments.","tags":["System"],"security":[],"responses":{"200":{"description":"JavaScript bundle","content":{"application/javascript":{"schema":{"type":"string"}}}},"404":{"description":"Bundle not built"}}}},"/health":{"get":{"summary":"Health check","description":"Server health check. No authentication required.","tags":["System"],"security":[],"responses":{"200":{"description":"Server is healthy","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"ok"},"service":{"type":"string","example":"eternal-memory"},"version":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}}}}}}}}},"x-pricing":{"currency":"USDC","network":"Base (EIP-155:8453)","protocol":"x402 (HTTP 402 Payment Required)","operations":{"store":{"base":"$0.001","perKb":"$0.001"},"retrieve":{"base":"$0.0005"},"query":{"base":"$0.001"},"list":{"base":"$0.0005"},"share":{"base":"$0.001"},"delete":{"base":"Free"},"status":{"base":"Free"},"export":{"base":"$0.01"},"embed (surcharge)":{"base":"$0.0005","note":"Added when using embeddingText or queryText for server-side embedding"}}},"x-authentication":{"protocol":"ERC-8004","signing":"EIP-712 typed data","domain":{"name":"AgentEternalMemory","version":"1","chainId":8453},"types":{"AgentRequest":[{"name":"agentId","type":"address"},{"name":"method","type":"string"},{"name":"path","type":"string"},{"name":"timestamp","type":"uint256"},{"name":"nonce","type":"string"}]},"header":"Authorization: ERC8004 <base64(JSON({agentId, method, path, timestamp, nonce, signature}))>","timestampTolerance":"5 minutes"},"x-payments":{"protocol":"x402 v2","flow":["1. Client sends request with auth header","2. Server returns 402 with payment-required header (base64 PaymentRequirements)","3. Client signs EIP-3009 TransferWithAuthorization for USDC","4. Client retries with payment-signature header (base64 PaymentPayload)","5. Server verifies payment with facilitator","6. Server runs the handler and returns the result","7. Server settles payment on-chain via facilitator (async, after response)"],"headers":{"request":"payment-signature: <base64 PaymentPayload>","response402":"payment-required: <base64 PaymentRequirements>"}}}