Provider gateway API

Every provider node exposes a small HTTP API that renters use to run workloads. The Kiln website calls it through a relay at /api/gateway/<listing>/…, but you can call a gateway directly too.

The base URL is the listing's host, for example http://203.0.113.7:8443.

Authentication

Only the wallet that opened a lease can act on it.

1. Sign the session message with the renter wallet (ed25519, as wallets' signMessage does). The text must match exactly, with \n newlines:

Kiln session
lease: <lease address>
provider: <listing address>
issued: <unix seconds>

2. Exchange it for a token:

POST /v1/leases/{lease}/session
Content-Type: application/json

{ "issued": 1792425600, "signature": "<base58 signature>" }

{ "token": "<lease>.<expiry>.<mac>", "expires": 1792432800 }

The gateway reads the lease from Solana and checks that it belongs to this listing, hasn't ended, and that the signature is from its renter. issued must be within the last five minutes. The token is valid until the lease ends, but only for that lease.

3. Send the token as Authorization: Bearer <token> on every other call.

Endpoints

GET /v1/info

Public.

{ "provider": "4VkU…oCnn", "gpu": "1x RTX 4090", "busy": false, "version": 1 }

POST /v1/leases/{lease}/deploy

{
  "image": "quay.io/jupyter/pytorch-notebook:cuda12-latest",
  "command": [],
  "env": { "JUPYTER_TOKEN": "…" },
  "ports": [8888]
}
Field Rules
image Valid Docker reference, max 255 characters
command Up to 32 arguments, 1 KB each
env Up to 64 variables; names [A-Za-z_][A-Za-z0-9_]*
ports Up to 8 distinct container ports to expose

Response:

{ "state": "pulling", "endpoints": [{ "containerPort": 8888, "hostPort": 30100, "host": "203.0.113.7" }] }

Deploying again replaces the lease's current container. Returns 409 if another lease's workload is using the machine.

GET /v1/leases/{lease}/status

{
  "status": { "state": "running", "image": "…", "endpoints": [ … ], "exitCode": 0, "error": "" },
  "leaseEndsAt": 1792432800,
  "verifiedSeconds": 1260,
  "lastHeartbeat": 1792426860
}

state is one of none, pulling, starting, running, exited or failed.

GET /v1/leases/{lease}/logs?tail=300

Returns the last tail lines (1–5,000) of container output: { "logs": "…" }.

POST /v1/leases/{lease}/stop

Removes the container. Heartbeats, and payment, stop until you deploy again.

Errors

Errors are JSON: { "error": "message" }.

Status Meaning
400 Malformed request or invalid spec
401 Bad or expired signature or token
404 Lease belongs to another provider
409 Machine busy with another lease, or a deploy is already in progress
410 Lease closed or ended
503 No free ports on the provider
Previous← Solana programNextGlossary →