{ "openapi": "3.1.0", "info": { "title": "TempoKey REST API", "version": "0.1.0", "description": "Hosted payments use Tempo Mainnet (4217). Membership endpoints describe the separate Robinhood testnet pilot (46630). The API stores delegated keys encrypted for authenticated execution. Do not submit an owner wallet private key." }, "servers": [ { "url": "https://api.tempokey.xyz", "description": "Mainnet payment API" } ], "externalDocs": { "description": "Developer documentation", "url": "https://www.tempokey.xyz/docs/api" }, "tags": [ { "name": "Agents", "description": "Delegated key registration and execution" }, { "name": "Membership", "description": "Public testnet membership metadata" }, { "name": "Health", "description": "Process and network configuration" } ], "paths": { "/api/health": { "get": { "operationId": "health", "summary": "Read configured chain and process health", "tags": [ "Health" ], "security": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/agent/register": { "post": { "operationId": "registerAgent", "summary": "Register an already authorized mainnet P256 key", "tags": [ "Agents" ], "security": [], "responses": { "200": { "description": "Save the returned Bearer token securely. Re-registration replaces the prior token.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "agentId", "bearerToken" ], "properties": { "success": { "const": true }, "agentId": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "bearerToken": { "type": "string", "description": "Opaque execution credential, returned at registration." }, "message": { "type": "string" } } } } } }, "400": { "description": "Request rejected or execution failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected or execution failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request body exceeds the 16 KiB limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected or execution failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request rejected or execution failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Registration" } } } } } }, "/api/agent/list/{ownerAddress}": { "get": { "operationId": "listAgents", "summary": "List public registration metadata for an owner", "tags": [ "Agents" ], "security": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Request rejected or execution failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "ownerAddress", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } } ] } }, "/api/agent/{agentId}/pay": { "post": { "operationId": "pay", "summary": "Send a PathUSD or USDC.e payment", "tags": [ "Agents" ], "security": [ { "agentBearer": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true } }, "additionalProperties": true } } }, "headers": { "X-Membership-Tier": { "description": "Present on applicable charged routes.", "schema": { "type": "string" } }, "X-Membership-Status": { "description": "Present on applicable charged routes.", "schema": { "type": "string" } }, "X-Usage-Limit-Daily": { "description": "Present on applicable charged routes.", "schema": { "type": "string" } }, "X-Usage-Remaining-Daily": { "description": "Present on applicable charged routes.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds before retrying, when supplied.", "schema": { "type": "string" } } } }, "400": { "description": "Request rejected or execution failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected or execution failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected or execution failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected or execution failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request body exceeds the 16 KiB limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected or execution failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request rejected or execution failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } }, { "name": "Idempotency-Key", "in": "header", "schema": { "type": "string", "maxLength": 128 }, "description": "Unique logical request ID. Reuse with an identical request when retrying; completed results have a bounded 24-hour window." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } } } } }, "/api/agent/{agentId}/batch": { "post": { "operationId": "batchPay", "summary": "Send 1-50 sequential pathUSD payments", "tags": [ "Agents" ], "security": [ { "agentBearer": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true } }, "additionalProperties": true } } }, "headers": { "X-Membership-Tier": { "description": "Present on applicable charged routes.", "schema": { "type": "string" } }, "X-Membership-Status": { "description": "Present on applicable charged routes.", "schema": { "type": "string" } }, "X-Usage-Limit-Daily": { "description": "Present on applicable charged routes.", "schema": { "type": "string" } }, "X-Usage-Remaining-Daily": { "description": "Present on applicable charged routes.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds before retrying, when supplied.", "schema": { "type": "string" } } } }, "400": { "description": "Request rejected or execution failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected or execution failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected or execution failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected or execution failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request body exceeds the 16 KiB limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected or execution failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request rejected or execution failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } }, { "name": "Idempotency-Key", "in": "header", "schema": { "type": "string", "maxLength": 128 }, "description": "Unique logical request ID. Reuse with an identical request when retrying; completed results have a bounded 24-hour window." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Batch" } } } } } }, "/api/agent/{agentId}/balance": { "get": { "operationId": "balance", "summary": "Read the owner token balance", "tags": [ "Agents" ], "security": [ { "agentBearer": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }, "headers": { "X-Membership-Tier": { "description": "Present on applicable charged routes.", "schema": { "type": "string" } }, "X-Membership-Status": { "description": "Present on applicable charged routes.", "schema": { "type": "string" } }, "X-Usage-Limit-Daily": { "description": "Present on applicable charged routes.", "schema": { "type": "string" } }, "X-Usage-Remaining-Daily": { "description": "Present on applicable charged routes.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds before retrying, when supplied.", "schema": { "type": "string" } } } }, "401": { "description": "Request rejected or execution failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected or execution failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request rejected or execution failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } }, { "name": "token", "in": "query", "schema": { "type": "string" }, "description": "Defaults to PathUSD; registered token addresses are also accepted." } ] } }, "/api/agent/{agentId}/status": { "get": { "operationId": "agentStatus", "summary": "Read key status, pathUSD allowance and call permissions", "tags": [ "Agents" ], "security": [ { "agentBearer": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }, "headers": { "X-Membership-Tier": { "description": "Present on applicable charged routes.", "schema": { "type": "string" } }, "X-Membership-Status": { "description": "Present on applicable charged routes.", "schema": { "type": "string" } }, "X-Usage-Limit-Daily": { "description": "Present on applicable charged routes.", "schema": { "type": "string" } }, "X-Usage-Remaining-Daily": { "description": "Present on applicable charged routes.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds before retrying, when supplied.", "schema": { "type": "string" } } } }, "401": { "description": "Request rejected or execution failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected or execution failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request rejected or execution failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } } ] } }, "/api/agent/{agentId}/usage": { "get": { "operationId": "agentUsage", "summary": "Read shared owner usage counters; this read has no owner quota charge", "tags": [ "Agents" ], "security": [ { "agentBearer": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }, "headers": { "X-Membership-Tier": { "description": "Present on applicable charged routes.", "schema": { "type": "string" } }, "X-Membership-Status": { "description": "Present on applicable charged routes.", "schema": { "type": "string" } }, "X-Usage-Limit-Daily": { "description": "Present on applicable charged routes.", "schema": { "type": "string" } }, "X-Usage-Remaining-Daily": { "description": "Present on applicable charged routes.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds before retrying, when supplied.", "schema": { "type": "string" } } } }, "401": { "description": "Request rejected or execution failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected or execution failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request rejected or execution failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } } ] } }, "/api/membership/config": { "get": { "operationId": "membershipConfig", "summary": "Read public pilot contracts, tiers and quotas", "tags": [ "Membership" ], "security": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/membership/position/{owner}": { "get": { "operationId": "membershipPosition", "summary": "Read the confirmed Robinhood testnet position", "tags": [ "Membership" ], "security": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Request rejected or execution failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected or execution failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected or execution failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "owner", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } } ] } } }, "components": { "securitySchemes": { "agentBearer": { "type": "http", "scheme": "bearer", "bearerFormat": "Opaque token" } }, "schemas": { "Error": { "type": "object", "required": [ "success", "error" ], "properties": { "success": { "const": false }, "error": { "type": "string" }, "code": { "type": "string" }, "retryAfter": { "type": "integer", "minimum": 0 } } }, "Payment": { "type": "object", "required": [ "to", "amount" ], "properties": { "to": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "amount": { "type": "number", "exclusiveMinimum": 0, "minimum": 0.000001, "description": "Human token units. Use at most six decimal places." }, "token": { "type": "string", "maxLength": 64, "description": "PathUSD (default), USDC.e, or their registered mainnet addresses." } } }, "Batch": { "type": "object", "required": [ "entries" ], "properties": { "entries": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "object", "required": [ "to", "amount" ], "properties": { "to": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "amount": { "type": "number", "minimum": 0.000001 } } } } }, "description": "Sequential pathUSD payments. HTTP 200 can include failed entries; inspect the summary and each result." }, "Registration": { "type": "object", "required": [ "ownerAddress", "name", "privateKeyHex", "accessKeyAddress", "spendingLimit", "expiry" ], "properties": { "ownerAddress": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Public agent label; do not put secrets here." }, "privateKeyHex": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "writeOnly": true, "description": "Delegated P256 agent key, never the root wallet key." }, "accessKeyAddress": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "spendingLimit": { "type": "string", "maxLength": 40, "pattern": "^\\d+(\\.\\d+)?$", "description": "Human-unit metadata. On-chain permissions remain authoritative." }, "expiry": { "type": "integer", "minimum": 1, "description": "Agent expiry metadata in Unix seconds. The service checks the actual on-chain key." } } } } } }