Esta página está disponível apenas em inglês. A versão em inglês é a que prevalece.
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
| Environment | Base URL |
|---|---|
| Production (Base mainnet) | https://api.mzgrid.io/v1 |
| Local development | http://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 inWei. - 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 ascursor.nextCursorisnullon 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
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.
{
"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
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.
{
"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:
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:
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:
{
"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"
}
}| HTTP | Typical code | Meaning |
|---|---|---|
| 400 | invalid_request | The body or query failed validation. message names the field. |
| 400 | terms_not_accepted | termsVersion 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. |
| 401 | unauthorized | Missing, expired or invalid token, key or provider signature. |
| 403 | forbidden | Authenticated, but not allowed to access this resource (for example another customer's job). |
| 404 | not_found | The job, offer or key does not exist. |
| 409 | conflict | The action is not valid in the resource's current state, e.g. stopping a completed job. |
| 422 | deposit_exceeds_cap, offer_unavailable, insufficient_vram | The request is well-formed but cannot be fulfilled. |
| 429 | rate_limited | Too many requests. Retry after the number of seconds in Retry-After. |
| 500 | internal | Unexpected server error. Safe to retry idempotent requests with backoff. |
| 503 | unavailable | Temporarily unavailable, for example while the chain indexer catches up. |
A terms_not_accepted error carries the required version in details:
{
"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
| Group | Endpoints |
|---|---|
| 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/* |