{"openapi":"3.1.0","info":{"title":"x402-vector API","version":"0.0.1","description":"Pay-per-call memory and vector state for AI agents. The wallet that signs the x402 payment owns the namespace.","contact":{"url":"https://x402vector.com"},"x-guidance":"Use PUT /v1/memory to store compact JSON memories, GET /v1/memory/{key} to retrieve known keys, POST /v1/search for semantic recall, and POST /v1/memory/batch to persist multiple memories. Paid endpoints use x402 over Base USDC; the paying wallet owns the namespace."},"servers":[{"url":"https://api.x402vector.com","description":"Production API"}],"externalDocs":{"url":"https://x402vector.com","description":"x402-vector web docs"},"paths":{"/v1/memory":{"put":{"operationId":"memoryWrite","summary":"Store one memory item","description":"Stores one JSON-serializable memory item in the paying wallet namespace, hot-buffers it immediately, and queues durable persistence plus embedding.\n\nPrice: $0.002 USDC per call.","tags":["Memory"],"security":[{"x402PaymentSignature":[]}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.002"},"protocols":[{"x402":{}}]},"parameters":[{"name":"PAYMENT-SIGNATURE","in":"header","required":false,"description":"x402 v2 payment signature. Omit it to receive a 402 quote.","schema":{"type":"string"}},{"name":"X-PAYMENT","in":"header","required":false,"description":"Legacy x402 payment header accepted for compatibility.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"key":{"type":"string","pattern":"^[A-Za-z0-9._:-]{1,256}$"},"value":{}},"required":["key","value"],"additionalProperties":false},"example":{"key":"project:last-brief","value":{"text":"The user prefers concise implementation plans and exact file references.","tags":["preference","brief"]}}}}},"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"accepted":{"type":"boolean","const":true},"key":{"type":"string","pattern":"^[A-Za-z0-9._:-]{1,256}$"},"namespace":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"contentHash":{"type":"string","minLength":1}},"required":["accepted","key","namespace","contentHash"],"additionalProperties":false},"example":{"accepted":true,"key":"project:last-brief","namespace":"0x1111111111111111111111111111111111111111","contentHash":"3f786850e387550fdab836ed7e6dc881de23001b"}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"402":{"description":"Payment required. Repeat the request with a valid x402 payment header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}}}}},"/v1/memory/batch":{"post":{"operationId":"memoryBatch","summary":"Store a batch of memory items","description":"Stores up to 100 JSON-serializable memory items in the paying wallet namespace for a flat batch price.\n\nPrice: $0.05 USDC per call.","tags":["Memory"],"security":[{"x402PaymentSignature":[]}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.05"},"protocols":[{"x402":{}}]},"parameters":[{"name":"PAYMENT-SIGNATURE","in":"header","required":false,"description":"x402 v2 payment signature. Omit it to receive a 402 quote.","schema":{"type":"string"}},{"name":"X-PAYMENT","in":"header","required":false,"description":"Legacy x402 payment header accepted for compatibility.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"items":{"minItems":1,"maxItems":100,"type":"array","items":{"type":"object","properties":{"key":{"type":"string","pattern":"^[A-Za-z0-9._:-]{1,256}$"},"value":{}},"required":["key","value"],"additionalProperties":false}}},"required":["items"],"additionalProperties":false},"example":{"items":[{"key":"task:123:summary","value":{"text":"Investigate the billing webhook."}},{"key":"task:123:status","value":{"state":"in-progress"}}]}}}},"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"accepted":{"type":"boolean","const":true},"keys":{"minItems":1,"maxItems":100,"type":"array","items":{"type":"string","pattern":"^[A-Za-z0-9._:-]{1,256}$"}},"namespace":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"}},"required":["accepted","keys","namespace"],"additionalProperties":false},"example":{"accepted":true,"keys":["task:123:summary","task:123:status"],"namespace":"0x1111111111111111111111111111111111111111"}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"402":{"description":"Payment required. Repeat the request with a valid x402 payment header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}}}}},"/v1/memory/{key}":{"get":{"operationId":"memoryRead","summary":"Read one memory item","description":"Reads one item by key from the paying wallet namespace, checking the hot buffer before durable Postgres storage.\n\nPrice: $0.001 USDC per call.","tags":["Memory"],"security":[{"x402PaymentSignature":[]}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.001"},"protocols":[{"x402":{}}]},"parameters":[{"name":"key","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9._:-]{1,256}$"},"example":"project:last-brief"},{"name":"PAYMENT-SIGNATURE","in":"header","required":false,"description":"x402 v2 payment signature. Omit it to receive a 402 quote.","schema":{"type":"string"}},{"name":"X-PAYMENT","in":"header","required":false,"description":"Legacy x402 payment header accepted for compatibility.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"key":{"type":"string","pattern":"^[A-Za-z0-9._:-]{1,256}$"},"value":{},"namespace":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"source":{"type":"string","enum":["hot","durable"]},"contentHash":{"type":"string","minLength":1}},"required":["key","value","namespace","source","contentHash"],"additionalProperties":false},"example":{"key":"project:last-brief","value":{"text":"The user prefers concise implementation plans and exact file references."},"namespace":"0x1111111111111111111111111111111111111111","source":"durable","contentHash":"3f786850e387550fdab836ed7e6dc881de23001b"}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"402":{"description":"Payment required. Repeat the request with a valid x402 payment header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}},"404":{"description":"Memory item not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"operationId":"memoryDelete","summary":"Delete one memory item","description":"Deletes one item from the signer wallet namespace. This endpoint is free and authenticated with a short-lived EIP-191 wallet signature.\n\nPrice: Free.","tags":["Memory"],"security":[],"parameters":[{"name":"key","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9._:-]{1,256}$"},"example":"project:last-brief"},{"name":"X-WALLET-ADDRESS","in":"header","required":true,"description":"EVM wallet address expected to recover from the delete signature.","schema":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"}},{"name":"X-WALLET-SIGNATURE","in":"header","required":true,"description":"EIP-191 signature over x402-vector-delete:{key}:{unix-minute}.","schema":{"type":"string"}}],"responses":{"204":{"description":"Deleted."},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"404":{"description":"Memory item not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/search":{"post":{"operationId":"search","summary":"Search wallet-scoped memory","description":"Embeds a query and returns nearest memory items from the paying wallet namespace only.\n\nPrice: $0.01 USDC per call.","tags":["Search"],"security":[{"x402PaymentSignature":[]}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.01"},"protocols":[{"x402":{}}]},"parameters":[{"name":"PAYMENT-SIGNATURE","in":"header","required":false,"description":"x402 v2 payment signature. Omit it to receive a 402 quote.","schema":{"type":"string"}},{"name":"X-PAYMENT","in":"header","required":false,"description":"Legacy x402 payment header accepted for compatibility.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"query":{"type":"string","minLength":1},"topK":{"default":10,"type":"integer","minimum":1,"maximum":50}},"required":["query","topK"],"additionalProperties":false},"example":{"query":"What does the user prefer for implementation plans?","topK":10}}}},"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"namespace":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"results":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","pattern":"^[A-Za-z0-9._:-]{1,256}$"},"value":{},"score":{"type":"number"},"contentHash":{"type":"string","minLength":1},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["key","value","score","contentHash","updatedAt"],"additionalProperties":false}}},"required":["namespace","results"],"additionalProperties":false},"example":{"namespace":"0x1111111111111111111111111111111111111111","results":[{"key":"project:last-brief","value":{"text":"The user prefers concise implementation plans and exact file references."},"score":0.91,"contentHash":"3f786850e387550fdab836ed7e6dc881de23001b","updatedAt":"2026-06-17T12:00:00.000Z"}]}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"402":{"description":"Payment required. Repeat the request with a valid x402 payment header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}}}}},"/v1/namespace":{"get":{"operationId":"namespaceInfo","summary":"Preview namespace status","description":"Returns public non-sensitive namespace metadata for an EVM address: item count, bytes used, rent status, and expiry timestamps.\n\nPrice: Free.","tags":["Namespace"],"security":[],"parameters":[{"name":"address","in":"query","required":true,"schema":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"example":"0x1111111111111111111111111111111111111111"}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"address":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"itemCount":{"type":"integer","minimum":0,"maximum":9007199254740991},"bytesUsed":{"type":"string","pattern":"^\\d+$"},"rentPaidUntil":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},{"type":"null"}]},"graceEndsAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},{"type":"null"}]},"status":{"type":"string","enum":["active","grace","expired"]},"softDeletedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},{"type":"null"}]}},"required":["address","itemCount","bytesUsed","rentPaidUntil","graceEndsAt","status","softDeletedAt"],"additionalProperties":false},"example":{"address":"0x1111111111111111111111111111111111111111","itemCount":12,"bytesUsed":"49152","rentPaidUntil":"2026-07-17T12:00:00.000Z","graceEndsAt":"2026-07-31T12:00:00.000Z","status":"active","softDeletedAt":null}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}}}}}},"components":{"securitySchemes":{"x402PaymentSignature":{"type":"apiKey","in":"header","name":"PAYMENT-SIGNATURE","description":"x402 v2 payment signature header."},"legacyXPayment":{"type":"apiKey","in":"header","name":"X-PAYMENT","description":"Legacy x402 payment header accepted for compatibility."},"walletAddress":{"type":"apiKey","in":"header","name":"X-WALLET-ADDRESS","description":"Wallet address used with free signed delete requests."},"walletSignature":{"type":"apiKey","in":"header","name":"X-WALLET-SIGNATURE","description":"EIP-191 signature over x402-vector-delete:{key}:{unix-minute}; current or previous minute accepted."}},"schemas":{"PaymentRequired":{"type":"object","properties":{"x402Version":{"type":"integer","const":2},"resource":{"type":"object","additionalProperties":true},"accepts":{"type":"array","items":{"type":"object","additionalProperties":true}},"extensions":{"type":"object","additionalProperties":true}},"required":["x402Version","resource","accepts"],"additionalProperties":true},"ErrorResponse":{"type":"object","properties":{"error":{},"message":{},"statusCode":{"type":"integer"}},"additionalProperties":true}}}}