Provider API

Routes under /evm/*. The read routes are public and used by clients too; the write routes relay provider-signed messages. Encoding, headers, paging and body limits are in API conventions; the error envelope and retry rule are in Errors.

DeploymentCopy Anchor Link

GET /evm/chainCopy Anchor Link

The deployment parameters a client or provider needs to sign.

Auth: public · Index-backed: no (reads the chain)

Response 200

{
  "chain_id": 84532,
  "contracts": {
    "job_registry": "0x…",
    "provider_registry": "0x…",
    "ask_registry": "0x…",
    "usdc": "0x…"
  },
  "decimals": 6,
  "token_domain": { "name": "…", "version": "…" },
  "gas_price": "1000000",
  "head_block": "12345678",
  "block_time_ms": 2000,
  "fee_bps": 100
}

Errors: 503 chain_unreachable or relay_unavailable (config_read).

Job bookCopy Anchor Link

GET /evm/jobsCopy Anchor Link

The job book, filtered. With free=N it is also the provider's poll.

Auth: public; a provider session with free · Index-backed: yes · Paged: yes

Response 200

{
  "jobs": [
    {
      "job_id": "0x…", "owner": "0x…", "c": "0x…",
      "model_id": "3", "sla_secs": "3600", "designated": "0",
      "rate_in": "1500", "rate_out": "6000", "units_in": "1200", "units_out": "800",
      "expires_at": "1786003600", "state": 0, "ended_because": 0,
      "provider_id": "0", "claimed_at": "0", "completion_tok": "0",
      "task_cid": "bafy…", "result_cid": null, "posted_block": "12345600"
    }
  ],
  "as_of_block": "12345672"
}

state and ended_because are as in Job lifecycle; an open job past expires_at reads as 3 / 5. provider_id, claimed_at and completion_tok are "0" until claimed or settled.

Provider poll. With free=N (0–4294967295), the request needs a provider session, state=Open and a model in the catalog. The node records the provider as live for that model with N free slots, leases it up to N of the oldest matching jobs it may claim (open bids, or designated to it) for MATCH_LEASE_MS, counting leases it already holds, and returns only the jobs it holds. See Matching and leases. Without free, the session is ignored.

On a coordinator whose escrow has lost keys, open undesignated jobs posted before its current key custody are left out of the book.

Errors

curl -s "https://api.vorq.co/evm/jobs?state=Open&model=3&free=4" \
  -H "authorization: Bearer $TOKEN"

GET /evm/jobs/summaryCopy Anchor Link

Totals for one owner, overall and per model.

Auth: public · Index-backed: yes

Response 200

{
  "jobs": "12", "completed": "10", "priced": "12", "escrowed": "91000",
  "by_model": [{ "model_id": "3", "jobs": "12", "completed": "10", "priced": "12", "escrowed": "91000" }],
  "as_of_block": "12345672"
}

GET /evm/jobs/{job_id}Copy Anchor Link

One job in the book's shape, plus as_of_block.

Auth: public · Index-backed: yes

Errors: 400 for a malformed id; 404 for an unknown job.

Provider operationsCopy Anchor Link

POST /evm/opsCopy Anchor Link

Relay one signed provider op. The coordinator verifies the signature, simulates the transaction, sends it and waits for the receipt.

Auth: session (any address; the op signature is the authority) · Index-backed: no · Body limit: 20 MiB

Request: a flat object with op, signature (the provider wallet's signature over the op's signed message) and the op's fields.

{ "op": "claim", "job_id": "0x…", "issued_at": 1786000000, "signature": "0x…" }

claim, settle and fail need issued_at within ±600 seconds of the node's clock. set_identity and request_capacity need issued_at greater than the last accepted one for that op and at most one hour ahead.

Response 201

{ "tx_hash": "0x…", "status": "success", "block_number": "12345678", "result_cid": "bafy…" }

result_cid is present on settle only: the IPFS CID the result was stored under.

Errors

POST /evm/simulate/claimCopy Anchor Link

An advisory check before signing a claim. It reads the chain, not the index, so it is accurate while the index lags.

Auth: public · Index-backed: no

Request

{ "job_id": "0x…", "address": "0x<provider wallet>" }

Response 200

{ "ok": false, "reason": "NotDesignated" }

{"ok": true}, or the first failing check, in the contract's order: UnknownJob, NotOpen, UnknownProvider, NotListed, ModelNotAllowed, NotDesignated, AtCapacity. It does not check the payment, the signature or the ±600-second window; POST /evm/ops simulates the real transaction.

AsksCopy Anchor Link

PUT /evm/asksCopy Anchor Link

Publish a signed ask snapshot to the AskRegistry. See Publish asks.

Auth: session (any address; the snapshot signature is the authority) · Index-backed: no · Body limit: 32 KiB

Request

{
  "snapshot": {
    "provider_id": 7,
    "signed_at": 1786000000,
    "quotes": [{ "model_id": 3, "sla": 3600, "rate_in": "1500", "rate_out": "6000" }]
  },
  "signature": "0x…"
}

Response 200: after the publication is mined and confirmed.

{ "provider_id": "7", "signed_at": "1786000000", "published": true, "tx_hash": "0x…" }

Errors

GET /evm/asksCopy Anchor Link

Published asks of listed providers.

Auth: public · Index-backed: yes · Paged: yes

Response 200

{ "asks": [{ "provider_id": "7", "model_id": "3", "sla": "3600", "rate_in": "1500", "rate_out": "6000" }], "as_of_block": "12345672" }

GET /evm/asks/floorsCopy Anchor Link

The lowest ask per (model_id, sla) across listed providers, for catalog models. rate_in and rate_out are each minimised on their own, so a floor row may combine two providers' rates.

Auth: public · Index-backed: yes · Paged: yes

Response 200

{ "floors": [{ "model_id": "3", "sla": "3600", "rate_in": "1200", "rate_out": "5000" }], "as_of_block": "12345672" }

Providers and catalogCopy Anchor Link

GET /evm/providersCopy Anchor Link

Registered providers, by id.

Auth: public · Index-backed: yes · Paged: yes

Response 200

{
  "providers": [
    {
      "provider_id": "7", "operator": "0x…", "box_key": "0x…", "evidence": {},
      "listed": true, "reputation": "1000",
      "allow_all_models": false, "allowed_models": ["3"],
      "capacity": "12", "active_jobs": "2"
    }
  ],
  "as_of_block": "12345672"
}

GET /evm/providers/{id}Copy Anchor Link

One provider plus as_of_block.

Auth: public · Index-backed: yes

Errors: 400 for an id that is not a uint32; 404 for an unknown provider.

GET /evm/modelsCopy Anchor Link

The model catalog; the same body as GET /v1/models.

GET /evm/allowlistCopy Anchor Link

Entries of the contracts' attestation allowlist.

Auth: public · Index-backed: yes · Paged: yes

Response 200

{ "entries": [{ "key": "0x…", "status": 1, "entry": {} }], "as_of_block": "12345672" }