{"openapi":"3.1.0","info":{"title":"SunLend Energy API","version":"1.0.0","description":"Buying TRON energy and bandwidth from a SunLend account balance. Money is in sun (1 TRX = 1 000 000 sun). Human-readable docs: /docs/energy-api.md"},"servers":[{"url":"https://sunlend.io/api/v1/energy"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"API key slk_… from the account area (section “API”)"}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{"type":"string"}}}}}},"Resource":{"type":"string","enum":["energy","bandwidth"]},"Term":{"type":"string","enum":["15m","1h","1d"]},"Order":{"type":"object","required":["id","resource","address","volume","term","priceSun","status","createdAt"],"properties":{"id":{"type":"integer"},"apiKeyId":{"type":["integer","null"]},"resource":{"$ref":"#/components/schemas/Resource"},"address":{"type":"string","pattern":"^T[1-9A-HJ-NP-Za-km-z]{33}$"},"volume":{"type":"integer"},"term":{"$ref":"#/components/schemas/Term"},"priceSun":{"type":"integer"},"status":{"type":"string","enum":["pending","filled","failed"]},"txId":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"}}},"Quote":{"type":"object","properties":{"resource":{"$ref":"#/components/schemas/Resource"},"volume":{"type":"integer"},"term":{"$ref":"#/components/schemas/Term"},"priceSun":{"type":"integer"},"sunPerUnit":{"type":["integer","null"]},"feeSun":{"type":["integer","null"],"description":"Fixed fee per energy order, sun (any volume)"},"trxPer1k":{"type":["number","null"]},"balanceSun":{"type":"integer"}}},"Activation":{"type":"object","properties":{"id":{"type":"integer"},"address":{"type":"string"},"priceSun":{"type":"integer"},"status":{"type":"string","enum":["pending","done","failed"]},"createdAt":{"type":"string","format":"date-time"}}},"Automation":{"type":"object","properties":{"id":{"type":"integer"},"kind":{"type":"string","enum":["refill","renewal","smart"]},"address":{"type":"string"},"volume":{"type":"integer"},"minimal":{"type":["integer","null"]},"duration":{"type":["string","null"],"enum":["1h","1d",null]},"status":{"type":"string","enum":["active","paused"]},"pauseReason":{"type":["string","null"],"enum":["system","user",null]},"autoResume":{"type":"boolean"},"lastFireAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"firePriceSun":{"type":"integer"}}},"AutomationInput":{"type":"object","required":["kind","address"],"additionalProperties":false,"properties":{"kind":{"type":"string","enum":["refill","renewal","smart"]},"address":{"type":"string"},"volume":{"type":"integer","minimum":65000},"minimal":{"type":"integer","minimum":1000},"duration":{"type":"string","enum":["1h","1d"]},"autoResume":{"type":"boolean"}}},"WebhookEvent":{"type":"string","enum":["order.filled","order.failed","deposit.credited","automation.fired","automation.paused","automation.resumed","activation.done"]},"Webhook":{"type":"object","properties":{"id":{"type":"integer"},"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEvent"}},"isActive":{"type":"boolean"},"failures":{"type":"integer"},"lastSuccessAt":{"type":["string","null"],"format":"date-time"},"lastFailureAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"}}},"Delivery":{"type":"object","properties":{"id":{"type":"integer"},"eventId":{"type":"string"},"event":{"type":"string"},"status":{"type":"string","enum":["pending","ok","failed"]},"attempts":{"type":"integer"},"lastStatus":{"type":["integer","null"]},"lastError":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"deliveredAt":{"type":["string","null"],"format":"date-time"}}}}},"paths":{"/account":{"get":{"summary":"Balance and permanent top-up address","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"balanceSun":{"type":"integer"},"depositAddress":{"type":["object","null"],"properties":{"network":{"type":"string"},"address":{"type":"string"}}}}}}}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-scope":"read"}},"/quote":{"get":{"summary":"Order price at the current rate","parameters":[{"name":"resource","in":"query","schema":{"$ref":"#/components/schemas/Resource"}},{"name":"volume","in":"query","required":true,"schema":{"type":"integer"}},{"name":"term","in":"query","required":true,"schema":{"$ref":"#/components/schemas/Term"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Quote"}}}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"invalid_volume, invalid_term, invalid_resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-scope":"read"}},"/orders":{"get":{"summary":"Orders, newest first","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Order"}},"pagination":{"type":"object","properties":{"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}}}}}}}},"400":{"description":"invalid_query","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-scope":"read"},"post":{"summary":"Buy energy or bandwidth from the balance","parameters":[{"name":"Idempotency-Key","in":"header","schema":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{1,100}$"},"description":"Retry with the same key returns the same order without a second charge"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["address","volume","term"],"additionalProperties":false,"properties":{"address":{"type":"string"},"resource":{"$ref":"#/components/schemas/Resource"},"volume":{"type":"integer"},"term":{"$ref":"#/components/schemas/Term"}}}}}},"responses":{"200":{"description":"Replayed by Idempotency-Key","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"order":{"$ref":"#/components/schemas/Order"},"balanceSun":{"type":"integer"}}}}}}}},"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"order":{"$ref":"#/components/schemas/Order"},"balanceSun":{"type":"integer"}}}}}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"insufficient_funds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope or daily_limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"idempotency_conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"provider_failed — money refunded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"provider_off, price_unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"provider_unknown — order is pending, do not retry with a new key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-scope":"purchase"}},"/orders/{id}":{"get":{"summary":"One order","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Order"}}}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-scope":"read"}},"/activations":{"get":{"summary":"Activation price","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"priceSun":{"type":"integer"},"balanceSun":{"type":"integer"}}}}}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-scope":"read"},"post":{"summary":"Activate a new TRON address","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["address"],"additionalProperties":false,"properties":{"address":{"type":"string"}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"activation":{"$ref":"#/components/schemas/Activation"},"balanceSun":{"type":"integer"}}}}}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"insufficient_funds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope or daily_limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"already_active, already_requested","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-scope":"purchase"}},"/automations":{"get":{"summary":"Automation rules","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Automation"}}}}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-scope":"read"},"post":{"summary":"New rule: auto top-up, auto-renewal or Tron Charger","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutomationInput"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Automation"}}}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"insufficient_funds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope or daily_limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"already_exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-scope":"full"}},"/automations/{id}":{"get":{"summary":"One rule","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Automation"}}}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-scope":"read"},"patch":{"summary":"Pause, resume or toggle auto-resume","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["pause","resume"]},"autoResume":{"type":"boolean"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Automation"}}}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"insufficient_funds on resume","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope or daily_limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-scope":"full"},"delete":{"summary":"Delete the rule","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1}}],"responses":{"204":{"description":"Deleted"},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope or daily_limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-scope":"full"}},"/webhooks":{"get":{"summary":"Webhooks","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Webhook"}}}}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-scope":"read"},"post":{"summary":"New webhook; the signing secret is returned once","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url","events"],"properties":{"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEvent"}}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"webhook":{"$ref":"#/components/schemas/Webhook"},"secret":{"type":"string"}}}}}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope or daily_limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"webhook_limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"invalid_url, invalid_events","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-scope":"full"}},"/webhooks/{id}":{"patch":{"summary":"Change url, events or isActive","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string"},"events":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEvent"}},"isActive":{"type":"boolean"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Webhook"}}}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope or daily_limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"invalid_url, invalid_events","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-scope":"full"},"delete":{"summary":"Delete the webhook","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1}}],"responses":{"204":{"description":"Deleted"},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope or daily_limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-scope":"full"}},"/webhooks/{id}/rotate":{"post":{"summary":"New signing secret","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"secret":{"type":"string"}}}}}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope or daily_limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-scope":"full"}},"/webhooks/{id}/ping":{"post":{"summary":"Queue a test ping event","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1}}],"responses":{"202":{"description":"Queued","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"queued":{"type":"boolean"}}}}}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope or daily_limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-scope":"full"}},"/webhooks/{id}/deliveries":{"get":{"summary":"Delivery log, newest first","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Delivery"}}}}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-scope":"read"}},"/webhooks/{id}/deliveries/{deliveryId}":{"post":{"summary":"Resend a failed delivery","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1}},{"name":"deliveryId","in":"path","required":true,"schema":{"type":"integer","minimum":1}}],"responses":{"202":{"description":"Queued","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"queued":{"type":"boolean"}}}}}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope or daily_limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-scope":"full"}}}}