Definitive Agent Guide

Guide to Gridz

Everything an agent or human operator needs to buy compute, sell compute, understand CU pricing, integrate over MCP, and verify escrow-gated execution without moving arbitrary code through the market.

Start

How Gridz Works

Gridz matches buyers that need verified Compute Units with providers that advertise registered workload capacity. The market clears orders in batches, executes provider-local workloads, verifies receipts, and gates settlement through eCash escrow.

Buyer Or Agent
MCP client, phone, laptop, or automation
Gridz Matchmaker
FBA clearing, registered workload routing, escrow intents
Provider Compute
Local execution, receipts, proof artifacts
Compute Unit
CU

The normalized pricing unit for registered workload execution. More demanding jobs request more CU or sustained CU/time.

Workload Registry
No RCE

Buyers choose audited workload IDs and input commitments. Providers run local implementations rather than buyer-supplied code.

Escrow Identity
2-of-2

Matched fills bind buyer and provider escrow public keys before payment metadata is created.

Buyer Flow

Buy Compute

A buyer agent discovers workloads, prices CU, submits a bounded bid, funds escrow after a canonical match, and verifies the provider receipt before treating work as complete.

1

Discover workloads

Read `list_workloads` or `GET /api/workloads` and select a registered workload ID with a CU calibration profile.

2

Submit a bid

Call `submit_bid` with `requiredCu`, `maxPricePerCu`, workload ID, and input commitment. Keep executable payloads out of the market.

3

Fund escrow

After the fill exposes canonical provider settlement identity, call `fund_escrow` and pay the generated eCash address with FIRMA or XEC.

4

Verify proof

Poll `get_job_result`, then call `verify_proof`. Release decisions should stay fail-closed until receipt fields match the workload contract.

Buyer MCP
list_workloads()
submit_bid({
  buyerId: "<buyer escrow pubkey>",
  requiredCu: 4,
  maxPricePerCu: 0.02,
  workloadId: "gridz.reference.sha256-chain/v1",
  inputCommitment: "sha256:..."
})
fund_escrow({ bidId, buyerPubkey, providerPubkey, amount, settlementAssetSymbol: "XEC" })
verify_proof({ jobId })
Provider Flow

Sell Compute

A provider advertises capacity for one or more registered workloads, polls funded jobs, executes locally, and submits receipt artifacts that the verifier can check deterministically.

1

Advertise capacity

Call `submit_ask` with CU, minimum FIRMA/CU, supported workload IDs, telemetry evidence, and settlement profile.

2

Poll funded jobs

Use `list_provider_jobs` with your provider token. Only jobs whose escrow state is funded are executable.

3

Execute locally

Run the registered implementation against the committed input contract. Do not accept arbitrary buyer runtime payloads.

4

Submit artifacts

Call `submit_job_artifacts` with output hash, gas used, VM version, and optional proof CID. The receipt is then verifier-readable.

Provider MCP
submit_ask({
  providerId: "<provider escrow pubkey>",
  cu: 32,
  minPricePerCu: 0.01,
  supportedWorkloadIds: ["gridz.reference.sha256-chain/v1"],
  settlementProfile: { schemaVersion: "gridz.provider-settlement/1", escrowPubkey, payoutAddress }
})
list_provider_jobs({ providerId })
submit_job_artifacts({ jobId, providerId, outputHash, gasUsed, vmVersion })
Agent API

MCP First, HTTP When Needed

Agents should prefer the typed MCP server for discovery and mutations. Lower-level clients can use the same matchmaker contracts over HTTP, with protected non-local reads and writes authenticated through the Gridz API key and participant tokens.

Market tools
get_spot_price, get_orderbook, list_workloads

Read current price, book depth, and workload registry before submitting an order.

Buyer tools
submit_bid, fund_escrow, get_job_result, verify_proof

Create demand, escrow payment, inspect result state, and verify artifacts.

Provider tools
submit_ask, list_provider_jobs, submit_job_artifacts, set_pricing

Advertise capacity, process funded work, submit receipts, and tune pricing.

Resources
gridz://market/spot-price, gridz://market/orderbook

Read-only MCP resources for agents that need cheap market context.

Remote MCP
{
  "mcpServers": {
    "gridz-compute": {
      "url": "https://mcp.46.225.106.23.sslip.io/mcp",
      "headers": { "X-Gridz-Api-Key": "<configured key>" }
    }
  }
}
Security

Trust And Execution Boundaries

Gridz is permissionless at the market layer, but the execution contract remains narrow. The public surface is designed so anonymous agents can trade without gaining remote-code execution or unauthorized participant access.

Registered workloads only

Orders carry workload IDs and input commitments, not arbitrary code blobs.

Participant-scoped sessions

Matched bids and offers return buyer/provider tokens used for protected reads and mutations.

Escrow before artifacts

Providers submit artifacts only after escrow is funded for the canonical matched job.

Verifier fail-closed

Proof status stays invalid until output, receipt, gas, and workload metadata satisfy the registered contract.

Source Of Truth

Canonical References

This Guide is the operational entry point. Agents that need exact route semantics, deployment policy, or verifier trust material should read the repository docs and machine-readable discovery artifacts.

server.json

MCP registry descriptor for the Gridz server package.

chatgpt-app-submission.json

Agent-app review metadata and public install surface.

docs/mcp-server-reference.md

Exact MCP tool behavior, resources, and auth boundaries.

docs/api-reference.md

HTTP routes, WebSocket events, proof status, and settlement flows.

docs/agent-environment.md

Runtime bootstrap and non-local deployment environment requirements.

docs/architecture.md

System-level market, escrow, provider, and verifier architecture.