Chuyển đến nội dung
MZGrid

Trang này chỉ có bằng tiếng Anh. Phiên bản tiếng Anh là bản có giá trị chính thức.

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:

Văn bản
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.