{
  "openapi": "3.1.0",
  "info": {
    "title": "H3RETIK Cloud x402 Disposable VPS Sessions and Agent Lock",
    "version": "1.0.0",
    "summary": "Disposable VPS sessions and low-cost agent coordination locks, payable with x402 on Base USDC.",
    "description": "H3RETIK Cloud gives agents and operators short-lived headless servers without dashboards, logins, cards, or month-long VPS rentals. A client calls a package endpoint, receives HTTP 402 payment requirements, pays Base USDC through x402, retries with the payment proof, receives a session token, runs bounded terminal commands, then the compute window expires. Fixed packages support micro probes, lightweight investigations, operational command batches, and deep research windows. The service is designed for private agent compute, disposable automation, OSINT workflows, on-chain probes, crawler runs, code audits, and command execution where agents need a machine rather than a user interface. H3RETIK Agent Lock adds a 0.0001 USDC distributed-lock primitive for autonomous agents that need exactly-one execution across X mentions, queue items, bounty creation, case creation, wallet actions, scrapes, and MCP workers.",
    "termsOfService": "https://h1dr4.dev/docs",
    "contact": {
      "name": "H1DR4",
      "url": "https://h1dr4.dev/h3retik",
      "email": "contact@h1dr4.dev"
    },
    "license": {
      "name": "Commercial API"
    },
    "x-keywords": [
      "x402",
      "agent compute",
      "disposable VPS",
      "ephemeral server",
      "headless terminal",
      "privacy compute",
      "Base USDC",
      "autonomous agent infrastructure",
      "command execution",
      "crawler runtime",
      "OSINT workflow",
      "on-chain probe",
      "audit runner",
      "agent lock",
      "distributed lock",
      "idempotency",
      "mutex",
      "exactly-once execution",
      "agent coordination",
      "workflow lock"
    ]
  },
  "servers": [
    {
      "url": "https://h1dr4.dev/h3retik/api",
      "description": "H1DR4 public H3RETIK Cloud API proxy"
    }
  ],
  "tags": [
    {
      "name": "x402",
      "description": "Paid disposable compute sessions using HTTP 402 and Base USDC."
    },
    {
      "name": "agent-compute",
      "description": "Short-lived headless servers for autonomous agents and operators."
    },
    {
      "name": "disposable-vps",
      "description": "Ephemeral VPS sessions that expire after the purchased time/action window."
    },
    {
      "name": "agent-lock",
      "description": "Low-cost x402 distributed locks for autonomous-agent idempotency and exactly-one execution."
    }
  ],
  "paths": {
    "/x402/sessions/micro": {
      "post": {
        "operationId": "createMicroX402Session",
        "summary": "Micro disposable VPS session",
        "description": "Create a 5 minute / 3 action disposable VPS session. Best for a quick endpoint check, one-off shell command, short web probe, or minimal agent command execution. Unpaid requests return HTTP 402 payment requirements; paid retries return an active session token.",
        "tags": [
          "x402",
          "agent-compute",
          "disposable-vps"
        ],
        "x-x402": {
          "network": "base",
          "chainId": 8453,
          "asset": "USDC",
          "price": "0.19 USDC",
          "amountAtomic": "190000",
          "sessionMinutes": 5,
          "actions": 3,
          "payTo": "0x99EEDcE3C87Adf3dE1c9B8B08F1810C168D6E039"
        },
        "requestBody": {
          "$ref": "#/components/requestBodies/FixedPackageRequest"
        },
        "responses": {
          "$ref": "#/components/responses/X402SessionResponses"
        }
      }
    },
    "/x402/sessions/probe": {
      "post": {
        "operationId": "createProbeX402Session",
        "summary": "Probe disposable VPS session",
        "description": "Create a 15 minute / 10 action disposable VPS session. Best for lightweight investigation, dependency installs, API checks, on-chain probes, crawler tests, and short automation runs. Unpaid requests return HTTP 402 payment requirements; paid retries return an active session token.",
        "tags": [
          "x402",
          "agent-compute",
          "disposable-vps"
        ],
        "x-x402": {
          "network": "base",
          "chainId": 8453,
          "asset": "USDC",
          "price": "0.60 USDC",
          "amountAtomic": "600000",
          "sessionMinutes": 15,
          "actions": 10,
          "payTo": "0x99EEDcE3C87Adf3dE1c9B8B08F1810C168D6E039"
        },
        "requestBody": {
          "$ref": "#/components/requestBodies/FixedPackageRequest"
        },
        "responses": {
          "$ref": "#/components/responses/X402SessionResponses"
        }
      }
    },
    "/x402/sessions/ops": {
      "post": {
        "operationId": "createOpsX402Session",
        "summary": "Ops disposable VPS session",
        "description": "Create a 60 minute / 50 action disposable VPS session. Best for operational command batches, research jobs, repeatable crawler runs, small audits, on-chain analysis, and longer autonomous agent tasks. Unpaid requests return HTTP 402 payment requirements; paid retries return an active session token.",
        "tags": [
          "x402",
          "agent-compute",
          "disposable-vps"
        ],
        "x-x402": {
          "network": "base",
          "chainId": 8453,
          "asset": "USDC",
          "price": "2.70 USDC",
          "amountAtomic": "2700000",
          "sessionMinutes": 60,
          "actions": 50,
          "payTo": "0x99EEDcE3C87Adf3dE1c9B8B08F1810C168D6E039"
        },
        "requestBody": {
          "$ref": "#/components/requestBodies/FixedPackageRequest"
        },
        "responses": {
          "$ref": "#/components/responses/X402SessionResponses"
        }
      }
    },
    "/x402/sessions/deep": {
      "post": {
        "operationId": "createDeepX402Session",
        "summary": "Deep disposable VPS session",
        "description": "Create a 180 minute / 150 action disposable VPS session. Best for deeper research, larger audits, data processing, longer crawl windows, batch OSINT workflows, and extended agent jobs. Unpaid requests return HTTP 402 payment requirements; paid retries return an active session token.",
        "tags": [
          "x402",
          "agent-compute",
          "disposable-vps"
        ],
        "x-x402": {
          "network": "base",
          "chainId": 8453,
          "asset": "USDC",
          "price": "8.10 USDC",
          "amountAtomic": "8100000",
          "sessionMinutes": 180,
          "actions": 150,
          "payTo": "0x99EEDcE3C87Adf3dE1c9B8B08F1810C168D6E039"
        },
        "requestBody": {
          "$ref": "#/components/requestBodies/FixedPackageRequest"
        },
        "responses": {
          "$ref": "#/components/responses/X402SessionResponses"
        }
      }
    },
    "/x402/sessions": {
      "post": {
        "operationId": "createCustomX402Session",
        "summary": "Custom disposable VPS session",
        "description": "Create a custom disposable VPS quote by specifying minutes, actions, and optional region. Use this when a fixed package does not match the intended agent job. Unpaid requests return HTTP 402 payment requirements; paid retries return an active session token.",
        "tags": [
          "x402",
          "agent-compute",
          "disposable-vps"
        ],
        "requestBody": {
          "$ref": "#/components/requestBodies/CustomSessionRequest"
        },
        "responses": {
          "$ref": "#/components/responses/X402SessionResponses"
        }
      }
    },
    "/x402/locks/acquire": {
      "post": {
        "operationId": "acquireAgentLockX402",
        "summary": "Acquire a low-cost Agent Lock",
        "description": "Acquire a TTL-bound distributed lock so parallel agents do not perform the same action twice. Use it for X mentions, queue items, bounties, case creation, wallet actions, scrape targets, and MCP workers. Unpaid requests return HTTP 402 payment requirements; paid retries return acquired=true with a release token or acquired=false if another actor already holds the key.",
        "tags": [
          "x402",
          "agent-lock"
        ],
        "x-x402": {
          "network": "base",
          "chainId": 8453,
          "asset": "USDC",
          "price": "0.0001 USDC",
          "amountAtomic": "100",
          "payTo": "0x99EEDcE3C87Adf3dE1c9B8B08F1810C168D6E039"
        },
        "requestBody": {
          "$ref": "#/components/requestBodies/AgentLockAcquireRequest"
        },
        "responses": {
          "$ref": "#/components/responses/X402AgentLockResponses"
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "x402": {
        "type": "apiKey",
        "in": "header",
        "name": "PAYMENT-SIGNATURE",
        "description": "HTTP 402 payment proof returned by an x402-compatible client after paying Base USDC."
      }
    },
    "schemas": {
      "Location": {
        "type": "string",
        "enum": [
          "auto",
          "us",
          "europe",
          "asia"
        ],
        "default": "auto",
        "description": "Preferred compute region. Auto lets H3RETIK choose the nearest or currently healthiest region."
      },
      "FixedPackageInput": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "location": {
            "$ref": "#/components/schemas/Location"
          }
        }
      },
      "CustomSessionInput": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "minutes": {
            "type": "integer",
            "minimum": 1,
            "maximum": 360,
            "description": "Requested compute minutes."
          },
          "actions": {
            "type": "integer",
            "minimum": 1,
            "maximum": 300,
            "description": "Maximum command/actions allowed in the session."
          },
          "location": {
            "$ref": "#/components/schemas/Location"
          }
        },
        "required": [
          "minutes",
          "actions"
        ]
      },
      "PaymentRequired": {
        "type": "object",
        "description": "Returned with HTTP 402 before payment. Contains x402 payment requirements and H3RETIK resource metadata.",
        "additionalProperties": true
      },
      "SessionResponse": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "session_id": {
            "type": "string"
          },
          "expires_at": {
            "type": "string",
            "format": "date-time"
          },
          "actions_remaining": {
            "type": "integer"
          },
          "location": {
            "$ref": "#/components/schemas/Location"
          }
        }
      },
      "AgentLockAcquireInput": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "key": {
            "type": "string",
            "minLength": 3,
            "maxLength": 256,
            "description": "Unique lock key. Example: h1dr4:x-mention:<tweet-id> or bounty:create:<slug>."
          },
          "owner": {
            "type": "string",
            "maxLength": 160,
            "description": "Optional agent, wallet, or worker identifier."
          },
          "ttl_seconds": {
            "type": "integer",
            "minimum": 5,
            "maximum": 86400,
            "default": 900,
            "description": "How long the lock stays active before automatic expiry."
          },
          "metadata": {
            "type": "object",
            "description": "Optional small coordination context."
          }
        },
        "required": [
          "key"
        ]
      },
      "AgentLockResponse": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "acquired": {
            "type": "boolean"
          },
          "lock": {
            "type": "object"
          },
          "release_token": {
            "type": "string",
            "description": "Returned only on successful acquire. Required for release/renew."
          }
        }
      }
    },
    "requestBodies": {
      "FixedPackageRequest": {
        "required": false,
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/FixedPackageInput"
            },
            "examples": {
              "auto": {
                "summary": "Auto region",
                "value": {
                  "location": "auto"
                }
              },
              "europe": {
                "summary": "Europe region",
                "value": {
                  "location": "europe"
                }
              }
            }
          }
        }
      },
      "CustomSessionRequest": {
        "required": true,
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/CustomSessionInput"
            },
            "examples": {
              "short-run": {
                "summary": "Short custom run",
                "value": {
                  "minutes": 20,
                  "actions": 12,
                  "location": "auto"
                }
              }
            }
          }
        }
      },
      "AgentLockAcquireRequest": {
        "required": true,
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/AgentLockAcquireInput"
            },
            "examples": {
              "x-mention": {
                "summary": "Claim one X mention",
                "value": {
                  "key": "h1dr4:x-mention:2066895922949464487",
                  "owner": "h1dr4-agent",
                  "ttl_seconds": 900
                }
              }
            }
          }
        }
      }
    },
    "responses": {
      "X402SessionResponses": {
        "200": {
          "description": "Payment settled and disposable VPS session created.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SessionResponse"
              }
            }
          }
        },
        "402": {
          "description": "Payment required. The response includes x402 requirements for Base USDC exact payment.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PaymentRequired"
              }
            }
          }
        },
        "400": {
          "description": "Invalid request body or unsupported package."
        },
        "503": {
          "description": "Session allocator or payment facilitator temporarily unavailable."
        }
      },
      "X402AgentLockResponses": {
        "200": {
          "description": "Payment settled and lock acquisition attempted. acquired=true includes release_token; acquired=false means the key is currently held by another actor.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AgentLockResponse"
              }
            }
          }
        },
        "402": {
          "description": "Payment required. The response includes x402 requirements for Base USDC exact payment.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PaymentRequired"
              }
            }
          }
        },
        "400": {
          "description": "Invalid lock key, TTL, or request body."
        }
      }
    }
  },
  "externalDocs": {
    "description": "H3RETIK Cloud docs and agent instructions",
    "url": "https://h1dr4.dev/h3retik"
  }
}