🛠️ Key-Value Store

Persistent key-value storage for agents. Store any JSON-serializable value under a string key with a configurable TTL (default 24h, max 30 days). Keys are automatically namespaced per wallet address — no cross-tenant data leakage. Supports set, get, delete, and list operations.

💡 Flat $0.001 per operation (set, get, delete, or list)

Request Body

Parameter	Type	Required	Description	Default
`action`	string	required	Operation: set \| get \| delete \| list	—
`key`	string	optional	Key to operate on (required for set/get/delete, max 256 chars)	—
`value`	any	optional	Value to store (required for set, any JSON-serializable type, max 64 KB)	—
`ttl`	number	optional	Time-to-live in seconds (set only)	`86400`
`prefix`	string	optional	Key prefix filter (list only)	—

Response Fields

Field	Type	Description
`action`	string	Operation that was performed
`key`	string	Key that was operated on
`value`	any	Stored value (get only)
`ttl`	number	Remaining TTL in seconds
`found`	boolean	Whether the key existed (get only)
`keys`	array	List of matching keys (list only)
`count`	number	Number of keys returned (list only)
`success`	boolean	Whether the operation succeeded

Code Examples

cURL

bash

# Set a value
curl -X POST https://sparkforge.sh/api/store \
  -H "Content-Type: application/json" \
  -H "X-PAYMENT: <x402-payment-token>" \
  -d '{"action":"set","key":"my-agent-state","value":{"step":3,"done":false},"ttl":3600}'

# Get a value
curl -X POST https://sparkforge.sh/api/store \
  -H "Content-Type: application/json" \
  -H "X-PAYMENT: <x402-payment-token>" \
  -d '{"action":"get","key":"my-agent-state"}'

Python

python

import requests

headers = {"Content-Type": "application/json", "X-PAYMENT": "<token>"}

# Set
requests.post("https://sparkforge.sh/api/store", headers=headers,
    json={"action": "set", "key": "run-state", "value": {"step": 1}, "ttl": 3600})

# Get
r = requests.post("https://sparkforge.sh/api/store", headers=headers,
    json={"action": "get", "key": "run-state"})
data = r.json()
print(data["value"], data["ttl"])

TypeScript / Node.js

typescript

const set = await fetch402("https://sparkforge.sh/api/store", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ action: "set", key: "state", value: { step: 1 }, ttl: 3600 }),
});

const get = await fetch402("https://sparkforge.sh/api/store", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ action: "get", key: "state" }),
});
const { value, ttl, found } = await get.json();

Example Response

json

{
  "action": "get",
  "key": "my-agent-state",
  "value": { "step": 3, "done": false },
  "ttl": 3542,
  "found": true,
  "success": true
}

💳 Payment via x402

This endpoint costs $0.001 per call, paid in USDC on Base, Polygon, or Solana. Use the @x402/fetch library to handle payments automatically, or implement the x402 handshake manually.

bash

# Free demo mode (no payment)
curl https://sparkforge.sh/api/store?demo=true

# Or try via MCP (Claude Desktop, Cursor, Windsurf)
# Add to mcp config: { "url": "https://sparkforge.sh/api/mcp" }