# Kyun — Full API Guide for Agents

> Complete autonomous-operation reference for the Kyun v2 API.

This document mirrors the OpenAPI v2 description at https://api.kyun.sh/endpoints/v2/json but is written as a linear agent walkthrough.

## Identity model

- Account balance is denominated in EUR cents (integer minor units).
- Session tokens last 7 days. For long-lived automation, create an API key via the account routes.
- The `x-auth-token` header carries either a session token or an API key.

## Proof-of-work

GET /v2/etc/pow returns { challenge, signature, difficulty }. Find a string `proof` such that SHA-256(challenge + proof) hex starts with `difficulty` zero characters. Use node or python (not bash) — difficulty 5 needs ~1M iterations. Challenges expire in 2 minutes and are single-use. Submit { challenge, signature, proof } as `pow` in PUT /v2/account.

## Deposits & funding

- IMPORTANT ordering: create a draft order first (PUT /v2/services/danbo), then GET /v2/orders/{orderId} to obtain chargeNowMinor (EUR cents), THEN create a deposit of exactly that amount. POST /v2/deposits { amount: chargeNowMinor / 100, currency: "eur" } creates a deposit with a Monero address and the exact `xmr` amount to send (1 XMR = 1e12 atomic units).
- GET /v2/deposits/rates returns { eur, usd } — the EUR and USD value of 1 XMR.
- Send the exact quoted XMR to the deposit address. Monero JSON-RPC (check env for KYUN_WALLET_RPC, default http://$KYUN_LOCAL_IP:28083/json_rpc, and KYUN_MONEROD_RPC, default http://$KYUN_LOCAL_IP:28081/json_rpc). The envelope is `{"jsonrpc":"2.0","id":"0","method":METHOD,"params":{...}}` — the key is `params` (not `args`) and all arguments go inside `params`, never at the JSON root. Steps: (a) get_address {"account_index":0} → wallet address; (b) refresh {}; (c) get_balance {"account_index":0} → unlocked_balance in atomic units (1 XMR = 1e12); (d) if unlocked < required, mine via monerod generateblocks {"wallet_address":YOUR_ADDRESS,"amount_of_blocks":80}; (e) refresh again; (f) transfer {"destinations":[{"amount":ATOMIC,"address":DEPOSIT_ADDRESS}],"account_index":0,"priority":1,"get_tx_key":true}; (g) generateblocks {"wallet_address":YOUR_ADDRESS,"amount_of_blocks":1} then refresh to finalize. Balance is credited on mempool detection (receivedAll=true) and locked after confirmations.
- GET /v2/deposits/{id}/status returns { receivedAll, received, confirmations }.
- A deposit bonus may apply (check billing.depositBonusPercent), so the credited EUR-cents balance can exceed the raw conversion.

## Pricing

GET /v2/datacenters/{datacenterId}/unitPrices returns the monthly price factors in EUR cents:
- coreMonthlyPrice * cores
- computeDiskTbMonthlyPrice * diskGB / 1000
- ramGiBMonthlyPrice * ramGiB
- ipv4MonthlyPrice * ipv4Count
Sum these for the Danbo monthly recurring price. The offer endpoint returns the validated selection and limits. Sales can discount these.

## Orders

- PUT /v2/services/danbo { idempotencyKey, datacenterId, specs, ipv4Count } → order ref { kind: "order", id }. GET /v2/orders/{orderId} → draft order with chargeNowMinor and newRecurringPriceMinor.
- POST /v2/orders/{orderId}/confirm → charges balance and provisions the resource.
- GET /v2/orders/{orderId} → poll status: draft → processing → completed | failed.
- The completed order resourceRef gives the new service id.

## OS installation (cloud-init)

- GET /v2/datacenters/{datacenterId}/osCatalog → distros[] with versions[] including resolved imageUrl and checksum.
- POST /v2/services/danbo/{danboId}/cloudInit { imageUrl, osName, checksum } → 202 task ref. checksum is the { type, sum } object from the catalog (pass it through unchanged).
- Monitor: GET /v2/services/danbo/{danboId}/tasks/{taskId} or SSE stream.
- Retry: POST /v2/services/danbo/{danboId}/tasks/{taskId}/retry.

## Serial console

- POST /v2/services/danbo/{danboId}/serial/ticket → { ticket, expiresAt }.
- Open WebSocket: wss://<host>/v2/services/danbo/{danboId}/serial?ticket=<ticket>.
- Send text frames to execute commands; receive text frames as output.

## Failure handling

If a provisioning step fails and cannot be self-recovered, create a support chat: POST /v2/chats { ultraPrivateMode: true } and describe the issue for staff.