본문으로 건너뛰기
MZGrid

이 페이지는 영어로만 제공됩니다. 영어 버전이 정본으로서 효력을 가집니다.

Using the API from Python

Call the MZGrid REST API from Python with requests, fund jobs with web3.py, and use the job's endpoint with the openai client.

There is no separate Python SDK: the REST API is small and maps cleanly onto requests. This page shows a complete flow — sign in, create a job, fund it, wait for the endpoint, call it with the openai package and stop it.

Shell
pip install requests openai web3 eth-account

Client setup

Python
import os
import time
import requests

API = os.environ.get("MZG_API_URL", "https://api.mzgrid.io/v1")
session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['MZG_API_KEY']}"


def call(method: str, path: str, **kwargs):
    r = session.request(method, f"{API}{path}", timeout=60, **kwargs)
    if r.status_code >= 400:
        err = r.json().get("error", {})
        raise RuntimeError(f"{r.status_code} {err.get('code')}: {err.get('message')}")
    return r.json() if r.content else None

Signing in with a wallet (optional)

If you do not have an API key yet, obtain a session token with eth-account, then create a key:

Python
from eth_account import Account
from eth_account.messages import encode_defunct

acct = Account.from_key(os.environ["WALLET_PRIVATE_KEY"])
nonce = requests.post(f"{API}/auth/nonce", json={"address": acct.address}).json()
signed = acct.sign_message(encode_defunct(text=nonce["message"]))
auth = requests.post(
    f"{API}/auth/verify",
    json={"address": acct.address, "signature": signed.signature.hex()},
).json()

key = requests.post(
    f"{API}/keys",
    json={"name": "python-scripts"},
    headers={"Authorization": f"Bearer {auth['token']}"},
).json()
print("store this key securely:", key["key"])

Browse offers

Python
offers = call("GET", "/market/offers", params={
    "sku": "rtx4090", "minReliability": 95, "sort": "price", "limit": 5,
})["items"]
for o in offers:
    print(o["id"], o["provider"]["name"], o["region"]["code"], o["pricePerHour"], "MZG/h")

Create a job

Python
created = call("POST", "/jobs", json={
    "offerId": offers[0]["id"],
    "template": "llama-3.1-8b",
    "maxDurationHours": 2,
    "config": {"env": {"HF_TOKEN": os.environ["HF_TOKEN"]}},
})
job, escrow = created["job"], created["escrow"]
print("deposit", job["deposit"], "MZG")

Fund the escrow with web3.py

This uses the approve + createJob path. MZG_TOKEN_ADDRESS is the MZG token address for your chain from Smart contracts; the escrow address comes from the API response. Load the ABIs from the published contract source or the @mzgrid/sdk package.

Python
import json
from web3 import Web3

w3 = Web3(Web3.HTTPProvider(os.environ.get("BASE_RPC_URL", "https://mainnet.base.org")))
acct = w3.eth.account.from_key(os.environ["WALLET_PRIVATE_KEY"])

token = w3.eth.contract(address=os.environ["MZG_TOKEN_ADDRESS"], abi=json.load(open("abi/MZGToken.json")))
escrow_c = w3.eth.contract(address=escrow["contract"], abi=json.load(open("abi/MZGridEscrow.json")))


def send(fn):
    tx = fn.build_transaction({"from": acct.address, "nonce": w3.eth.get_transaction_count(acct.address)})
    signed = acct.sign_transaction(tx)
    tx_hash = w3.eth.send_raw_transaction(signed.raw_transaction)
    w3.eth.wait_for_transaction_receipt(tx_hash)
    return tx_hash


send(token.functions.approve(escrow["contract"], int(escrow["depositWei"])))
fund_tx = send(escrow_c.functions.createJob(
    escrow["jobIdBytes32"],
    escrow["provider"],
    int(escrow["pricePerHourWei"]),
    escrow["maxDurationS"],
    escrow["specHash"],
))
call("POST", f"/jobs/{job['id']}/funded", json={"txHash": "0x" + fund_tx.hex().removeprefix("0x")})

You can also fund the job from the dashboard and continue in Python from the next step.

Wait for the endpoint

Python
deadline = time.time() + 15 * 60
while True:
    job = call("GET", f"/jobs/{job['id']}")
    if job["status"] == "running" and job.get("endpointUrl"):
        break
    if job["status"] in ("failed", "cancelled", "reclaimed"):
        raise RuntimeError(f"job ended with status {job['status']}")
    if time.time() > deadline:
        raise TimeoutError("endpoint not ready after 15 minutes")
    time.sleep(5)

print("endpoint:", job["endpointUrl"])

Call the endpoint with the openai client

vLLM templates expose an OpenAI-compatible API under /v1 on the job's endpointUrl:

Python
from openai import OpenAI

llm = OpenAI(base_url=f"{job['endpointUrl']}/v1", api_key="unused")

resp = llm.chat.completions.create(
    model="meta-llama/Llama-3.1-8B-Instruct",
    messages=[
        {"role": "system", "content": "You are a concise assistant."},
        {"role": "user", "content": "Summarise what an escrow does in two sentences."},
    ],
    max_tokens=200,
)
print(resp.choices[0].message.content)

# Streaming
stream = llm.chat.completions.create(
    model="meta-llama/Llama-3.1-8B-Instruct",
    messages=[{"role": "user", "content": "Count from 1 to 5."}],
    stream=True,
)
for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="", flush=True)

If you started the job with config.env.VLLM_API_KEY, vLLM requires that key: pass it as api_key instead of "unused".

Read logs and stop

Python
for line in call("GET", f"/jobs/{job['id']}/logs")["lines"][-20:]:
    print(line["t"], line["stream"], line["text"])

stopped = call("POST", f"/jobs/{job['id']}/stop")
print(stopped["status"], stopped.get("charged"), stopped.get("refund"))