{ "schema_version": "1.0", "name": "Foldr.Space", "description": "Agent-native file infrastructure. Upload files, manage permanent URLs, hand off resources between agents via capability tokens. REST API + MCP server. Pay 5¢ USDC per upload via x402 (HTTP 402, Base mainnet) — or pre-fund credits via Stripe. Pro tier ($25/mo) bypasses per-call charges. Also a consumer file-sharing product (web + free iOS app).", "url": "https://foldr.space", "logo_url": "https://foldr.space/foldr-logo.png", "contact": "hello@foldr.space", "docs_url": "https://foldr.space/developers/docs", "agent_guide_url": "https://foldr.space/agents", "for_ai_url": "https://foldr.space/for-ai", "llms_txt_url": "https://foldr.space/llms.txt", "llms_full_txt_url": "https://foldr.space/llms-full.txt", "openapi_url": "https://foldr.space/openapi.json", "x402_landing_url": "https://foldr.space/x402", "upload_tutorial_url": "https://foldr.space/agents/upload-api", "privacy_policy_url": "https://foldr.space/privacy", "terms_of_service_url": "https://foldr.space/terms", "product_summary": { "tagline": "S3 for AI agents. 5¢ per upload via x402.", "primary_use_case": "Programmatic file storage for autonomous agents. Upload, share, and revoke access to files via REST or MCP, paying per-upload in USDC on Base.", "key_differentiators": [ "x402 micropayments — pay 5¢ USDC per upload, no subscription required", "Idempotency-Key on every write endpoint (Stripe-style replay safety)", "Capability tokens — short-lived, use-capped, revocable share links for agent-to-agent file handoff", "Per-API-key folder namespaces with hierarchy", "Webhooks for file/capability lifecycle with HMAC signing", "MCP server (streamable-http) with 23+ tools for Claude Desktop, Cursor, Windsurf, etc.", "OpenAPI 3.1 spec for codegen", "Range/206 partial content for resumable downloads" ], "alternatives_to": [ "S3 + presigned URLs (for agent workloads)", "Cloudflare R2 (for agent workloads)", "Tigris", "Bunny Storage", "WeTransfer (for the consumer side)", "Dropbox / Google Drive (for the consumer side)" ], "ideal_for": [ "Autonomous agents that hold a Base wallet", "AI workflows that need ephemeral or permanent file storage", "Agent-to-agent file handoff (capability tokens)", "MCP-compatible AI tools (Claude Desktop, Cursor, Windsurf, Cline, Continue)", "Developers building on top of Anthropic / OpenAI APIs that need a file backend" ] }, "mobile_app": { "platform": "iOS", "name": "Foldr.Space — File Sharing", "url": "https://apps.apple.com/us/app/foldr-space-file-sharing/id6756532777", "price": "Free", "description": "Consumer-side iOS app for human file sharing on iPhone. Separate from the agent API." }, "auth": { "type": "bearer", "format": "fs_{32_alphanumeric}", "header": "Authorization: Bearer fs_xxx...", "signup_url": "https://foldr.space/developers/signup", "programmatic_registration": "POST https://foldr.space/api/v1/auth/register", "docs_url": "https://foldr.space/developers/docs", "notes": "API key identifies the agent and scopes ownership of files/folders/capabilities. Payment is separate — see `payment` below." }, "onboarding": { "description": "Three programmatic calls and you're uploading. No browser required.", "steps": [ { "step": 1, "method": "POST", "url": "https://foldr.space/api/v1/auth/register", "body": { "email": "agent@example.com" }, "returns": "API key (fs_xxx) on default tier", "auth_required": false, "rate_limit": "3 registrations / hour / IP" }, { "step": 2, "method": "POST", "url": "https://foldr.space/api/v1/files", "headers": "Authorization: Bearer fs_xxx", "body": "multipart/form-data with file field", "returns": "402 Payment Required with x402 envelope on first call", "auth_required": true, "note": "Agent signs a USDC transferWithAuthorization payload from the 402 accepts[] requirements, retries with X-PAYMENT header. Or top up account credits to skip x402." }, { "step": 3, "method": "POST", "url": "https://foldr.space/api/v1/auth/upgrade", "body": { "tier": "pro" }, "returns": "Subscription confirmation. Pro+ keys bypass per-call upload charges entirely.", "auth_required": true, "optional": true } ] }, "payment": { "model": "x402_or_credits", "currencies": ["USDC", "USD"], "x402": { "description": "Per-upload micropayment in USDC on Base. Server returns 402 with payment requirements; agent signs and retries with X-PAYMENT header.", "network": "base", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "recipient": "0x0fF790fBBF1D26E533cCaf9c9C01EBE728509f74", "facilitator": "https://x402.org/facilitator", "amount_per_upload_atomic": "50000", "amount_per_upload_cents": 5, "landing_page": "https://foldr.space/x402", "tutorial": "https://foldr.space/agents/upload-api" }, "credits": { "description": "Pre-fund a Stripe-backed credits ledger. Same 5¢ per upload, debited from balance instead of paid via x402. Useful for agents without a Base wallet.", "check_balance": "GET /api/v1/agent/account", "top_up": "POST /api/v1/agent/account/top-up", "min_top_up_cents": 500 }, "subscription_bypass": { "description": "Pro tier ($25/mo) and Enterprise ($100/mo) bypass per-call charges entirely.", "tiers_url": "https://foldr.space/developers/pricing" } }, "pricing_model": "per_upload_or_subscription", "reliability": { "health_url": "https://foldr.space/api/v1/health", "description": "Real-time uptime, latency p50/p95/p99, throughput, and success rate", "response_headers": [ "X-Foldr-Cost", "X-Foldr-Balance-Remaining", "X-Foldr-Processing-Ms", "X-Foldr-Request-Id", "X-Foldr-Uptime", "X-Foldr-Latency-P95" ] }, "api": { "type": "rest", "base_url": "https://foldr.space/api/v1", "version": "v1", "content_types": ["application/json", "multipart/form-data"], "openapi_spec": "https://foldr.space/openapi.json", "capabilities_url": "https://foldr.space/api/v1/agent/capabilities", "info_url": "https://foldr.space/api/v1/info", "idempotency": { "header": "Idempotency-Key", "scope": "All POST/PUT/PATCH endpoints", "ttl": "24h", "behavior": "Same key + same body replays original 2xx with Idempotent-Replayed: true. Same key + different body returns 422. In-flight duplicate returns 409 with Retry-After." }, "range_downloads": { "endpoint": "GET /api/v1/files/{id}", "spec": "RFC 7233 — Range: bytes=A-B → 206 Partial Content + Content-Range" } }, "mcp": { "url": "https://foldr.space/api/mcp", "transport": "streamable-http", "description": "MCP server for Claude Desktop, Cursor, Windsurf, Cline, Continue, and any MCP-compatible client. Uploads via this transport debit account credits (5¢ each) — x402 is HTTP-only.", "tools_count": 23, "tools": [ "upload_file", "bulk_upload", "list_files", "get_file_info", "delete_file", "generate_share_link", "update_file_metadata", "move_file", "create_folder", "list_folders", "list_folder_files", "delete_folder", "mint_capability", "list_capabilities", "revoke_capability", "create_webhook", "list_webhooks", "delete_webhook", "create_short_url", "check_balance", "top_up_credits", "list_transactions", "get_usage" ], "resources": [ "foldr://platform", "foldr://api-docs", "foldr://pricing", "foldr://health" ] }, "primitives": { "idempotency_key": "Stripe-style replay safety on every write endpoint.", "capability_tokens": "cap_… tokens — time-bounded (default 1h, max 7d), optionally use-capped, revocable. Redeem via Authorization: Capability cap_… or ?capability= query.", "agent_folders": "Per-API-key slug-addressed folder namespace with parent_slug hierarchy.", "webhooks": "HMAC-signed deliveries with retry backoff (1m / 5m / 15m). Events: file.uploaded, file.deleted, file.metadata_updated, capability.minted, capability.revoked.", "metadata": "Free-form JSON metadata on files with GIN/trigram-indexed search (q=, metadata= filters)." }, "sdks": { "python": "sdks/python/foldrspace.py", "typescript": "sdks/typescript/foldrspace.ts", "errors": "PaymentRequiredError on 402 carries the accepts[] envelope so agents can sign and retry." } }