本文へスキップ
MZGrid

このページは英語版のみご利用いただけます。 英語版が正式な内容となります。

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).

JSON
{
  "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:

JSON
{
  "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.

JSON
{ "termsVersion": "2026-11-05" }
JSON
{ "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.

JSON
{
  "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.

JSON
{
  "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.

HTTP
GET /v1/providers/jobs/next?machineId=m-fra-01
JSON
{
  "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.

JSON
{ "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.

JSON
{
  "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.

JSON
{
  "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).

JSON
{ "exitCode": 0, "resultHash": "0x4e19…a07d" }

GET /v1/providers/me

JSON
{
  "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.

JSON
{ "h100-sxm": "755", "a100-80": "470" }

Returns the full pricing map. See Pricing.