이 페이지는 영어로만 제공됩니다. 영어 버전이 정본으로서 효력을 가집니다.
Provider endpoints
Endpoints used by the provider agent: registration, benchmarks, heartbeats, job polling, status, usage, completion, account and pricing.
These endpoints are used by the mzgrid-provider agent. You only need to call them directly if you are building your own agent or tooling. Every request must carry the signed provider header:
X-MZG-Provider: <address>:<unixTs>:<signature of "mzgrid-provider:<unixTs>">See Overview & authentication for details. The address must be registered on-chain in the ProviderRegistry before it can receive jobs.
POST /v1/providers/register
Registers machines and pricing with the coordinator. Call after register(metadataURI) on-chain. termsVersion is required: the Terms of Service version the provider accepted (YYYY-MM-DD, currently 2026-11-05). If it is missing, malformed or older than the current version, the request fails with 400 terms_not_accepted and nothing is registered. The mzgrid-provider agent sends it once you accept the terms (--accept-terms).
{
"name": "kestrel-compute",
"region": "eu-central",
"machines": [
{
"machineId": "m-fra-01",
"gpus": [
{ "sku": "h100-sxm", "uuid": "GPU-1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "vramGb": 80, "driver": "560.35.03" },
{ "sku": "h100-sxm", "uuid": "GPU-6f5e4d3c-2b1a-4c9d-8e7f-5a4b3c2d1e0f", "vramGb": 80, "driver": "560.35.03" }
],
"cpuCores": 112,
"ramGb": 1024,
"diskGb": 7680,
"bandwidthMbps": 10000
}
],
"pricing": { "h100-sxm": "745" },
"termsVersion": "2026-11-05"
}The response describes the provider, its machines and offers, and echoes the recorded acceptance:
{
"address": "0x8b3f…2e41",
"name": "kestrel-compute",
"tier": "datacenter",
"status": "active",
"region": "eu-central",
"locked": "0.000000",
"machines": [
{ "machineId": "m-fra-01", "verified": false, "status": "unverified", "offers": [{ "id": "off_3k9d2m1x", "sku": "h100-sxm", "gpuCount": 2, "pricePerHour": "745.000000" }] }
],
"benchmarkRequired": true,
"termsVersion": "2026-11-05",
"termsAcceptedAt": "2026-11-05T09:02:11.000Z"
}POST /v1/providers/terms
Records Terms of Service acceptance for the signing provider wallet — used by the provider dashboard. Works before the wallet is registered (no 404); if a provider is registered for the address, its record is updated too. The acceptance is stored with the same per-address record as wallet sign-in, so GET /v1/account reflects it.
{ "termsVersion": "2026-11-05" }{ "termsVersion": "2026-11-05", "acceptedAt": "2026-11-05T09:01:44.000Z" }Missing, malformed or outdated termsVersion → 400 terms_not_accepted.
POST /v1/providers/benchmark
Submits benchmark results for a machine. Each GPU must measure within 70–115% of its SKU's FP16 reference to be verified. signature is the provider key's signature over the results.
{
"machineId": "m-fra-01",
"results": [
{ "gpuUuid": "GPU-1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "tflopsFp16": 962.4, "memBandwidthGBs": 3012.6, "durationMs": 38804 },
{ "gpuUuid": "GPU-6f5e4d3c-2b1a-4c9d-8e7f-5a4b3c2d1e0f", "tflopsFp16": 958.1, "memBandwidthGBs": 3008.9, "durationMs": 38911 }
],
"signature": "0x9a1f…c41b"
}POST /v1/providers/heartbeat
Sent every 30 seconds per machine. Feeds uptime and the live dashboard.
{
"machineId": "m-fra-01",
"gpus": [
{ "uuid": "GPU-1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "utilization": 94, "memUsedMb": 74210, "tempC": 66 },
{ "uuid": "GPU-6f5e4d3c-2b1a-4c9d-8e7f-5a4b3c2d1e0f", "utilization": 0, "memUsedMb": 0, "tempC": 34 }
],
"runningJobs": ["job_7f3a9c2d41"]
}GET /v1/providers/jobs/next
Long-polls for the next job for a machine, holding the request open for up to 25 seconds. Returns { "job": null } if nothing arrives.
GET /v1/providers/jobs/next?machineId=m-fra-01{
"job": {
"id": "job_7f3a9c2d41",
"jobIdBytes32": "0x6a0f…c93e",
"status": "funded",
"template": "llama-3.3-70b",
"sku": "h100-sxm",
"gpuName": "NVIDIA H100 SXM",
"provider": "0x8b3f…2e41",
"region": "eu-central",
"pricePerHour": "745.000000",
"maxDurationHours": 4,
"deposit": "2980.000000",
"createdAt": "2026-11-04T09:10:31Z",
"txs": { "fund": "0x5c1e…9b07" }
}
}After receiving a job, the agent must call acceptJob(jobIdBytes32) on the escrow within 10 minutes of funding.
POST /v1/providers/jobs/:id/accepted
Reports the acceptJob transaction.
{ "txHash": "0xe4a2…7f10" }POST /v1/providers/jobs/:id/status
Reports container progress. endpointUrl is set once the service is reachable; log carries log lines to append to the job log.
{
"state": "running",
"endpointUrl": "http://198.51.100.23:41877",
"log": ["INFO: Uvicorn running on http://0.0.0.0:8000"]
}state is pulling, starting or running.
POST /v1/providers/jobs/:id/usage
Sent every 60 seconds while a job runs. Utilisation samples must be no more than 90 seconds apart; a gap of more than 10 minutes fails the job and triggers an OfflineDuringJob slash.
{
"gpuSeconds": 60,
"samples": [
{ "t": "2026-11-04T09:20:00Z", "util": 91 },
{ "t": "2026-11-04T09:20:30Z", "util": 96 },
{ "t": "2026-11-04T09:21:00Z", "util": 93 }
]
}POST /v1/providers/jobs/:id/finished
Reports that the container exited. The coordinator then settles on-chain with completeJob(jobId, usedSeconds, resultHash).
{ "exitCode": 0, "resultHash": "0x4e19…a07d" }GET /v1/providers/me
{
"address": "0x8b3f…2e41",
"name": "kestrel-compute",
"status": "Active",
"locked": "92260.660000",
"liquidEarned30d": "509705.120000",
"reliability": 98,
"termsVersion": "2026-11-05",
"termsAcceptedAt": "2026-11-05T09:02:11.000Z",
"machines": [
{ "machineId": "m-fra-01", "gpus": 8, "sku": "h100-sxm", "verified": true, "online": true, "runningJobs": 5 }
]
}status mirrors the registry: Active, Exiting or Exited. While Exiting, exitUnlockAt gives the time after which withdrawLocked() can succeed.
PUT /v1/providers/pricing
Sets prices per SKU in MZG per GPU-hour. Applies to jobs created after the change.
{ "h100-sxm": "755", "a100-80": "470" }Returns the full pricing map. See Pricing.