For developers / Guide
Developer guide · integrate in an afternoon

Energy as an API.

Everything the eCandle apps do runs on one REST API — quotes, orders, device status, webhooks — plus a set of published on-chain contracts. This guide takes you from API key to your first confirmed payment event.

01

🔑Get your API key

Sign in to the developer portal and create a key. Keys look like ek_… and are sent as a bearer token:

# base URL
https://api.ecandle.arkreen.com

# every authenticated call
curl -H "Authorization: Bearer ek_your_key" \
  https://api.ecandle.arkreen.com/v1/devices
Treat keys like passwords: server-side only, never in client code or a repo. Rotate from the portal if one leaks.
02

⚡The core loop: quote → order → paid

Powering a device is three calls. Public payment endpoints don't even need a key — they're the same ones the checkout page uses:

# 1. price a session
POST /v1/quote        { deviceId, chain, token, tier }

# 2. create the order (returns id + payment details)
POST /v1/orders       { deviceId, chain, token, amountUsd, quoteId }

# 3. poll until paid — or just listen for the webhook
GET  /v1/orders/:id   → status: pending | success | expired

Payment can come from any rail — a customer's wallet via the on-chain PaymentRouter, cash confirmed by an agent, or scan-to-pay. Your integration doesn't care: the order flips to success either way, and the device powers on.

03

📡Subscribe to webhooks

Register an endpoint in the portal and we'll POST you events as they happen — with retries and backoff if your endpoint is down:

  • payment.confirmed — an order was paid (any rail). The usual trigger for your own fulfilment logic.
  • revenue.recorded / split.settled — money entered the books and the 50/40/10 split executed, with the on-chain reference.
  • ticket.created — a customer reported a problem on a device you care about.
Make handlers idempotent (dedupe on event id): retries mean you can occasionally see the same event twice.
04

🔍Read the world: devices, stats, impact

Read endpoints give you live network state for dashboards and apps:

  • GET /v1/devices/:id/status — live online state of a single device (public).
  • GET /v1/public/stats — network-wide numbers: energy delivered, sessions, on-chain volume (public; powers the site you're reading).
  • GET /v1/impact — active devices, power sessions, regional breakdown (public).
05

⛓️Go on-chain if you want to

The settlement layer is public smart contracts on-chain — you can integrate at that level too:

  • PaymentRouter — payWithPermit() lets a user pay an order and split revenue in one transaction with a single EIP-2612 signature. This is exactly what the checkout's wallet panel calls.
  • ECandleRWA — the asset & split contract. Listen for YieldDeposited events to observe every settlement (gross + 50/40/10 legs) without touching our API at all.
  • Source published — contracts are verified on Sourcify (exact match); addresses and ABIs are in the portal.

Common questions

Is there a sandbox?
Yes — the full stack also runs against a test network with a mintable test USDC, so you can integrate end-to-end (including on-chain settlement) without real money. Ask in the portal for staging access.
What auth do the different endpoints need?
The payment flow (quote/order/status) and public reads are unauthenticated by design — they're what the customer checkout uses. Everything else takes your ek_ key, scoped to the developer role: you get what you need to build, and can't touch settlement internals or other tenants' data.
How real-time are webhooks vs polling?
Webhooks fire as soon as the platform confirms the event (payment confirmation is typically seconds, bounded by chain confirmation on wallet payments). Polling GET /v1/orders/:id at a few seconds' interval is a fine fallback — the checkout page itself works that way.
Where do I report a security issue?
Straight to ecandle@arkreen.com — please don't open a public issue for anything security-sensitive. We take disclosure seriously, especially while the contracts are pre-audit.

Build something that lights up.

Grab a key, wire up the three-call loop, and put real solar power behind your product.

Open the developer portal →