跳至正文
MZGrid

此页面仅提供英文版本。 以英文版本为准。

Overview & authentication

Base URLs, conventions for amounts and timestamps, wallet sign-in, API keys, provider request signing, errors and rate limits.

The MZGrid coordinator exposes a JSON REST API for browsing the marketplace, creating and managing jobs, and running provider agents. The TypeScript SDK wraps it; you can also call it directly from any language — see Using the API from Python.

Base URL

EnvironmentBase URL
Production (Base mainnet)https://api.mzgrid.io/v1
Local developmenthttp://localhost:8787/v1

All routes are under /v1. Requests and responses are JSON (Content-Type: application/json).

Conventions

  • Amounts are MZG as decimal strings with up to 6 decimals, for example "750.000000" or "116.25". Parse them with a decimal library rather than floating point. On-chain values are in wei (18 decimals) and appear only in fields whose names end in Wei.
  • Timestamps are ISO-8601 in UTC, for example "2026-11-04T09:12:44Z".
  • Addresses and hashes are 0x-prefixed hex strings.
  • Pagination uses opaque cursors: list endpoints that paginate return nextCursor, which you pass back as cursor. nextCursor is null on the last page.

Authentication

Public endpoints — catalogue, marketplace and network statistics — require no authentication. Customer endpoints require a bearer token. Provider endpoints require a signed provider header.

Wallet sign-in (session token)

Sign in with an Ethereum wallet using an EIP-191 personal_sign signature. Signing in requires accepting the Terms of Service, Privacy Policy and Risk Disclosure: you send the accepted version as termsVersion (a YYYY-MM-DD date; the current version is 2026-11-05).

1. Request a nonce

HTTP
POST /v1/auth/nonce
Content-Type: application/json

{ "address": "0x71C2…9aE4", "termsVersion": "2026-11-05" }

termsVersion is optional here. When you send it, the message to sign contains an extra acceptance statement, and /v1/auth/verify must then be called with the same termsVersion. A malformed value returns 400.

JSON
{
  "nonce": "b1f0c9e27a6d4e8390c1a2b3c4d5e6f7",
  "message": "api.mzgrid.io wants you to sign in to MZGrid with your wallet:\n0x71C2…9aE4\n\nSign in to the MZGrid coordinator. This request does not trigger a transaction or cost any MZG.\nI accept the MZGrid Terms of Service, Privacy Policy and Risk Disclosure (version 2026-11-05).\n\nURI: https://api.mzgrid.io\nVersion: 1\nChain ID: 8453\nNonce: b1f0c9e27a6d4e8390c1a2b3c4d5e6f7\nIssued At: 2026-11-05T09:10:02.000Z\nExpiration Time: 2026-11-05T09:15:02.000Z",
  "expiresAt": "2026-11-05T09:15:02.000Z"
}

2. Sign message with the wallet and verify

HTTP
POST /v1/auth/verify
Content-Type: application/json

{ "address": "0x71C2…9aE4", "signature": "0x2c7d…41b1c", "termsVersion": "2026-11-05" }

termsVersion is required. It must be well-formed, not older than the coordinator's current terms version, and equal to the version sent with the nonce (if any). Otherwise the response is 400 with code terms_not_accepted, and the nonce is not consumed — ask the user to accept the current terms and retry with the same signature or a new nonce.

JSON
{
  "token": "mzs_Q2xhdWRlIGlzIG5vdCBhIHRva2Vu…",
  "expiresAt": "2026-11-06T09:10:05.000Z",
  "address": "0x71C2…9aE4",
  "termsVersion": "2026-11-05"
}

The accepted version and time are recorded for the address and returned by GET /v1/account as termsVersion and termsAcceptedAt. Send the token on subsequent requests:

HTTP
Authorization: Bearer mzs_Q2xhdWRlIGlzIG5vdCBhIHRva2Vu…

API keys

For servers, scripts and CI, create a long-lived API key with a session token (see API keys). Keys start with mzg_live_ and are used the same way:

Shell
curl https://api.mzgrid.io/v1/account \
  -H "Authorization: Bearer $MZG_API_KEY"

An API key acts on behalf of the wallet that created it. It can create, read and stop jobs, but it cannot move funds: funding the escrow always requires a wallet signature.

Provider request signing

Provider agents authenticate every request with the X-MZG-Provider header:

文本
X-MZG-Provider: <address>:<unixTs>:<signature>

where signature is the EIP-191 personal_sign signature of the string mzgrid-provider:<unixTs> by the provider's registered key. Use the current Unix time in seconds; requests with timestamps far from the server clock are rejected. The mzgrid-provider agent does this automatically. See Provider endpoints.

Errors

Errors use standard HTTP status codes and a consistent body:

JSON
{
  "error": {
    "code": "deposit_exceeds_cap",
    "message": "Deposit 18000.000000 MZG exceeds this provider's job cap of 4025.000000 MZG; shorten the job or pick another provider"
  }
}
HTTPTypical codeMeaning
400invalid_requestThe body or query failed validation. message names the field.
400terms_not_acceptedtermsVersion is missing, malformed, older than the current Terms of Service version, or differs from the version in the sign-in nonce. Returned by /auth/verify, /providers/register and /providers/terms.
401unauthorizedMissing, expired or invalid token, key or provider signature.
403forbiddenAuthenticated, but not allowed to access this resource (for example another customer's job).
404not_foundThe job, offer or key does not exist.
409conflictThe action is not valid in the resource's current state, e.g. stopping a completed job.
422deposit_exceeds_cap, offer_unavailable, insufficient_vramThe request is well-formed but cannot be fulfilled.
429rate_limitedToo many requests. Retry after the number of seconds in Retry-After.
500internalUnexpected server error. Safe to retry idempotent requests with backoff.
503unavailableTemporarily unavailable, for example while the chain indexer catches up.

A terms_not_accepted error carries the required version in details:

JSON
{
  "error": {
    "code": "terms_not_accepted",
    "message": "You must accept the current Terms of Service (version 2026-11-05) to sign in (termsVersion is missing)",
    "details": { "requiredVersion": "2026-11-05", "receivedVersion": null, "termsUrl": "https://mzgrid.io/legal/terms" }
  }
}

Rate limits

Requests are limited to 600 per minute per API key (or per IP address for unauthenticated public requests). Responses that exceed the limit return 429 with a Retry-After header. If you poll job status, prefer jobs.waitForEndpoint() in the SDK or poll no more than once every few seconds.

Endpoint index

GroupEndpoints
Public/health, /catalog/*, /market/offers, /network/*
Jobs & account/jobs, /jobs/:id, /jobs/:id/funded, /jobs/:id/logs, /jobs/:id/stop, /account
API keys/keys, /keys/:id
Providers/providers/*