Cloud API

The cloud API connects the local Eliza agent to Eliza Cloud for cloud-hosted inference, credits, and remote agent management. Login uses a browser-based OAuth-style flow with polling for session completion.

Billing is now expected to stay inside the app whenever Eliza Cloud exposes the required billing endpoints. The topUpUrl values returned by /api/cloud/status and /api/cloud/credits should be treated as a hosted fallback, not the primary UX.

Endpoints

POST /api/cloud/login

Start the Eliza Cloud login flow. Creates a session on the cloud and returns a browser URL for the user to authenticate. Poll GET /api/cloud/login/status with the returned sessionId to check completion.

Response

{
  "ok": true,
  "sessionId": "550e8400-e29b-41d4-a716-446655440000",
  "browserUrl": "https://www.elizacloud.ai/auth/cli-login?session=550e8400-e29b-41d4-a716-446655440000"
}

GET /api/cloud/login/status

Poll the status of a login session. When status is "authenticated", the API key is automatically saved to config and applied to the process environment.

When the cloud wallet feature is enabled (ENABLE_CLOUD_WALLET=1), a successful login also triggers best-effort cloud wallet provisioning. The agent attempts to import EVM and Solana wallets from Eliza Cloud and set them as the primary wallet source. If provisioning fails, the login still succeeds — the API key is saved, and the wallet provisioning failure is logged without affecting the authentication response. You can manually retry wallet provisioning later using POST /api/wallet/refresh-cloud.

Query Parameters

Response (pending)

{
  "status": "pending"
}

Response (authenticated)

{
  "status": "authenticated",
  "keyPrefix": "eca-..."
}

Possible status values

GET /api/cloud/status

Get cloud connection status, authentication state, and billing URL.

Response (connected)

{
  "connected": true,
  "enabled": true,
  "hasApiKey": true,
  "userId": "user-123",
  "organizationId": "org-456",
  "topUpUrl": "https://elizacloud.ai/dashboard/settings?tab=billing"
}

Response (not connected)

{
  "connected": false,
  "enabled": true,
  "hasApiKey": false,
  "userId": null,
  "organizationId": null,
  "topUpUrl": "https://elizacloud.ai"
}

GET /api/cloud/credits

Get the cloud credit balance. Returns null balance when not connected.

Response

{
  "connected": true,
  "balance": 15.50,
  "low": false,
  "critical": false,
  "topUpUrl": "https://elizacloud.ai/dashboard/settings?tab=billing"
}

Billing proxy endpoints

These endpoints proxy authenticated Eliza Cloud billing APIs through the local Eliza backend so the desktop app can keep billing, payment methods, and top-ups in-app. They require an active Eliza Cloud login because the local server forwards the saved cloud API key.

Use topUpUrl only as a hosted fallback if Eliza Cloud does not return an embedded checkout or crypto quote flow the app can render directly.

GET /api/cloud/billing/summary

Get the current Eliza Cloud billing summary.

Typical response

{
  "balance": 15.5,
  "currency": "USD",
  "embeddedCheckoutEnabled": false,
  "hostedCheckoutEnabled": true,
  "cryptoEnabled": true
}

GET /api/cloud/billing/payment-methods

List saved payment methods for the authenticated Eliza Cloud account.

GET /api/cloud/billing/history

List recent billing activity, including top-ups and settlement history.

POST /api/cloud/billing/checkout

Create a billing checkout session.

Request

{
  "amountUsd": 25,
  "mode": "hosted"
}

Typical response

{
  "provider": "stripe",
  "mode": "hosted",
  "checkoutUrl": "https://checkout.stripe.com/c/pay/cs_xxx...",
  "sessionId": "cs_xxx..."
}

Eliza prefers embedded checkout when Eliza Cloud supports it, but the current cloud billing integration can still return a hosted checkout URL.

POST /api/cloud/billing/crypto/quote

Request a crypto invoice or quote for a credit top-up.

Request

{
  "amountUsd": 25,
  "walletAddress": "0xabc123..."
}

Typical response

{
  "provider": "oxapay",
  "network": "BEP20",
  "currency": "USDC",
  "amount": "25.000",
  "amountUsd": 25,
  "paymentLinkUrl": "https://pay.example.com/track_123",
  "expiresAt": "2026-03-15T01:00:00.000Z"
}

POST /api/cloud/disconnect

Disconnect from Eliza Cloud. Clears the API key from config, process environment, and agent database record.

Response

{
  "ok": true,
  "status": "disconnected"
}

GET /api/cloud/agents

List cloud agents. Requires an active cloud connection.

Response

{
  "ok": true,
  "agents": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "My Cloud Agent",
      "status": "running",
      "createdAt": "2024-06-10T12:00:00Z"
    }
  ]
}

POST /api/cloud/agents

Create a new cloud agent. Requires an active cloud connection.

Request

{
  "agentName": "My Cloud Agent",
  "agentConfig": { "character": "eliza" },
  "environmentVars": { "OPENAI_API_KEY": "<OPENAI_API_KEY>" }
}

Response (201 Created)

{
  "ok": true,
  "agent": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "My Cloud Agent",
    "status": "provisioning"
  }
}

POST /api/cloud/agents/:id/provision

Provision a cloud agent — connect the local agent to the cloud agent instance.

Path Parameters

Response

{
  "ok": true,
  "agentId": "550e8400-e29b-41d4-a716-446655440000",
  "agentName": "My Cloud Agent",
  "status": { "connected": true }
}

POST /api/cloud/agents/:id/shutdown

Shutdown and delete a cloud agent.

Path Parameters

Response

{
  "ok": true,
  "agentId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "stopped"
}

POST /api/cloud/agents/:id/connect

Connect to an existing cloud agent (disconnecting from any currently active agent first).

Path Parameters

Response

{
  "ok": true,
  "agentId": "550e8400-e29b-41d4-a716-446655440000",
  "agentName": "My Cloud Agent",
  "status": { "connected": true }
}