{"openapi":"3.1.0","info":{"title":"EnergyTRX API","version":"1.0.0","description":"Public REST API for the EnergyTRX TRON energy resale platform. Buy energy, manage Smart Energy subscriptions, and access account data programmatically.","contact":{"email":"info@energy-trx.com","url":"https://t.me/EnergyyTRX"}},"servers":[{"url":"https://energy-trx.com/api/v1","description":"Production"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"ek_live_…","description":"API key bearer token. Write requests (POST/PATCH/DELETE) must additionally carry X-Timestamp + X-Signature headers — HMAC-SHA256(secret, `${timestamp}.${body}`) in hex."}},"schemas":{"Error":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_REQUIRED","INVALID_API_KEY","INVALID_SIGNATURE","TIMESTAMP_INVALID","RATE_LIMIT_EXCEEDED","INVALID_REQUEST","INSUFFICIENT_BALANCE","RESOURCE_NOT_FOUND","RESOURCE_CONFLICT","INTERNAL_ERROR","SERVICE_UNAVAILABLE"]},"message":{"type":"string"},"details":{"type":"object","nullable":true}}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}},"Account":{"type":"object","required":["user_id","balance_trx","balance_usdt","deposit_address","deposit_network","created_at"],"properties":{"user_id":{"type":"string"},"email":{"type":"string","nullable":true},"balance_trx":{"type":"string","description":"TRX balance, decimal string (6 decimals)."},"balance_usdt":{"type":"string","description":"USDT balance, decimal string (2 decimals)."},"deposit_address":{"type":"string","description":"User's TRC-20 deposit address."},"deposit_network":{"type":"string","enum":["TRC-20"]},"created_at":{"type":"string","format":"date-time"}},"example":{"user_id":"clu0a1b2c3d4e5f6g7h8i9","email":"you@example.com","balance_trx":"1234.567890","balance_usdt":"456.78","deposit_address":"TXyZabc1234567890ABCDEF","deposit_network":"TRC-20","created_at":"2026-04-15T09:30:00.000Z"}},"Order":{"type":"object","required":["id","status","energy_amount","duration_hours","target_address","cost_trx","created_at","updated_at"],"properties":{"id":{"type":"string"},"status":{"type":"string","enum":["pending","active","completed","expired","failed","cancelled","refunded"]},"energy_amount":{"type":"string","description":"Energy in raw units, e.g. \"65000\"."},"duration_hours":{"type":"integer"},"target_address":{"type":"string","description":"TRON address that received delegation."},"cost_trx":{"type":"string"},"tx_id":{"type":"string","nullable":true,"description":"On-chain delegation tx hash (Tronscan)."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"expires_at":{"type":"string","format":"date-time","nullable":true}},"example":{"id":"clord1234567890","status":"completed","energy_amount":"65000","duration_hours":1,"target_address":"TXyZrecipient1234567890ABCDEF","cost_trx":"3.140000","tx_id":"2c1d3e9b...","created_at":"2026-05-27T10:15:22.000Z","updated_at":"2026-05-27T10:16:01.000Z","expires_at":"2026-05-27T11:15:22.000Z"}},"SmartEnergy":{"type":"object","required":["id","address","product_slug","product_name","status","balance_trx","total_delegations","created_at"],"properties":{"id":{"type":"string"},"address":{"type":"string","description":"Recipient TRON address."},"product_slug":{"type":"string","enum":["smart-delegation-65k","smart-delegation-131k"]},"product_name":{"type":"string"},"status":{"type":"string","enum":["active","paused","deleted"]},"balance_trx":{"type":"string"},"total_delegations":{"type":"integer"},"deleted_at":{"type":"string","format":"date-time","nullable":true},"refund_amount_trx":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"}},"example":{"id":"clsmart1234567890","address":"TXyZrecipient1234567890ABCDEF","product_slug":"smart-delegation-65k","product_name":"Smart Energy 65k","status":"active","balance_trx":"100.000000","total_delegations":42,"deleted_at":null,"refund_amount_trx":null,"created_at":"2026-05-20T08:00:00.000Z"}},"Transaction":{"type":"object","required":["id","type","amount","currency","status","created_at"],"properties":{"id":{"type":"string"},"type":{"type":"string","enum":["deposit","order","refund","manual_credit","manual_debit","smart_delegation_topup"]},"amount":{"type":"string"},"currency":{"type":"string","enum":["TRX","USDT"]},"status":{"type":"string","enum":["pending","confirmed","failed"]},"tx_hash":{"type":"string","nullable":true,"description":"On-chain hash for deposits (Tronscan)."},"created_at":{"type":"string","format":"date-time"}},"example":{"id":"cltx1234567890","type":"deposit","amount":"100.000000","currency":"TRX","status":"confirmed","tx_hash":"9f8e7d6c5b4a3210...","created_at":"2026-05-26T14:22:11.000Z"}},"ApiKey":{"type":"object","required":["id","name","prefix","scopes","createdAt"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"prefix":{"type":"string","description":"First 8 chars of the key (for identification)."},"scopes":{"type":"array","items":{"type":"string"}},"lastUsedAt":{"type":"string","format":"date-time","nullable":true},"lastUsedIp":{"type":"string","nullable":true},"expiresAt":{"type":"string","format":"date-time","nullable":true},"revokedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"example":{"id":"clkey1234567890","name":"Production server","prefix":"a1b2c3d4","scopes":["read","write"],"lastUsedAt":"2026-05-27T09:00:00.000Z","lastUsedIp":"203.0.113.42","expiresAt":null,"revokedAt":null,"createdAt":"2026-05-01T12:00:00.000Z"}},"Prices":{"type":"object","required":["currency","price_per_package_trx","package_units","quotes","updated_at"],"properties":{"currency":{"type":"string","enum":["TRX"]},"price_per_package_trx":{"type":"number"},"package_units":{"type":"integer"},"min_order_units":{"type":"integer"},"max_order_units":{"type":"integer"},"default_duration_hours":{"type":"integer"},"enabled_packages":{"type":"array","items":{"type":"integer"}},"quotes":{"type":"object","description":"TRX cost per package size."},"updated_at":{"type":"string","format":"date-time"}},"example":{"currency":"TRX","price_per_package_trx":3.14,"package_units":65000,"min_order_units":65000,"max_order_units":1000000,"default_duration_hours":1,"enabled_packages":[65000,131000,650000,1000000],"quotes":{"65000":3.14,"131000":6.28,"650000":31.4,"1000000":48.3},"updated_at":"2026-05-27T10:00:00.000Z"}},"Webhook":{"type":"object","required":["id","url","events","active","failure_count","created_at","updated_at"],"properties":{"id":{"type":"string"},"url":{"type":"string","description":"Destination URL (HTTPS in production)."},"events":{"type":"array","items":{"type":"string"},"description":"Subscribed event types."},"active":{"type":"boolean"},"failure_count":{"type":"integer","description":"Consecutive delivery exhaustions; auto-disables at 20."},"last_delivery_at":{"type":"string","format":"date-time","nullable":true},"last_failure_at":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"example":{"id":"clwh1234567890","url":"https://your-server.example.com/webhook","events":["order.created","deposit.received"],"active":true,"failure_count":0,"last_delivery_at":"2026-05-27T10:00:00.000Z","last_failure_at":null,"created_at":"2026-05-20T08:00:00.000Z","updated_at":"2026-05-20T08:00:00.000Z"}}}},"x-events":{"description":"Webhook event types customers can subscribe to via /dashboard/webhooks. Each delivery carries an HMAC signature in X-Energytrx-Signature.","types":["order.created","order.completed","order.failed","order.cancelled","order.expired","deposit.received","smart_energy.activated","smart_energy.paused","smart_energy.resumed","smart_energy.topped_up","smart_energy.depleted"]},"paths":{"/prices":{"get":{"summary":"Get current energy prices","description":"Public endpoint — no authentication required. Returns live per-package pricing in TRX.","security":[],"tags":["Public"],"responses":{"200":{"description":"Current pricing","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["currency","price_per_package_trx","package_units","quotes","updated_at"],"properties":{"currency":{"type":"string","enum":["TRX"]},"price_per_package_trx":{"type":"number"},"package_units":{"type":"integer"},"min_order_units":{"type":"integer"},"max_order_units":{"type":"integer"},"default_duration_hours":{"type":"integer"},"enabled_packages":{"type":"array","items":{"type":"integer"}},"quotes":{"type":"object","description":"TRX cost per package size."},"updated_at":{"type":"string","format":"date-time"}},"example":{"currency":"TRX","price_per_package_trx":3.14,"package_units":65000,"min_order_units":65000,"max_order_units":1000000,"default_duration_hours":1,"enabled_packages":[65000,131000,650000,1000000],"quotes":{"65000":3.14,"131000":6.28,"650000":31.4,"1000000":48.3},"updated_at":"2026-05-27T10:00:00.000Z"}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"data":{"currency":"TRX","price_per_package_trx":3.14,"package_units":65000,"min_order_units":65000,"max_order_units":1000000,"default_duration_hours":1,"enabled_packages":[65000,131000,650000,1000000],"quotes":{"65000":3.14,"131000":6.28,"650000":31.4,"1000000":48.3},"updated_at":"2026-05-27T10:00:00.000Z"},"meta":{"request_id":"ab12cd34ef56gh78"}}},"example":{"data":{"currency":"TRX","price_per_package_trx":3.14,"package_units":65000,"min_order_units":65000,"max_order_units":1000000,"default_duration_hours":1,"enabled_packages":[65000,131000,650000,1000000],"quotes":{"65000":3.14,"131000":6.28,"650000":31.4,"1000000":48.3},"updated_at":"2026-05-27T10:00:00.000Z"},"meta":{"request_id":"ab12cd34ef56gh78"}}}}}}}},"/account":{"get":{"summary":"Get the authenticated user's account","description":"Returns the caller's profile, balances, and deposit address.","tags":["Account"],"responses":{"200":{"description":"Account info","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["user_id","balance_trx","balance_usdt","deposit_address","deposit_network","created_at"],"properties":{"user_id":{"type":"string"},"email":{"type":"string","nullable":true},"balance_trx":{"type":"string","description":"TRX balance, decimal string (6 decimals)."},"balance_usdt":{"type":"string","description":"USDT balance, decimal string (2 decimals)."},"deposit_address":{"type":"string","description":"User's TRC-20 deposit address."},"deposit_network":{"type":"string","enum":["TRC-20"]},"created_at":{"type":"string","format":"date-time"}},"example":{"user_id":"clu0a1b2c3d4e5f6g7h8i9","email":"you@example.com","balance_trx":"1234.567890","balance_usdt":"456.78","deposit_address":"TXyZabc1234567890ABCDEF","deposit_network":"TRC-20","created_at":"2026-04-15T09:30:00.000Z"}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"data":{"user_id":"clu0a1b2c3d4e5f6g7h8i9","email":"you@example.com","balance_trx":"1234.567890","balance_usdt":"456.78","deposit_address":"TXyZabc1234567890ABCDEF","deposit_network":"TRC-20","created_at":"2026-04-15T09:30:00.000Z"},"meta":{"request_id":"ab12cd34ef56gh78"}}},"example":{"data":{"user_id":"clu0a1b2c3d4e5f6g7h8i9","email":"you@example.com","balance_trx":"1234.567890","balance_usdt":"456.78","deposit_address":"TXyZabc1234567890ABCDEF","deposit_network":"TRC-20","created_at":"2026-04-15T09:30:00.000Z"},"meta":{"request_id":"ab12cd34ef56gh78"}}}}},"401":{"description":"AUTH_REQUIRED / INVALID_API_KEY / INVALID_SIGNATURE / TIMESTAMP_INVALID","content":{"application/json":{"schema":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_REQUIRED","INVALID_API_KEY","INVALID_SIGNATURE","TIMESTAMP_INVALID","RATE_LIMIT_EXCEEDED","INVALID_REQUEST","INSUFFICIENT_BALANCE","RESOURCE_NOT_FOUND","RESOURCE_CONFLICT","INTERNAL_ERROR","SERVICE_UNAVAILABLE"]},"message":{"type":"string"},"details":{"type":"object","nullable":true}}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}}}},"429":{"description":"RATE_LIMIT_EXCEEDED — see X-RateLimit-Reset + Retry-After","content":{"application/json":{"schema":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_REQUIRED","INVALID_API_KEY","INVALID_SIGNATURE","TIMESTAMP_INVALID","RATE_LIMIT_EXCEEDED","INVALID_REQUEST","INSUFFICIENT_BALANCE","RESOURCE_NOT_FOUND","RESOURCE_CONFLICT","INTERNAL_ERROR","SERVICE_UNAVAILABLE"]},"message":{"type":"string"},"details":{"type":"object","nullable":true}}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}}}},"500":{"description":"INTERNAL_ERROR — server fault, include the request_id when reporting","content":{"application/json":{"schema":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_REQUIRED","INVALID_API_KEY","INVALID_SIGNATURE","TIMESTAMP_INVALID","RATE_LIMIT_EXCEEDED","INVALID_REQUEST","INSUFFICIENT_BALANCE","RESOURCE_NOT_FOUND","RESOURCE_CONFLICT","INTERNAL_ERROR","SERVICE_UNAVAILABLE"]},"message":{"type":"string"},"details":{"type":"object","nullable":true}}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}}}},"503":{"description":"SERVICE_UNAVAILABLE — temporary upstream failure","content":{"application/json":{"schema":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_REQUIRED","INVALID_API_KEY","INVALID_SIGNATURE","TIMESTAMP_INVALID","RATE_LIMIT_EXCEEDED","INVALID_REQUEST","INSUFFICIENT_BALANCE","RESOURCE_NOT_FOUND","RESOURCE_CONFLICT","INTERNAL_ERROR","SERVICE_UNAVAILABLE"]},"message":{"type":"string"},"details":{"type":"object","nullable":true}}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}}}}}}},"/orders":{"get":{"summary":"List your orders","description":"Paginated list, newest first. Optional `status` filter accepts any OrderStatus.","tags":["Orders"],"parameters":[{"name":"page","in":"query","required":false,"description":"Page number, 1-indexed.","schema":{"type":"integer","minimum":1,"default":1},"example":1},{"name":"per_page","in":"query","required":false,"description":"Page size (max 100).","schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"example":50},{"name":"status","in":"query","required":false,"description":"Filter to one status value (e.g. `pending`).","schema":{"type":"string"},"example":"completed"}],"responses":{"200":{"description":"Paginated orders","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","required":["id","status","energy_amount","duration_hours","target_address","cost_trx","created_at","updated_at"],"properties":{"id":{"type":"string"},"status":{"type":"string","enum":["pending","active","completed","expired","failed","cancelled","refunded"]},"energy_amount":{"type":"string","description":"Energy in raw units, e.g. \"65000\"."},"duration_hours":{"type":"integer"},"target_address":{"type":"string","description":"TRON address that received delegation."},"cost_trx":{"type":"string"},"tx_id":{"type":"string","nullable":true,"description":"On-chain delegation tx hash (Tronscan)."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"expires_at":{"type":"string","format":"date-time","nullable":true}},"example":{"id":"clord1234567890","status":"completed","energy_amount":"65000","duration_hours":1,"target_address":"TXyZrecipient1234567890ABCDEF","cost_trx":"3.140000","tx_id":"2c1d3e9b...","created_at":"2026-05-27T10:15:22.000Z","updated_at":"2026-05-27T10:16:01.000Z","expires_at":"2026-05-27T11:15:22.000Z"}}},"meta":{"type":"object","required":["request_id","page","per_page","total","has_more"],"properties":{"request_id":{"type":"string"},"page":{"type":"integer"},"per_page":{"type":"integer"},"total":{"type":"integer"},"has_more":{"type":"boolean"}}}},"example":{"data":[{"id":"clord1234567890","status":"completed","energy_amount":"65000","duration_hours":1,"target_address":"TXyZrecipient1234567890ABCDEF","cost_trx":"3.140000","tx_id":"2c1d3e9b...","created_at":"2026-05-27T10:15:22.000Z","updated_at":"2026-05-27T10:16:01.000Z","expires_at":"2026-05-27T11:15:22.000Z"}],"meta":{"request_id":"ab12cd34ef56gh78","page":1,"per_page":50,"total":1,"has_more":false}}},"example":{"data":[{"id":"clord1234567890","status":"completed","energy_amount":"65000","duration_hours":1,"target_address":"TXyZrecipient1234567890ABCDEF","cost_trx":"3.140000","tx_id":"2c1d3e9b...","created_at":"2026-05-27T10:15:22.000Z","updated_at":"2026-05-27T10:16:01.000Z","expires_at":"2026-05-27T11:15:22.000Z"}],"meta":{"request_id":"ab12cd34ef56gh78","page":1,"per_page":50,"total":1,"has_more":false}}}}},"401":{"description":"AUTH_REQUIRED / INVALID_API_KEY / INVALID_SIGNATURE / TIMESTAMP_INVALID","content":{"application/json":{"schema":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_REQUIRED","INVALID_API_KEY","INVALID_SIGNATURE","TIMESTAMP_INVALID","RATE_LIMIT_EXCEEDED","INVALID_REQUEST","INSUFFICIENT_BALANCE","RESOURCE_NOT_FOUND","RESOURCE_CONFLICT","INTERNAL_ERROR","SERVICE_UNAVAILABLE"]},"message":{"type":"string"},"details":{"type":"object","nullable":true}}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}}}},"429":{"description":"RATE_LIMIT_EXCEEDED — see X-RateLimit-Reset + Retry-After","content":{"application/json":{"schema":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_REQUIRED","INVALID_API_KEY","INVALID_SIGNATURE","TIMESTAMP_INVALID","RATE_LIMIT_EXCEEDED","INVALID_REQUEST","INSUFFICIENT_BALANCE","RESOURCE_NOT_FOUND","RESOURCE_CONFLICT","INTERNAL_ERROR","SERVICE_UNAVAILABLE"]},"message":{"type":"string"},"details":{"type":"object","nullable":true}}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}}}},"500":{"description":"INTERNAL_ERROR — server fault, include the request_id when reporting","content":{"application/json":{"schema":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_REQUIRED","INVALID_API_KEY","INVALID_SIGNATURE","TIMESTAMP_INVALID","RATE_LIMIT_EXCEEDED","INVALID_REQUEST","INSUFFICIENT_BALANCE","RESOURCE_NOT_FOUND","RESOURCE_CONFLICT","INTERNAL_ERROR","SERVICE_UNAVAILABLE"]},"message":{"type":"string"},"details":{"type":"object","nullable":true}}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}}}},"503":{"description":"SERVICE_UNAVAILABLE — temporary upstream failure","content":{"application/json":{"schema":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_REQUIRED","INVALID_API_KEY","INVALID_SIGNATURE","TIMESTAMP_INVALID","RATE_LIMIT_EXCEEDED","INVALID_REQUEST","INSUFFICIENT_BALANCE","RESOURCE_NOT_FOUND","RESOURCE_CONFLICT","INTERNAL_ERROR","SERVICE_UNAVAILABLE"]},"message":{"type":"string"},"details":{"type":"object","nullable":true}}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}}}}}},"post":{"summary":"Create an Energy Transfer order","description":"Delegates energy to `target_address` for 1 hour. Debits `cost_trx` from your TRX balance.","tags":["Orders"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["target_address","energy_amount"],"properties":{"target_address":{"type":"string","description":"TRON address to receive the delegation."},"energy_amount":{"type":"integer","description":"Energy units (e.g. 65000)."}}},"example":{"target_address":"TXyZrecipient1234567890ABCDEF","energy_amount":65000}}}},"responses":{"201":{"description":"Order created","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["id","status","energy_amount","duration_hours","target_address","cost_trx","created_at","updated_at"],"properties":{"id":{"type":"string"},"status":{"type":"string","enum":["pending","active","completed","expired","failed","cancelled","refunded"]},"energy_amount":{"type":"string","description":"Energy in raw units, e.g. \"65000\"."},"duration_hours":{"type":"integer"},"target_address":{"type":"string","description":"TRON address that received delegation."},"cost_trx":{"type":"string"},"tx_id":{"type":"string","nullable":true,"description":"On-chain delegation tx hash (Tronscan)."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"expires_at":{"type":"string","format":"date-time","nullable":true}},"example":{"id":"clord1234567890","status":"completed","energy_amount":"65000","duration_hours":1,"target_address":"TXyZrecipient1234567890ABCDEF","cost_trx":"3.140000","tx_id":"2c1d3e9b...","created_at":"2026-05-27T10:15:22.000Z","updated_at":"2026-05-27T10:16:01.000Z","expires_at":"2026-05-27T11:15:22.000Z"}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"data":{"id":"clord1234567890","status":"completed","energy_amount":"65000","duration_hours":1,"target_address":"TXyZrecipient1234567890ABCDEF","cost_trx":"3.140000","tx_id":"2c1d3e9b...","created_at":"2026-05-27T10:15:22.000Z","updated_at":"2026-05-27T10:16:01.000Z","expires_at":"2026-05-27T11:15:22.000Z"},"meta":{"request_id":"ab12cd34ef56gh78"}}},"example":{"data":{"id":"clord1234567890","status":"completed","energy_amount":"65000","duration_hours":1,"target_address":"TXyZrecipient1234567890ABCDEF","cost_trx":"3.140000","tx_id":"2c1d3e9b...","created_at":"2026-05-27T10:15:22.000Z","updated_at":"2026-05-27T10:16:01.000Z","expires_at":"2026-05-27T11:15:22.000Z"},"meta":{"request_id":"ab12cd34ef56gh78"}}}}},"400":{"description":"INVALID_REQUEST","content":{"application/json":{"schema":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_REQUIRED","INVALID_API_KEY","INVALID_SIGNATURE","TIMESTAMP_INVALID","RATE_LIMIT_EXCEEDED","INVALID_REQUEST","INSUFFICIENT_BALANCE","RESOURCE_NOT_FOUND","RESOURCE_CONFLICT","INTERNAL_ERROR","SERVICE_UNAVAILABLE"]},"message":{"type":"string"},"details":{"type":"object","nullable":true}}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}}}},"401":{"description":"AUTH_REQUIRED / INVALID_API_KEY / INVALID_SIGNATURE / TIMESTAMP_INVALID","content":{"application/json":{"schema":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_REQUIRED","INVALID_API_KEY","INVALID_SIGNATURE","TIMESTAMP_INVALID","RATE_LIMIT_EXCEEDED","INVALID_REQUEST","INSUFFICIENT_BALANCE","RESOURCE_NOT_FOUND","RESOURCE_CONFLICT","INTERNAL_ERROR","SERVICE_UNAVAILABLE"]},"message":{"type":"string"},"details":{"type":"object","nullable":true}}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}}}},"402":{"description":"INSUFFICIENT_BALANCE","content":{"application/json":{"schema":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_REQUIRED","INVALID_API_KEY","INVALID_SIGNATURE","TIMESTAMP_INVALID","RATE_LIMIT_EXCEEDED","INVALID_REQUEST","INSUFFICIENT_BALANCE","RESOURCE_NOT_FOUND","RESOURCE_CONFLICT","INTERNAL_ERROR","SERVICE_UNAVAILABLE"]},"message":{"type":"string"},"details":{"type":"object","nullable":true}}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}}}},"429":{"description":"RATE_LIMIT_EXCEEDED — see X-RateLimit-Reset + Retry-After","content":{"application/json":{"schema":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_REQUIRED","INVALID_API_KEY","INVALID_SIGNATURE","TIMESTAMP_INVALID","RATE_LIMIT_EXCEEDED","INVALID_REQUEST","INSUFFICIENT_BALANCE","RESOURCE_NOT_FOUND","RESOURCE_CONFLICT","INTERNAL_ERROR","SERVICE_UNAVAILABLE"]},"message":{"type":"string"},"details":{"type":"object","nullable":true}}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}}}},"500":{"description":"INTERNAL_ERROR — server fault, include the request_id when reporting","content":{"application/json":{"schema":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_REQUIRED","INVALID_API_KEY","INVALID_SIGNATURE","TIMESTAMP_INVALID","RATE_LIMIT_EXCEEDED","INVALID_REQUEST","INSUFFICIENT_BALANCE","RESOURCE_NOT_FOUND","RESOURCE_CONFLICT","INTERNAL_ERROR","SERVICE_UNAVAILABLE"]},"message":{"type":"string"},"details":{"type":"object","nullable":true}}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}}}},"503":{"description":"SERVICE_UNAVAILABLE — temporary upstream failure","content":{"application/json":{"schema":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_REQUIRED","INVALID_API_KEY","INVALID_SIGNATURE","TIMESTAMP_INVALID","RATE_LIMIT_EXCEEDED","INVALID_REQUEST","INSUFFICIENT_BALANCE","RESOURCE_NOT_FOUND","RESOURCE_CONFLICT","INTERNAL_ERROR","SERVICE_UNAVAILABLE"]},"message":{"type":"string"},"details":{"type":"object","nullable":true}}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}}}}}}},"/orders/{id}":{"get":{"summary":"Get an order","description":"Single-order lookup scoped to the caller.","tags":["Orders"],"parameters":[{"name":"id","in":"path","required":true,"description":"Order id.","schema":{"type":"string"},"example":"clord1234567890"}],"responses":{"200":{"description":"Order","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["id","status","energy_amount","duration_hours","target_address","cost_trx","created_at","updated_at"],"properties":{"id":{"type":"string"},"status":{"type":"string","enum":["pending","active","completed","expired","failed","cancelled","refunded"]},"energy_amount":{"type":"string","description":"Energy in raw units, e.g. \"65000\"."},"duration_hours":{"type":"integer"},"target_address":{"type":"string","description":"TRON address that received delegation."},"cost_trx":{"type":"string"},"tx_id":{"type":"string","nullable":true,"description":"On-chain delegation tx hash (Tronscan)."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"expires_at":{"type":"string","format":"date-time","nullable":true}},"example":{"id":"clord1234567890","status":"completed","energy_amount":"65000","duration_hours":1,"target_address":"TXyZrecipient1234567890ABCDEF","cost_trx":"3.140000","tx_id":"2c1d3e9b...","created_at":"2026-05-27T10:15:22.000Z","updated_at":"2026-05-27T10:16:01.000Z","expires_at":"2026-05-27T11:15:22.000Z"}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"data":{"id":"clord1234567890","status":"completed","energy_amount":"65000","duration_hours":1,"target_address":"TXyZrecipient1234567890ABCDEF","cost_trx":"3.140000","tx_id":"2c1d3e9b...","created_at":"2026-05-27T10:15:22.000Z","updated_at":"2026-05-27T10:16:01.000Z","expires_at":"2026-05-27T11:15:22.000Z"},"meta":{"request_id":"ab12cd34ef56gh78"}}},"example":{"data":{"id":"clord1234567890","status":"completed","energy_amount":"65000","duration_hours":1,"target_address":"TXyZrecipient1234567890ABCDEF","cost_trx":"3.140000","tx_id":"2c1d3e9b...","created_at":"2026-05-27T10:15:22.000Z","updated_at":"2026-05-27T10:16:01.000Z","expires_at":"2026-05-27T11:15:22.000Z"},"meta":{"request_id":"ab12cd34ef56gh78"}}}}},"401":{"description":"AUTH_REQUIRED / INVALID_API_KEY / INVALID_SIGNATURE / TIMESTAMP_INVALID","content":{"application/json":{"schema":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_REQUIRED","INVALID_API_KEY","INVALID_SIGNATURE","TIMESTAMP_INVALID","RATE_LIMIT_EXCEEDED","INVALID_REQUEST","INSUFFICIENT_BALANCE","RESOURCE_NOT_FOUND","RESOURCE_CONFLICT","INTERNAL_ERROR","SERVICE_UNAVAILABLE"]},"message":{"type":"string"},"details":{"type":"object","nullable":true}}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}}}},"404":{"description":"RESOURCE_NOT_FOUND","content":{"application/json":{"schema":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_REQUIRED","INVALID_API_KEY","INVALID_SIGNATURE","TIMESTAMP_INVALID","RATE_LIMIT_EXCEEDED","INVALID_REQUEST","INSUFFICIENT_BALANCE","RESOURCE_NOT_FOUND","RESOURCE_CONFLICT","INTERNAL_ERROR","SERVICE_UNAVAILABLE"]},"message":{"type":"string"},"details":{"type":"object","nullable":true}}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}}}},"429":{"description":"RATE_LIMIT_EXCEEDED — see X-RateLimit-Reset + Retry-After","content":{"application/json":{"schema":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_REQUIRED","INVALID_API_KEY","INVALID_SIGNATURE","TIMESTAMP_INVALID","RATE_LIMIT_EXCEEDED","INVALID_REQUEST","INSUFFICIENT_BALANCE","RESOURCE_NOT_FOUND","RESOURCE_CONFLICT","INTERNAL_ERROR","SERVICE_UNAVAILABLE"]},"message":{"type":"string"},"details":{"type":"object","nullable":true}}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}}}},"500":{"description":"INTERNAL_ERROR — server fault, include the request_id when reporting","content":{"application/json":{"schema":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_REQUIRED","INVALID_API_KEY","INVALID_SIGNATURE","TIMESTAMP_INVALID","RATE_LIMIT_EXCEEDED","INVALID_REQUEST","INSUFFICIENT_BALANCE","RESOURCE_NOT_FOUND","RESOURCE_CONFLICT","INTERNAL_ERROR","SERVICE_UNAVAILABLE"]},"message":{"type":"string"},"details":{"type":"object","nullable":true}}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}}}},"503":{"description":"SERVICE_UNAVAILABLE — temporary upstream failure","content":{"application/json":{"schema":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_REQUIRED","INVALID_API_KEY","INVALID_SIGNATURE","TIMESTAMP_INVALID","RATE_LIMIT_EXCEEDED","INVALID_REQUEST","INSUFFICIENT_BALANCE","RESOURCE_NOT_FOUND","RESOURCE_CONFLICT","INTERNAL_ERROR","SERVICE_UNAVAILABLE"]},"message":{"type":"string"},"details":{"type":"object","nullable":true}}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}}}}}}},"/orders/{id}/cancel":{"post":{"summary":"Cancel a pending order","description":"Refunds the order cost to your TRX balance. Only orders in `pending` status can be cancelled.","tags":["Orders"],"parameters":[{"name":"id","in":"path","required":true,"description":"Order id.","schema":{"type":"string"},"example":"clord1234567890"}],"responses":{"200":{"description":"Order cancelled","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["id","status","energy_amount","duration_hours","target_address","cost_trx","created_at","updated_at"],"properties":{"id":{"type":"string"},"status":{"type":"string","enum":["pending","active","completed","expired","failed","cancelled","refunded"]},"energy_amount":{"type":"string","description":"Energy in raw units, e.g. \"65000\"."},"duration_hours":{"type":"integer"},"target_address":{"type":"string","description":"TRON address that received delegation."},"cost_trx":{"type":"string"},"tx_id":{"type":"string","nullable":true,"description":"On-chain delegation tx hash (Tronscan)."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"expires_at":{"type":"string","format":"date-time","nullable":true}},"example":{"id":"clord1234567890","status":"completed","energy_amount":"65000","duration_hours":1,"target_address":"TXyZrecipient1234567890ABCDEF","cost_trx":"3.140000","tx_id":"2c1d3e9b...","created_at":"2026-05-27T10:15:22.000Z","updated_at":"2026-05-27T10:16:01.000Z","expires_at":"2026-05-27T11:15:22.000Z"}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"data":{"id":"clord1234567890","status":"completed","energy_amount":"65000","duration_hours":1,"target_address":"TXyZrecipient1234567890ABCDEF","cost_trx":"3.140000","tx_id":"2c1d3e9b...","created_at":"2026-05-27T10:15:22.000Z","updated_at":"2026-05-27T10:16:01.000Z","expires_at":"2026-05-27T11:15:22.000Z"},"meta":{"request_id":"ab12cd34ef56gh78"}}},"example":{"data":{"id":"clord1234567890","status":"completed","energy_amount":"65000","duration_hours":1,"target_address":"TXyZrecipient1234567890ABCDEF","cost_trx":"3.140000","tx_id":"2c1d3e9b...","created_at":"2026-05-27T10:15:22.000Z","updated_at":"2026-05-27T10:16:01.000Z","expires_at":"2026-05-27T11:15:22.000Z"},"meta":{"request_id":"ab12cd34ef56gh78"}}}}},"401":{"description":"AUTH_REQUIRED / INVALID_API_KEY / INVALID_SIGNATURE / TIMESTAMP_INVALID","content":{"application/json":{"schema":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_REQUIRED","INVALID_API_KEY","INVALID_SIGNATURE","TIMESTAMP_INVALID","RATE_LIMIT_EXCEEDED","INVALID_REQUEST","INSUFFICIENT_BALANCE","RESOURCE_NOT_FOUND","RESOURCE_CONFLICT","INTERNAL_ERROR","SERVICE_UNAVAILABLE"]},"message":{"type":"string"},"details":{"type":"object","nullable":true}}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}}}},"404":{"description":"RESOURCE_NOT_FOUND","content":{"application/json":{"schema":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_REQUIRED","INVALID_API_KEY","INVALID_SIGNATURE","TIMESTAMP_INVALID","RATE_LIMIT_EXCEEDED","INVALID_REQUEST","INSUFFICIENT_BALANCE","RESOURCE_NOT_FOUND","RESOURCE_CONFLICT","INTERNAL_ERROR","SERVICE_UNAVAILABLE"]},"message":{"type":"string"},"details":{"type":"object","nullable":true}}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}}}},"409":{"description":"RESOURCE_CONFLICT — order is not pending","content":{"application/json":{"schema":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_REQUIRED","INVALID_API_KEY","INVALID_SIGNATURE","TIMESTAMP_INVALID","RATE_LIMIT_EXCEEDED","INVALID_REQUEST","INSUFFICIENT_BALANCE","RESOURCE_NOT_FOUND","RESOURCE_CONFLICT","INTERNAL_ERROR","SERVICE_UNAVAILABLE"]},"message":{"type":"string"},"details":{"type":"object","nullable":true}}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}}}},"429":{"description":"RATE_LIMIT_EXCEEDED — see X-RateLimit-Reset + Retry-After","content":{"application/json":{"schema":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_REQUIRED","INVALID_API_KEY","INVALID_SIGNATURE","TIMESTAMP_INVALID","RATE_LIMIT_EXCEEDED","INVALID_REQUEST","INSUFFICIENT_BALANCE","RESOURCE_NOT_FOUND","RESOURCE_CONFLICT","INTERNAL_ERROR","SERVICE_UNAVAILABLE"]},"message":{"type":"string"},"details":{"type":"object","nullable":true}}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}}}},"500":{"description":"INTERNAL_ERROR — server fault, include the request_id when reporting","content":{"application/json":{"schema":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_REQUIRED","INVALID_API_KEY","INVALID_SIGNATURE","TIMESTAMP_INVALID","RATE_LIMIT_EXCEEDED","INVALID_REQUEST","INSUFFICIENT_BALANCE","RESOURCE_NOT_FOUND","RESOURCE_CONFLICT","INTERNAL_ERROR","SERVICE_UNAVAILABLE"]},"message":{"type":"string"},"details":{"type":"object","nullable":true}}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}}}},"503":{"description":"SERVICE_UNAVAILABLE — temporary upstream failure","content":{"application/json":{"schema":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_REQUIRED","INVALID_API_KEY","INVALID_SIGNATURE","TIMESTAMP_INVALID","RATE_LIMIT_EXCEEDED","INVALID_REQUEST","INSUFFICIENT_BALANCE","RESOURCE_NOT_FOUND","RESOURCE_CONFLICT","INTERNAL_ERROR","SERVICE_UNAVAILABLE"]},"message":{"type":"string"},"details":{"type":"object","nullable":true}}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}}}}}}},"/smart-energy":{"get":{"summary":"List Smart Energy subscriptions","description":"Your active subscriptions. Pass `include_deleted=1` to include soft-deleted rows.","tags":["Smart Energy"],"parameters":[{"name":"include_deleted","in":"query","required":false,"description":"Include soft-deleted subs.","schema":{"type":"string","enum":["0","1"]},"example":"0"}],"responses":{"200":{"description":"Array of subscriptions","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","required":["id","address","product_slug","product_name","status","balance_trx","total_delegations","created_at"],"properties":{"id":{"type":"string"},"address":{"type":"string","description":"Recipient TRON address."},"product_slug":{"type":"string","enum":["smart-delegation-65k","smart-delegation-131k"]},"product_name":{"type":"string"},"status":{"type":"string","enum":["active","paused","deleted"]},"balance_trx":{"type":"string"},"total_delegations":{"type":"integer"},"deleted_at":{"type":"string","format":"date-time","nullable":true},"refund_amount_trx":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"}},"example":{"id":"clsmart1234567890","address":"TXyZrecipient1234567890ABCDEF","product_slug":"smart-delegation-65k","product_name":"Smart Energy 65k","status":"active","balance_trx":"100.000000","total_delegations":42,"deleted_at":null,"refund_amount_trx":null,"created_at":"2026-05-20T08:00:00.000Z"}}},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"count":{"type":"integer"}}}}},"example":{"data":[{"id":"clsmart1234567890","address":"TXyZrecipient1234567890ABCDEF","product_slug":"smart-delegation-65k","product_name":"Smart Energy 65k","status":"active","balance_trx":"100.000000","total_delegations":42,"deleted_at":null,"refund_amount_trx":null,"created_at":"2026-05-20T08:00:00.000Z"}],"meta":{"request_id":"ab12cd34ef56gh78","count":1}}}}},"401":{"description":"AUTH_REQUIRED / INVALID_API_KEY / INVALID_SIGNATURE / TIMESTAMP_INVALID","content":{"application/json":{"schema":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_REQUIRED","INVALID_API_KEY","INVALID_SIGNATURE","TIMESTAMP_INVALID","RATE_LIMIT_EXCEEDED","INVALID_REQUEST","INSUFFICIENT_BALANCE","RESOURCE_NOT_FOUND","RESOURCE_CONFLICT","INTERNAL_ERROR","SERVICE_UNAVAILABLE"]},"message":{"type":"string"},"details":{"type":"object","nullable":true}}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}}}},"429":{"description":"RATE_LIMIT_EXCEEDED — see X-RateLimit-Reset + Retry-After","content":{"application/json":{"schema":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_REQUIRED","INVALID_API_KEY","INVALID_SIGNATURE","TIMESTAMP_INVALID","RATE_LIMIT_EXCEEDED","INVALID_REQUEST","INSUFFICIENT_BALANCE","RESOURCE_NOT_FOUND","RESOURCE_CONFLICT","INTERNAL_ERROR","SERVICE_UNAVAILABLE"]},"message":{"type":"string"},"details":{"type":"object","nullable":true}}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}}}},"500":{"description":"INTERNAL_ERROR — server fault, include the request_id when reporting","content":{"application/json":{"schema":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_REQUIRED","INVALID_API_KEY","INVALID_SIGNATURE","TIMESTAMP_INVALID","RATE_LIMIT_EXCEEDED","INVALID_REQUEST","INSUFFICIENT_BALANCE","RESOURCE_NOT_FOUND","RESOURCE_CONFLICT","INTERNAL_ERROR","SERVICE_UNAVAILABLE"]},"message":{"type":"string"},"details":{"type":"object","nullable":true}}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}}}},"503":{"description":"SERVICE_UNAVAILABLE — temporary upstream failure","content":{"application/json":{"schema":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_REQUIRED","INVALID_API_KEY","INVALID_SIGNATURE","TIMESTAMP_INVALID","RATE_LIMIT_EXCEEDED","INVALID_REQUEST","INSUFFICIENT_BALANCE","RESOURCE_NOT_FOUND","RESOURCE_CONFLICT","INTERNAL_ERROR","SERVICE_UNAVAILABLE"]},"message":{"type":"string"},"details":{"type":"object","nullable":true}}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}}}}}},"post":{"summary":"Create a Smart Energy subscription","description":"Locks `top_up_trx` from your balance and auto-delivers energy to `address` whenever it needs it.","tags":["Smart Energy"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["address","top_up_trx"],"properties":{"address":{"type":"string","description":"TRON address that will receive automatic energy."},"top_up_trx":{"type":"number","description":"TRX to lock into the subscription balance."},"product_slug":{"type":"string","enum":["smart-delegation-65k","smart-delegation-131k"],"description":"Product variant. Defaults to smart-delegation-65k."}}},"example":{"address":"TXyZrecipient1234567890ABCDEF","top_up_trx":100,"product_slug":"smart-delegation-65k"}}}},"responses":{"201":{"description":"Subscription created","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["id","address","product_slug","product_name","status","balance_trx","total_delegations","created_at"],"properties":{"id":{"type":"string"},"address":{"type":"string","description":"Recipient TRON address."},"product_slug":{"type":"string","enum":["smart-delegation-65k","smart-delegation-131k"]},"product_name":{"type":"string"},"status":{"type":"string","enum":["active","paused","deleted"]},"balance_trx":{"type":"string"},"total_delegations":{"type":"integer"},"deleted_at":{"type":"string","format":"date-time","nullable":true},"refund_amount_trx":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"}},"example":{"id":"clsmart1234567890","address":"TXyZrecipient1234567890ABCDEF","product_slug":"smart-delegation-65k","product_name":"Smart Energy 65k","status":"active","balance_trx":"100.000000","total_delegations":42,"deleted_at":null,"refund_amount_trx":null,"created_at":"2026-05-20T08:00:00.000Z"}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"data":{"id":"clsmart1234567890","address":"TXyZrecipient1234567890ABCDEF","product_slug":"smart-delegation-65k","product_name":"Smart Energy 65k","status":"active","balance_trx":"100.000000","total_delegations":42,"deleted_at":null,"refund_amount_trx":null,"created_at":"2026-05-20T08:00:00.000Z"},"meta":{"request_id":"ab12cd34ef56gh78"}}},"example":{"data":{"id":"clsmart1234567890","address":"TXyZrecipient1234567890ABCDEF","product_slug":"smart-delegation-65k","product_name":"Smart Energy 65k","status":"active","balance_trx":"100.000000","total_delegations":42,"deleted_at":null,"refund_amount_trx":null,"created_at":"2026-05-20T08:00:00.000Z"},"meta":{"request_id":"ab12cd34ef56gh78"}}}}},"400":{"description":"INVALID_REQUEST","content":{"application/json":{"schema":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_REQUIRED","INVALID_API_KEY","INVALID_SIGNATURE","TIMESTAMP_INVALID","RATE_LIMIT_EXCEEDED","INVALID_REQUEST","INSUFFICIENT_BALANCE","RESOURCE_NOT_FOUND","RESOURCE_CONFLICT","INTERNAL_ERROR","SERVICE_UNAVAILABLE"]},"message":{"type":"string"},"details":{"type":"object","nullable":true}}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}}}},"401":{"description":"AUTH_REQUIRED / INVALID_API_KEY / INVALID_SIGNATURE / TIMESTAMP_INVALID","content":{"application/json":{"schema":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_REQUIRED","INVALID_API_KEY","INVALID_SIGNATURE","TIMESTAMP_INVALID","RATE_LIMIT_EXCEEDED","INVALID_REQUEST","INSUFFICIENT_BALANCE","RESOURCE_NOT_FOUND","RESOURCE_CONFLICT","INTERNAL_ERROR","SERVICE_UNAVAILABLE"]},"message":{"type":"string"},"details":{"type":"object","nullable":true}}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}}}},"402":{"description":"INSUFFICIENT_BALANCE","content":{"application/json":{"schema":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_REQUIRED","INVALID_API_KEY","INVALID_SIGNATURE","TIMESTAMP_INVALID","RATE_LIMIT_EXCEEDED","INVALID_REQUEST","INSUFFICIENT_BALANCE","RESOURCE_NOT_FOUND","RESOURCE_CONFLICT","INTERNAL_ERROR","SERVICE_UNAVAILABLE"]},"message":{"type":"string"},"details":{"type":"object","nullable":true}}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}}}},"409":{"description":"RESOURCE_CONFLICT — duplicate active subscription for this address","content":{"application/json":{"schema":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_REQUIRED","INVALID_API_KEY","INVALID_SIGNATURE","TIMESTAMP_INVALID","RATE_LIMIT_EXCEEDED","INVALID_REQUEST","INSUFFICIENT_BALANCE","RESOURCE_NOT_FOUND","RESOURCE_CONFLICT","INTERNAL_ERROR","SERVICE_UNAVAILABLE"]},"message":{"type":"string"},"details":{"type":"object","nullable":true}}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}}}},"429":{"description":"RATE_LIMIT_EXCEEDED — see X-RateLimit-Reset + Retry-After","content":{"application/json":{"schema":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_REQUIRED","INVALID_API_KEY","INVALID_SIGNATURE","TIMESTAMP_INVALID","RATE_LIMIT_EXCEEDED","INVALID_REQUEST","INSUFFICIENT_BALANCE","RESOURCE_NOT_FOUND","RESOURCE_CONFLICT","INTERNAL_ERROR","SERVICE_UNAVAILABLE"]},"message":{"type":"string"},"details":{"type":"object","nullable":true}}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}}}},"500":{"description":"INTERNAL_ERROR — server fault, include the request_id when reporting","content":{"application/json":{"schema":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_REQUIRED","INVALID_API_KEY","INVALID_SIGNATURE","TIMESTAMP_INVALID","RATE_LIMIT_EXCEEDED","INVALID_REQUEST","INSUFFICIENT_BALANCE","RESOURCE_NOT_FOUND","RESOURCE_CONFLICT","INTERNAL_ERROR","SERVICE_UNAVAILABLE"]},"message":{"type":"string"},"details":{"type":"object","nullable":true}}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}}}},"503":{"description":"SERVICE_UNAVAILABLE — temporary upstream failure","content":{"application/json":{"schema":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_REQUIRED","INVALID_API_KEY","INVALID_SIGNATURE","TIMESTAMP_INVALID","RATE_LIMIT_EXCEEDED","INVALID_REQUEST","INSUFFICIENT_BALANCE","RESOURCE_NOT_FOUND","RESOURCE_CONFLICT","INTERNAL_ERROR","SERVICE_UNAVAILABLE"]},"message":{"type":"string"},"details":{"type":"object","nullable":true}}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}}}}}}},"/smart-energy/{id}":{"get":{"summary":"Get a subscription","description":"Single-subscription lookup scoped to the caller.","tags":["Smart Energy"],"parameters":[{"name":"id","in":"path","required":true,"description":"Subscription id.","schema":{"type":"string"},"example":"clsmart1234567890"}],"responses":{"200":{"description":"Subscription","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["id","address","product_slug","product_name","status","balance_trx","total_delegations","created_at"],"properties":{"id":{"type":"string"},"address":{"type":"string","description":"Recipient TRON address."},"product_slug":{"type":"string","enum":["smart-delegation-65k","smart-delegation-131k"]},"product_name":{"type":"string"},"status":{"type":"string","enum":["active","paused","deleted"]},"balance_trx":{"type":"string"},"total_delegations":{"type":"integer"},"deleted_at":{"type":"string","format":"date-time","nullable":true},"refund_amount_trx":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"}},"example":{"id":"clsmart1234567890","address":"TXyZrecipient1234567890ABCDEF","product_slug":"smart-delegation-65k","product_name":"Smart Energy 65k","status":"active","balance_trx":"100.000000","total_delegations":42,"deleted_at":null,"refund_amount_trx":null,"created_at":"2026-05-20T08:00:00.000Z"}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"data":{"id":"clsmart1234567890","address":"TXyZrecipient1234567890ABCDEF","product_slug":"smart-delegation-65k","product_name":"Smart Energy 65k","status":"active","balance_trx":"100.000000","total_delegations":42,"deleted_at":null,"refund_amount_trx":null,"created_at":"2026-05-20T08:00:00.000Z"},"meta":{"request_id":"ab12cd34ef56gh78"}}},"example":{"data":{"id":"clsmart1234567890","address":"TXyZrecipient1234567890ABCDEF","product_slug":"smart-delegation-65k","product_name":"Smart Energy 65k","status":"active","balance_trx":"100.000000","total_delegations":42,"deleted_at":null,"refund_amount_trx":null,"created_at":"2026-05-20T08:00:00.000Z"},"meta":{"request_id":"ab12cd34ef56gh78"}}}}},"401":{"description":"AUTH_REQUIRED / INVALID_API_KEY / INVALID_SIGNATURE / TIMESTAMP_INVALID","content":{"application/json":{"schema":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_REQUIRED","INVALID_API_KEY","INVALID_SIGNATURE","TIMESTAMP_INVALID","RATE_LIMIT_EXCEEDED","INVALID_REQUEST","INSUFFICIENT_BALANCE","RESOURCE_NOT_FOUND","RESOURCE_CONFLICT","INTERNAL_ERROR","SERVICE_UNAVAILABLE"]},"message":{"type":"string"},"details":{"type":"object","nullable":true}}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}}}},"404":{"description":"RESOURCE_NOT_FOUND","content":{"application/json":{"schema":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_REQUIRED","INVALID_API_KEY","INVALID_SIGNATURE","TIMESTAMP_INVALID","RATE_LIMIT_EXCEEDED","INVALID_REQUEST","INSUFFICIENT_BALANCE","RESOURCE_NOT_FOUND","RESOURCE_CONFLICT","INTERNAL_ERROR","SERVICE_UNAVAILABLE"]},"message":{"type":"string"},"details":{"type":"object","nullable":true}}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}}}},"429":{"description":"RATE_LIMIT_EXCEEDED — see X-RateLimit-Reset + Retry-After","content":{"application/json":{"schema":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_REQUIRED","INVALID_API_KEY","INVALID_SIGNATURE","TIMESTAMP_INVALID","RATE_LIMIT_EXCEEDED","INVALID_REQUEST","INSUFFICIENT_BALANCE","RESOURCE_NOT_FOUND","RESOURCE_CONFLICT","INTERNAL_ERROR","SERVICE_UNAVAILABLE"]},"message":{"type":"string"},"details":{"type":"object","nullable":true}}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}}}},"500":{"description":"INTERNAL_ERROR — server fault, include the request_id when reporting","content":{"application/json":{"schema":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_REQUIRED","INVALID_API_KEY","INVALID_SIGNATURE","TIMESTAMP_INVALID","RATE_LIMIT_EXCEEDED","INVALID_REQUEST","INSUFFICIENT_BALANCE","RESOURCE_NOT_FOUND","RESOURCE_CONFLICT","INTERNAL_ERROR","SERVICE_UNAVAILABLE"]},"message":{"type":"string"},"details":{"type":"object","nullable":true}}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}}}},"503":{"description":"SERVICE_UNAVAILABLE — temporary upstream failure","content":{"application/json":{"schema":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_REQUIRED","INVALID_API_KEY","INVALID_SIGNATURE","TIMESTAMP_INVALID","RATE_LIMIT_EXCEEDED","INVALID_REQUEST","INSUFFICIENT_BALANCE","RESOURCE_NOT_FOUND","RESOURCE_CONFLICT","INTERNAL_ERROR","SERVICE_UNAVAILABLE"]},"message":{"type":"string"},"details":{"type":"object","nullable":true}}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}}}}}}},"/smart-energy/{id}/pause":{"post":{"summary":"Pause a subscription","description":"Halts auto-delegation. Balance is preserved; resume any time.","tags":["Smart Energy"],"parameters":[{"name":"id","in":"path","required":true,"description":"Subscription id.","schema":{"type":"string"},"example":"clsmart1234567890"}],"responses":{"200":{"description":"Paused","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["id","address","product_slug","product_name","status","balance_trx","total_delegations","created_at"],"properties":{"id":{"type":"string"},"address":{"type":"string","description":"Recipient TRON address."},"product_slug":{"type":"string","enum":["smart-delegation-65k","smart-delegation-131k"]},"product_name":{"type":"string"},"status":{"type":"string","enum":["active","paused","deleted"]},"balance_trx":{"type":"string"},"total_delegations":{"type":"integer"},"deleted_at":{"type":"string","format":"date-time","nullable":true},"refund_amount_trx":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"}},"example":{"id":"clsmart1234567890","address":"TXyZrecipient1234567890ABCDEF","product_slug":"smart-delegation-65k","product_name":"Smart Energy 65k","status":"active","balance_trx":"100.000000","total_delegations":42,"deleted_at":null,"refund_amount_trx":null,"created_at":"2026-05-20T08:00:00.000Z"}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"data":{"id":"clsmart1234567890","address":"TXyZrecipient1234567890ABCDEF","product_slug":"smart-delegation-65k","product_name":"Smart Energy 65k","status":"active","balance_trx":"100.000000","total_delegations":42,"deleted_at":null,"refund_amount_trx":null,"created_at":"2026-05-20T08:00:00.000Z"},"meta":{"request_id":"ab12cd34ef56gh78"}}},"example":{"data":{"id":"clsmart1234567890","address":"TXyZrecipient1234567890ABCDEF","product_slug":"smart-delegation-65k","product_name":"Smart Energy 65k","status":"active","balance_trx":"100.000000","total_delegations":42,"deleted_at":null,"refund_amount_trx":null,"created_at":"2026-05-20T08:00:00.000Z"},"meta":{"request_id":"ab12cd34ef56gh78"}}}}},"401":{"description":"AUTH_REQUIRED / INVALID_API_KEY / INVALID_SIGNATURE / TIMESTAMP_INVALID","content":{"application/json":{"schema":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_REQUIRED","INVALID_API_KEY","INVALID_SIGNATURE","TIMESTAMP_INVALID","RATE_LIMIT_EXCEEDED","INVALID_REQUEST","INSUFFICIENT_BALANCE","RESOURCE_NOT_FOUND","RESOURCE_CONFLICT","INTERNAL_ERROR","SERVICE_UNAVAILABLE"]},"message":{"type":"string"},"details":{"type":"object","nullable":true}}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}}}},"404":{"description":"RESOURCE_NOT_FOUND","content":{"application/json":{"schema":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_REQUIRED","INVALID_API_KEY","INVALID_SIGNATURE","TIMESTAMP_INVALID","RATE_LIMIT_EXCEEDED","INVALID_REQUEST","INSUFFICIENT_BALANCE","RESOURCE_NOT_FOUND","RESOURCE_CONFLICT","INTERNAL_ERROR","SERVICE_UNAVAILABLE"]},"message":{"type":"string"},"details":{"type":"object","nullable":true}}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}}}},"409":{"description":"RESOURCE_CONFLICT — not in active state","content":{"application/json":{"schema":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_REQUIRED","INVALID_API_KEY","INVALID_SIGNATURE","TIMESTAMP_INVALID","RATE_LIMIT_EXCEEDED","INVALID_REQUEST","INSUFFICIENT_BALANCE","RESOURCE_NOT_FOUND","RESOURCE_CONFLICT","INTERNAL_ERROR","SERVICE_UNAVAILABLE"]},"message":{"type":"string"},"details":{"type":"object","nullable":true}}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}}}},"429":{"description":"RATE_LIMIT_EXCEEDED — see X-RateLimit-Reset + Retry-After","content":{"application/json":{"schema":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_REQUIRED","INVALID_API_KEY","INVALID_SIGNATURE","TIMESTAMP_INVALID","RATE_LIMIT_EXCEEDED","INVALID_REQUEST","INSUFFICIENT_BALANCE","RESOURCE_NOT_FOUND","RESOURCE_CONFLICT","INTERNAL_ERROR","SERVICE_UNAVAILABLE"]},"message":{"type":"string"},"details":{"type":"object","nullable":true}}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}}}},"500":{"description":"INTERNAL_ERROR — server fault, include the request_id when reporting","content":{"application/json":{"schema":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_REQUIRED","INVALID_API_KEY","INVALID_SIGNATURE","TIMESTAMP_INVALID","RATE_LIMIT_EXCEEDED","INVALID_REQUEST","INSUFFICIENT_BALANCE","RESOURCE_NOT_FOUND","RESOURCE_CONFLICT","INTERNAL_ERROR","SERVICE_UNAVAILABLE"]},"message":{"type":"string"},"details":{"type":"object","nullable":true}}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}}}},"503":{"description":"SERVICE_UNAVAILABLE — temporary upstream failure","content":{"application/json":{"schema":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_REQUIRED","INVALID_API_KEY","INVALID_SIGNATURE","TIMESTAMP_INVALID","RATE_LIMIT_EXCEEDED","INVALID_REQUEST","INSUFFICIENT_BALANCE","RESOURCE_NOT_FOUND","RESOURCE_CONFLICT","INTERNAL_ERROR","SERVICE_UNAVAILABLE"]},"message":{"type":"string"},"details":{"type":"object","nullable":true}}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}}}}}}},"/smart-energy/{id}/resume":{"post":{"summary":"Resume a paused subscription","description":"Returns the subscription to active state.","tags":["Smart Energy"],"parameters":[{"name":"id","in":"path","required":true,"description":"Subscription id.","schema":{"type":"string"},"example":"clsmart1234567890"}],"responses":{"200":{"description":"Resumed","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["id","address","product_slug","product_name","status","balance_trx","total_delegations","created_at"],"properties":{"id":{"type":"string"},"address":{"type":"string","description":"Recipient TRON address."},"product_slug":{"type":"string","enum":["smart-delegation-65k","smart-delegation-131k"]},"product_name":{"type":"string"},"status":{"type":"string","enum":["active","paused","deleted"]},"balance_trx":{"type":"string"},"total_delegations":{"type":"integer"},"deleted_at":{"type":"string","format":"date-time","nullable":true},"refund_amount_trx":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"}},"example":{"id":"clsmart1234567890","address":"TXyZrecipient1234567890ABCDEF","product_slug":"smart-delegation-65k","product_name":"Smart Energy 65k","status":"active","balance_trx":"100.000000","total_delegations":42,"deleted_at":null,"refund_amount_trx":null,"created_at":"2026-05-20T08:00:00.000Z"}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"data":{"id":"clsmart1234567890","address":"TXyZrecipient1234567890ABCDEF","product_slug":"smart-delegation-65k","product_name":"Smart Energy 65k","status":"active","balance_trx":"100.000000","total_delegations":42,"deleted_at":null,"refund_amount_trx":null,"created_at":"2026-05-20T08:00:00.000Z"},"meta":{"request_id":"ab12cd34ef56gh78"}}},"example":{"data":{"id":"clsmart1234567890","address":"TXyZrecipient1234567890ABCDEF","product_slug":"smart-delegation-65k","product_name":"Smart Energy 65k","status":"active","balance_trx":"100.000000","total_delegations":42,"deleted_at":null,"refund_amount_trx":null,"created_at":"2026-05-20T08:00:00.000Z"},"meta":{"request_id":"ab12cd34ef56gh78"}}}}},"401":{"description":"AUTH_REQUIRED / INVALID_API_KEY / INVALID_SIGNATURE / TIMESTAMP_INVALID","content":{"application/json":{"schema":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_REQUIRED","INVALID_API_KEY","INVALID_SIGNATURE","TIMESTAMP_INVALID","RATE_LIMIT_EXCEEDED","INVALID_REQUEST","INSUFFICIENT_BALANCE","RESOURCE_NOT_FOUND","RESOURCE_CONFLICT","INTERNAL_ERROR","SERVICE_UNAVAILABLE"]},"message":{"type":"string"},"details":{"type":"object","nullable":true}}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}}}},"404":{"description":"RESOURCE_NOT_FOUND","content":{"application/json":{"schema":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_REQUIRED","INVALID_API_KEY","INVALID_SIGNATURE","TIMESTAMP_INVALID","RATE_LIMIT_EXCEEDED","INVALID_REQUEST","INSUFFICIENT_BALANCE","RESOURCE_NOT_FOUND","RESOURCE_CONFLICT","INTERNAL_ERROR","SERVICE_UNAVAILABLE"]},"message":{"type":"string"},"details":{"type":"object","nullable":true}}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}}}},"409":{"description":"RESOURCE_CONFLICT — not in paused state","content":{"application/json":{"schema":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_REQUIRED","INVALID_API_KEY","INVALID_SIGNATURE","TIMESTAMP_INVALID","RATE_LIMIT_EXCEEDED","INVALID_REQUEST","INSUFFICIENT_BALANCE","RESOURCE_NOT_FOUND","RESOURCE_CONFLICT","INTERNAL_ERROR","SERVICE_UNAVAILABLE"]},"message":{"type":"string"},"details":{"type":"object","nullable":true}}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}}}},"429":{"description":"RATE_LIMIT_EXCEEDED — see X-RateLimit-Reset + Retry-After","content":{"application/json":{"schema":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_REQUIRED","INVALID_API_KEY","INVALID_SIGNATURE","TIMESTAMP_INVALID","RATE_LIMIT_EXCEEDED","INVALID_REQUEST","INSUFFICIENT_BALANCE","RESOURCE_NOT_FOUND","RESOURCE_CONFLICT","INTERNAL_ERROR","SERVICE_UNAVAILABLE"]},"message":{"type":"string"},"details":{"type":"object","nullable":true}}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}}}},"500":{"description":"INTERNAL_ERROR — server fault, include the request_id when reporting","content":{"application/json":{"schema":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_REQUIRED","INVALID_API_KEY","INVALID_SIGNATURE","TIMESTAMP_INVALID","RATE_LIMIT_EXCEEDED","INVALID_REQUEST","INSUFFICIENT_BALANCE","RESOURCE_NOT_FOUND","RESOURCE_CONFLICT","INTERNAL_ERROR","SERVICE_UNAVAILABLE"]},"message":{"type":"string"},"details":{"type":"object","nullable":true}}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}}}},"503":{"description":"SERVICE_UNAVAILABLE — temporary upstream failure","content":{"application/json":{"schema":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_REQUIRED","INVALID_API_KEY","INVALID_SIGNATURE","TIMESTAMP_INVALID","RATE_LIMIT_EXCEEDED","INVALID_REQUEST","INSUFFICIENT_BALANCE","RESOURCE_NOT_FOUND","RESOURCE_CONFLICT","INTERNAL_ERROR","SERVICE_UNAVAILABLE"]},"message":{"type":"string"},"details":{"type":"object","nullable":true}}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}}}}}}},"/smart-energy/{id}/topup":{"post":{"summary":"Top up a subscription's balance","description":"Adds TRX to an active subscription.","tags":["Smart Energy"],"parameters":[{"name":"id","in":"path","required":true,"description":"Subscription id.","schema":{"type":"string"},"example":"clsmart1234567890"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["top_up_trx"],"properties":{"top_up_trx":{"type":"number","description":"TRX to add."}}},"example":{"top_up_trx":50}}}},"responses":{"200":{"description":"Topped up","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["id","address","product_slug","product_name","status","balance_trx","total_delegations","created_at"],"properties":{"id":{"type":"string"},"address":{"type":"string","description":"Recipient TRON address."},"product_slug":{"type":"string","enum":["smart-delegation-65k","smart-delegation-131k"]},"product_name":{"type":"string"},"status":{"type":"string","enum":["active","paused","deleted"]},"balance_trx":{"type":"string"},"total_delegations":{"type":"integer"},"deleted_at":{"type":"string","format":"date-time","nullable":true},"refund_amount_trx":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"}},"example":{"id":"clsmart1234567890","address":"TXyZrecipient1234567890ABCDEF","product_slug":"smart-delegation-65k","product_name":"Smart Energy 65k","status":"active","balance_trx":"100.000000","total_delegations":42,"deleted_at":null,"refund_amount_trx":null,"created_at":"2026-05-20T08:00:00.000Z"}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"data":{"id":"clsmart1234567890","address":"TXyZrecipient1234567890ABCDEF","product_slug":"smart-delegation-65k","product_name":"Smart Energy 65k","status":"active","balance_trx":"100.000000","total_delegations":42,"deleted_at":null,"refund_amount_trx":null,"created_at":"2026-05-20T08:00:00.000Z"},"meta":{"request_id":"ab12cd34ef56gh78"}}},"example":{"data":{"id":"clsmart1234567890","address":"TXyZrecipient1234567890ABCDEF","product_slug":"smart-delegation-65k","product_name":"Smart Energy 65k","status":"active","balance_trx":"100.000000","total_delegations":42,"deleted_at":null,"refund_amount_trx":null,"created_at":"2026-05-20T08:00:00.000Z"},"meta":{"request_id":"ab12cd34ef56gh78"}}}}},"401":{"description":"AUTH_REQUIRED / INVALID_API_KEY / INVALID_SIGNATURE / TIMESTAMP_INVALID","content":{"application/json":{"schema":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_REQUIRED","INVALID_API_KEY","INVALID_SIGNATURE","TIMESTAMP_INVALID","RATE_LIMIT_EXCEEDED","INVALID_REQUEST","INSUFFICIENT_BALANCE","RESOURCE_NOT_FOUND","RESOURCE_CONFLICT","INTERNAL_ERROR","SERVICE_UNAVAILABLE"]},"message":{"type":"string"},"details":{"type":"object","nullable":true}}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}}}},"402":{"description":"INSUFFICIENT_BALANCE","content":{"application/json":{"schema":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_REQUIRED","INVALID_API_KEY","INVALID_SIGNATURE","TIMESTAMP_INVALID","RATE_LIMIT_EXCEEDED","INVALID_REQUEST","INSUFFICIENT_BALANCE","RESOURCE_NOT_FOUND","RESOURCE_CONFLICT","INTERNAL_ERROR","SERVICE_UNAVAILABLE"]},"message":{"type":"string"},"details":{"type":"object","nullable":true}}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}}}},"404":{"description":"RESOURCE_NOT_FOUND","content":{"application/json":{"schema":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_REQUIRED","INVALID_API_KEY","INVALID_SIGNATURE","TIMESTAMP_INVALID","RATE_LIMIT_EXCEEDED","INVALID_REQUEST","INSUFFICIENT_BALANCE","RESOURCE_NOT_FOUND","RESOURCE_CONFLICT","INTERNAL_ERROR","SERVICE_UNAVAILABLE"]},"message":{"type":"string"},"details":{"type":"object","nullable":true}}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}}}},"429":{"description":"RATE_LIMIT_EXCEEDED — see X-RateLimit-Reset + Retry-After","content":{"application/json":{"schema":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_REQUIRED","INVALID_API_KEY","INVALID_SIGNATURE","TIMESTAMP_INVALID","RATE_LIMIT_EXCEEDED","INVALID_REQUEST","INSUFFICIENT_BALANCE","RESOURCE_NOT_FOUND","RESOURCE_CONFLICT","INTERNAL_ERROR","SERVICE_UNAVAILABLE"]},"message":{"type":"string"},"details":{"type":"object","nullable":true}}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}}}},"500":{"description":"INTERNAL_ERROR — server fault, include the request_id when reporting","content":{"application/json":{"schema":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_REQUIRED","INVALID_API_KEY","INVALID_SIGNATURE","TIMESTAMP_INVALID","RATE_LIMIT_EXCEEDED","INVALID_REQUEST","INSUFFICIENT_BALANCE","RESOURCE_NOT_FOUND","RESOURCE_CONFLICT","INTERNAL_ERROR","SERVICE_UNAVAILABLE"]},"message":{"type":"string"},"details":{"type":"object","nullable":true}}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}}}},"503":{"description":"SERVICE_UNAVAILABLE — temporary upstream failure","content":{"application/json":{"schema":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_REQUIRED","INVALID_API_KEY","INVALID_SIGNATURE","TIMESTAMP_INVALID","RATE_LIMIT_EXCEEDED","INVALID_REQUEST","INSUFFICIENT_BALANCE","RESOURCE_NOT_FOUND","RESOURCE_CONFLICT","INTERNAL_ERROR","SERVICE_UNAVAILABLE"]},"message":{"type":"string"},"details":{"type":"object","nullable":true}}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}}}}}}},"/transactions":{"get":{"summary":"List your transactions","description":"Your transaction ledger. Some non-customer system entries are excluded, as are below-minimum deposits.","tags":["Transactions"],"parameters":[{"name":"page","in":"query","required":false,"description":"Page number.","schema":{"type":"integer","minimum":1,"default":1},"example":1},{"name":"per_page","in":"query","required":false,"description":"Page size (max 100).","schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"example":50},{"name":"type","in":"query","required":false,"description":"Filter by ledger type.","schema":{"type":"string","enum":["deposit","order","refund","manual_credit","manual_debit","smart_delegation_topup"]},"example":"deposit"}],"responses":{"200":{"description":"Paginated transactions","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","required":["id","type","amount","currency","status","created_at"],"properties":{"id":{"type":"string"},"type":{"type":"string","enum":["deposit","order","refund","manual_credit","manual_debit","smart_delegation_topup"]},"amount":{"type":"string"},"currency":{"type":"string","enum":["TRX","USDT"]},"status":{"type":"string","enum":["pending","confirmed","failed"]},"tx_hash":{"type":"string","nullable":true,"description":"On-chain hash for deposits (Tronscan)."},"created_at":{"type":"string","format":"date-time"}},"example":{"id":"cltx1234567890","type":"deposit","amount":"100.000000","currency":"TRX","status":"confirmed","tx_hash":"9f8e7d6c5b4a3210...","created_at":"2026-05-26T14:22:11.000Z"}}},"meta":{"type":"object","required":["request_id","page","per_page","total","has_more"],"properties":{"request_id":{"type":"string"},"page":{"type":"integer"},"per_page":{"type":"integer"},"total":{"type":"integer"},"has_more":{"type":"boolean"}}}},"example":{"data":[{"id":"cltx1234567890","type":"deposit","amount":"100.000000","currency":"TRX","status":"confirmed","tx_hash":"9f8e7d6c5b4a3210...","created_at":"2026-05-26T14:22:11.000Z"}],"meta":{"request_id":"ab12cd34ef56gh78","page":1,"per_page":50,"total":1,"has_more":false}}},"example":{"data":[{"id":"cltx1234567890","type":"deposit","amount":"100.000000","currency":"TRX","status":"confirmed","tx_hash":"9f8e7d6c5b4a3210...","created_at":"2026-05-26T14:22:11.000Z"}],"meta":{"request_id":"ab12cd34ef56gh78","page":1,"per_page":50,"total":1,"has_more":false}}}}},"401":{"description":"AUTH_REQUIRED / INVALID_API_KEY / INVALID_SIGNATURE / TIMESTAMP_INVALID","content":{"application/json":{"schema":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_REQUIRED","INVALID_API_KEY","INVALID_SIGNATURE","TIMESTAMP_INVALID","RATE_LIMIT_EXCEEDED","INVALID_REQUEST","INSUFFICIENT_BALANCE","RESOURCE_NOT_FOUND","RESOURCE_CONFLICT","INTERNAL_ERROR","SERVICE_UNAVAILABLE"]},"message":{"type":"string"},"details":{"type":"object","nullable":true}}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}}}},"429":{"description":"RATE_LIMIT_EXCEEDED — see X-RateLimit-Reset + Retry-After","content":{"application/json":{"schema":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_REQUIRED","INVALID_API_KEY","INVALID_SIGNATURE","TIMESTAMP_INVALID","RATE_LIMIT_EXCEEDED","INVALID_REQUEST","INSUFFICIENT_BALANCE","RESOURCE_NOT_FOUND","RESOURCE_CONFLICT","INTERNAL_ERROR","SERVICE_UNAVAILABLE"]},"message":{"type":"string"},"details":{"type":"object","nullable":true}}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}}}},"500":{"description":"INTERNAL_ERROR — server fault, include the request_id when reporting","content":{"application/json":{"schema":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_REQUIRED","INVALID_API_KEY","INVALID_SIGNATURE","TIMESTAMP_INVALID","RATE_LIMIT_EXCEEDED","INVALID_REQUEST","INSUFFICIENT_BALANCE","RESOURCE_NOT_FOUND","RESOURCE_CONFLICT","INTERNAL_ERROR","SERVICE_UNAVAILABLE"]},"message":{"type":"string"},"details":{"type":"object","nullable":true}}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}}}},"503":{"description":"SERVICE_UNAVAILABLE — temporary upstream failure","content":{"application/json":{"schema":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_REQUIRED","INVALID_API_KEY","INVALID_SIGNATURE","TIMESTAMP_INVALID","RATE_LIMIT_EXCEEDED","INVALID_REQUEST","INSUFFICIENT_BALANCE","RESOURCE_NOT_FOUND","RESOURCE_CONFLICT","INTERNAL_ERROR","SERVICE_UNAVAILABLE"]},"message":{"type":"string"},"details":{"type":"object","nullable":true}}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}}}}}}},"/transactions/{id}":{"get":{"summary":"Get a transaction","description":"Single-transaction lookup. Returns 404 if the transaction isn't part of your visible ledger.","tags":["Transactions"],"parameters":[{"name":"id","in":"path","required":true,"description":"Transaction id.","schema":{"type":"string"},"example":"cltx1234567890"}],"responses":{"200":{"description":"Transaction","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["id","type","amount","currency","status","created_at"],"properties":{"id":{"type":"string"},"type":{"type":"string","enum":["deposit","order","refund","manual_credit","manual_debit","smart_delegation_topup"]},"amount":{"type":"string"},"currency":{"type":"string","enum":["TRX","USDT"]},"status":{"type":"string","enum":["pending","confirmed","failed"]},"tx_hash":{"type":"string","nullable":true,"description":"On-chain hash for deposits (Tronscan)."},"created_at":{"type":"string","format":"date-time"}},"example":{"id":"cltx1234567890","type":"deposit","amount":"100.000000","currency":"TRX","status":"confirmed","tx_hash":"9f8e7d6c5b4a3210...","created_at":"2026-05-26T14:22:11.000Z"}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"data":{"id":"cltx1234567890","type":"deposit","amount":"100.000000","currency":"TRX","status":"confirmed","tx_hash":"9f8e7d6c5b4a3210...","created_at":"2026-05-26T14:22:11.000Z"},"meta":{"request_id":"ab12cd34ef56gh78"}}},"example":{"data":{"id":"cltx1234567890","type":"deposit","amount":"100.000000","currency":"TRX","status":"confirmed","tx_hash":"9f8e7d6c5b4a3210...","created_at":"2026-05-26T14:22:11.000Z"},"meta":{"request_id":"ab12cd34ef56gh78"}}}}},"401":{"description":"AUTH_REQUIRED / INVALID_API_KEY / INVALID_SIGNATURE / TIMESTAMP_INVALID","content":{"application/json":{"schema":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_REQUIRED","INVALID_API_KEY","INVALID_SIGNATURE","TIMESTAMP_INVALID","RATE_LIMIT_EXCEEDED","INVALID_REQUEST","INSUFFICIENT_BALANCE","RESOURCE_NOT_FOUND","RESOURCE_CONFLICT","INTERNAL_ERROR","SERVICE_UNAVAILABLE"]},"message":{"type":"string"},"details":{"type":"object","nullable":true}}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}}}},"404":{"description":"RESOURCE_NOT_FOUND","content":{"application/json":{"schema":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_REQUIRED","INVALID_API_KEY","INVALID_SIGNATURE","TIMESTAMP_INVALID","RATE_LIMIT_EXCEEDED","INVALID_REQUEST","INSUFFICIENT_BALANCE","RESOURCE_NOT_FOUND","RESOURCE_CONFLICT","INTERNAL_ERROR","SERVICE_UNAVAILABLE"]},"message":{"type":"string"},"details":{"type":"object","nullable":true}}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}}}},"429":{"description":"RATE_LIMIT_EXCEEDED — see X-RateLimit-Reset + Retry-After","content":{"application/json":{"schema":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_REQUIRED","INVALID_API_KEY","INVALID_SIGNATURE","TIMESTAMP_INVALID","RATE_LIMIT_EXCEEDED","INVALID_REQUEST","INSUFFICIENT_BALANCE","RESOURCE_NOT_FOUND","RESOURCE_CONFLICT","INTERNAL_ERROR","SERVICE_UNAVAILABLE"]},"message":{"type":"string"},"details":{"type":"object","nullable":true}}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}}}},"500":{"description":"INTERNAL_ERROR — server fault, include the request_id when reporting","content":{"application/json":{"schema":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_REQUIRED","INVALID_API_KEY","INVALID_SIGNATURE","TIMESTAMP_INVALID","RATE_LIMIT_EXCEEDED","INVALID_REQUEST","INSUFFICIENT_BALANCE","RESOURCE_NOT_FOUND","RESOURCE_CONFLICT","INTERNAL_ERROR","SERVICE_UNAVAILABLE"]},"message":{"type":"string"},"details":{"type":"object","nullable":true}}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}}}},"503":{"description":"SERVICE_UNAVAILABLE — temporary upstream failure","content":{"application/json":{"schema":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_REQUIRED","INVALID_API_KEY","INVALID_SIGNATURE","TIMESTAMP_INVALID","RATE_LIMIT_EXCEEDED","INVALID_REQUEST","INSUFFICIENT_BALANCE","RESOURCE_NOT_FOUND","RESOURCE_CONFLICT","INTERNAL_ERROR","SERVICE_UNAVAILABLE"]},"message":{"type":"string"},"details":{"type":"object","nullable":true}}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}}}}}}},"/webhooks":{"get":{"summary":"List your webhook subscriptions","description":"Returns the public projection — never the signing secret. Read-only on this surface; create / edit / delete / test live behind the dashboard at /dashboard/webhooks (session-authenticated). HMAC signatures on outbound deliveries land in the `X-Energytrx-Signature` header.","tags":["Webhooks"],"responses":{"200":{"description":"Array of webhooks","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","required":["id","url","events","active","failure_count","created_at","updated_at"],"properties":{"id":{"type":"string"},"url":{"type":"string","description":"Destination URL (HTTPS in production)."},"events":{"type":"array","items":{"type":"string"},"description":"Subscribed event types."},"active":{"type":"boolean"},"failure_count":{"type":"integer","description":"Consecutive delivery exhaustions; auto-disables at 20."},"last_delivery_at":{"type":"string","format":"date-time","nullable":true},"last_failure_at":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"example":{"id":"clwh1234567890","url":"https://your-server.example.com/webhook","events":["order.created","deposit.received"],"active":true,"failure_count":0,"last_delivery_at":"2026-05-27T10:00:00.000Z","last_failure_at":null,"created_at":"2026-05-20T08:00:00.000Z","updated_at":"2026-05-20T08:00:00.000Z"}}},"meta":{"type":"object"}}},"example":{"data":[{"id":"clwh1234567890","url":"https://your-server.example.com/webhook","events":["order.created","deposit.received"],"active":true,"failure_count":0,"last_delivery_at":"2026-05-27T10:00:00.000Z","last_failure_at":null,"created_at":"2026-05-20T08:00:00.000Z","updated_at":"2026-05-20T08:00:00.000Z"}],"meta":{"request_id":"ab12cd34ef56gh78","count":1}}}}},"401":{"description":"AUTH_REQUIRED / INVALID_API_KEY / INVALID_SIGNATURE / TIMESTAMP_INVALID","content":{"application/json":{"schema":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_REQUIRED","INVALID_API_KEY","INVALID_SIGNATURE","TIMESTAMP_INVALID","RATE_LIMIT_EXCEEDED","INVALID_REQUEST","INSUFFICIENT_BALANCE","RESOURCE_NOT_FOUND","RESOURCE_CONFLICT","INTERNAL_ERROR","SERVICE_UNAVAILABLE"]},"message":{"type":"string"},"details":{"type":"object","nullable":true}}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}}}},"429":{"description":"RATE_LIMIT_EXCEEDED — see X-RateLimit-Reset + Retry-After","content":{"application/json":{"schema":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_REQUIRED","INVALID_API_KEY","INVALID_SIGNATURE","TIMESTAMP_INVALID","RATE_LIMIT_EXCEEDED","INVALID_REQUEST","INSUFFICIENT_BALANCE","RESOURCE_NOT_FOUND","RESOURCE_CONFLICT","INTERNAL_ERROR","SERVICE_UNAVAILABLE"]},"message":{"type":"string"},"details":{"type":"object","nullable":true}}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}}}},"500":{"description":"INTERNAL_ERROR — server fault, include the request_id when reporting","content":{"application/json":{"schema":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_REQUIRED","INVALID_API_KEY","INVALID_SIGNATURE","TIMESTAMP_INVALID","RATE_LIMIT_EXCEEDED","INVALID_REQUEST","INSUFFICIENT_BALANCE","RESOURCE_NOT_FOUND","RESOURCE_CONFLICT","INTERNAL_ERROR","SERVICE_UNAVAILABLE"]},"message":{"type":"string"},"details":{"type":"object","nullable":true}}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}}}},"503":{"description":"SERVICE_UNAVAILABLE — temporary upstream failure","content":{"application/json":{"schema":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_REQUIRED","INVALID_API_KEY","INVALID_SIGNATURE","TIMESTAMP_INVALID","RATE_LIMIT_EXCEEDED","INVALID_REQUEST","INSUFFICIENT_BALANCE","RESOURCE_NOT_FOUND","RESOURCE_CONFLICT","INTERNAL_ERROR","SERVICE_UNAVAILABLE"]},"message":{"type":"string"},"details":{"type":"object","nullable":true}}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}}}}}}},"/api-keys":{"get":{"summary":"List your API keys","description":"Returns the public projection — never the full key or secret. Read-only on this surface; key creation + revocation live behind the dashboard at /dashboard/api-keys (session-authenticated).","tags":["API Keys"],"responses":{"200":{"description":"Array of keys","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","required":["id","name","prefix","scopes","createdAt"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"prefix":{"type":"string","description":"First 8 chars of the key (for identification)."},"scopes":{"type":"array","items":{"type":"string"}},"lastUsedAt":{"type":"string","format":"date-time","nullable":true},"lastUsedIp":{"type":"string","nullable":true},"expiresAt":{"type":"string","format":"date-time","nullable":true},"revokedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"example":{"id":"clkey1234567890","name":"Production server","prefix":"a1b2c3d4","scopes":["read","write"],"lastUsedAt":"2026-05-27T09:00:00.000Z","lastUsedIp":"203.0.113.42","expiresAt":null,"revokedAt":null,"createdAt":"2026-05-01T12:00:00.000Z"}}},"meta":{"type":"object"}}},"example":{"data":[{"id":"clkey1234567890","name":"Production server","prefix":"a1b2c3d4","scopes":["read","write"],"lastUsedAt":"2026-05-27T09:00:00.000Z","lastUsedIp":"203.0.113.42","expiresAt":null,"revokedAt":null,"createdAt":"2026-05-01T12:00:00.000Z"}],"meta":{"request_id":"ab12cd34ef56gh78","count":1}}}}},"401":{"description":"AUTH_REQUIRED / INVALID_API_KEY / INVALID_SIGNATURE / TIMESTAMP_INVALID","content":{"application/json":{"schema":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_REQUIRED","INVALID_API_KEY","INVALID_SIGNATURE","TIMESTAMP_INVALID","RATE_LIMIT_EXCEEDED","INVALID_REQUEST","INSUFFICIENT_BALANCE","RESOURCE_NOT_FOUND","RESOURCE_CONFLICT","INTERNAL_ERROR","SERVICE_UNAVAILABLE"]},"message":{"type":"string"},"details":{"type":"object","nullable":true}}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}}}},"429":{"description":"RATE_LIMIT_EXCEEDED — see X-RateLimit-Reset + Retry-After","content":{"application/json":{"schema":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_REQUIRED","INVALID_API_KEY","INVALID_SIGNATURE","TIMESTAMP_INVALID","RATE_LIMIT_EXCEEDED","INVALID_REQUEST","INSUFFICIENT_BALANCE","RESOURCE_NOT_FOUND","RESOURCE_CONFLICT","INTERNAL_ERROR","SERVICE_UNAVAILABLE"]},"message":{"type":"string"},"details":{"type":"object","nullable":true}}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}}}},"500":{"description":"INTERNAL_ERROR — server fault, include the request_id when reporting","content":{"application/json":{"schema":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_REQUIRED","INVALID_API_KEY","INVALID_SIGNATURE","TIMESTAMP_INVALID","RATE_LIMIT_EXCEEDED","INVALID_REQUEST","INSUFFICIENT_BALANCE","RESOURCE_NOT_FOUND","RESOURCE_CONFLICT","INTERNAL_ERROR","SERVICE_UNAVAILABLE"]},"message":{"type":"string"},"details":{"type":"object","nullable":true}}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}}}},"503":{"description":"SERVICE_UNAVAILABLE — temporary upstream failure","content":{"application/json":{"schema":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_REQUIRED","INVALID_API_KEY","INVALID_SIGNATURE","TIMESTAMP_INVALID","RATE_LIMIT_EXCEEDED","INVALID_REQUEST","INSUFFICIENT_BALANCE","RESOURCE_NOT_FOUND","RESOURCE_CONFLICT","INTERNAL_ERROR","SERVICE_UNAVAILABLE"]},"message":{"type":"string"},"details":{"type":"object","nullable":true}}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}}}}}}},"/api-usage":{"get":{"summary":"Aggregate your recent API traffic","description":"Returns daily request counts, top endpoints, per-key breakdown, and overall error rate for the last `days` days (default 7, max 90).","tags":["Usage"],"parameters":[{"name":"days","in":"query","required":false,"description":"Window length in days (1..90).","schema":{"type":"integer","minimum":1,"maximum":90,"default":7},"example":7},{"name":"api_key_id","in":"query","required":false,"description":"Narrow to a single API key.","schema":{"type":"string"}}],"responses":{"200":{"description":"Aggregated usage","content":{"application/json":{"schema":{"type":"object","properties":{"total_requests":{"type":"integer"},"total_errors":{"type":"integer"},"error_rate":{"type":"number"},"unique_endpoints":{"type":"integer"},"daily":{"type":"array","items":{"type":"object"}},"top_endpoints":{"type":"array","items":{"type":"object"}},"per_key":{"type":"array","items":{"type":"object"}}}},"example":{"data":{"total_requests":1247,"total_errors":12,"error_rate":0.0096,"unique_endpoints":8,"daily":[{"date":"2026-05-27","total":247,"errors":1}],"top_endpoints":[{"method":"GET","path":"/api/v1/prices","count":612,"error_count":0}],"per_key":[{"api_key_id":"clkey1234567890","count":1247,"error_count":12}]},"meta":{"request_id":"ab12cd34ef56gh78","window_days":7}}}}},"401":{"description":"AUTH_REQUIRED / INVALID_API_KEY / INVALID_SIGNATURE / TIMESTAMP_INVALID","content":{"application/json":{"schema":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_REQUIRED","INVALID_API_KEY","INVALID_SIGNATURE","TIMESTAMP_INVALID","RATE_LIMIT_EXCEEDED","INVALID_REQUEST","INSUFFICIENT_BALANCE","RESOURCE_NOT_FOUND","RESOURCE_CONFLICT","INTERNAL_ERROR","SERVICE_UNAVAILABLE"]},"message":{"type":"string"},"details":{"type":"object","nullable":true}}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}}}},"429":{"description":"RATE_LIMIT_EXCEEDED — see X-RateLimit-Reset + Retry-After","content":{"application/json":{"schema":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_REQUIRED","INVALID_API_KEY","INVALID_SIGNATURE","TIMESTAMP_INVALID","RATE_LIMIT_EXCEEDED","INVALID_REQUEST","INSUFFICIENT_BALANCE","RESOURCE_NOT_FOUND","RESOURCE_CONFLICT","INTERNAL_ERROR","SERVICE_UNAVAILABLE"]},"message":{"type":"string"},"details":{"type":"object","nullable":true}}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}}}},"500":{"description":"INTERNAL_ERROR — server fault, include the request_id when reporting","content":{"application/json":{"schema":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_REQUIRED","INVALID_API_KEY","INVALID_SIGNATURE","TIMESTAMP_INVALID","RATE_LIMIT_EXCEEDED","INVALID_REQUEST","INSUFFICIENT_BALANCE","RESOURCE_NOT_FOUND","RESOURCE_CONFLICT","INTERNAL_ERROR","SERVICE_UNAVAILABLE"]},"message":{"type":"string"},"details":{"type":"object","nullable":true}}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}}}},"503":{"description":"SERVICE_UNAVAILABLE — temporary upstream failure","content":{"application/json":{"schema":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_REQUIRED","INVALID_API_KEY","INVALID_SIGNATURE","TIMESTAMP_INVALID","RATE_LIMIT_EXCEEDED","INVALID_REQUEST","INSUFFICIENT_BALANCE","RESOURCE_NOT_FOUND","RESOURCE_CONFLICT","INTERNAL_ERROR","SERVICE_UNAVAILABLE"]},"message":{"type":"string"},"details":{"type":"object","nullable":true}}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}},"example":{"error":{"code":"RESOURCE_NOT_FOUND","message":"Order not found."},"meta":{"request_id":"ab12cd34ef56gh78"}}}}}}}}}}