VORQ Docs
Reference

Provider API

Every /evm/* route, for the deployment, the job book, provider operations, asks, providers and the allowlist.

The request and response schema for every route on this page is in the API reference. This page covers the flow and what each refusal means.

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.

Deployment

GET /evm/chain

The deployment parameters a client or provider needs to sign.

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

contracts.usdc is the payment token, and token_domain its EIP-712 name and version for signing the payment. block_time_ms is the node's poll interval. fee_bps is the protocol fee.

Errors: 503 chain_unreachable or relay_unavailable (config_read).

Job book

GET /evm/jobs

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

state=Cancelled matches every ended job: cancelled, expired, failed or reclaimed. provider matches the jobs claimed by that provider. min_rate_in and min_rate_out keep jobs at or above those rates; posted_before keeps jobs posted at or before that block. The default order is oldest, by posting block.

state and ended_because are as in Job lifecycle; an open job past expires_at reads as 3 / 5. provider_id, claimed_at, prompt_tok, cached_tok, completion_tok and rate_in_cached are "0" until claimed or settled; the four usage fields are what settlement billed, after the contract's clamps. gas_fee is the relay gas fee in USD that the JobRegistry fixed for the job when it was posted; the treasury keeps it when a claimed job settles, fails or is reclaimed. fee is the protocol fee in USD that settlement took on top of the charge, "0" for a job that did not settle.

Provider poll. free=N 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. Held orders among them are posted on chain before the poll answers. 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

StatuscodeCause
400nullA bad filter (param names it); free without state=Open or model; a model not in the catalog.
401invalid_sessionfree without a valid session.
403not_registeredfree with a session that is not a provider session.
curl -s "https://api.vorq.co/evm/jobs?state=Open&model=3&free=4" \
  -H "authorization: Bearer $TOKEN"

GET /evm/jobs/summary

Totals for one owner, overall and per model.

Auth: public · Index-backed: yes

completed counts settled jobs, and escrowed is what their claims lock, summed over all of them: each job's cap, the protocol fee on it at the current fee_bps, and its gas_fee.

GET /evm/jobs/{job_id}

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 operations

POST /evm/ops

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

A missing session answers 401 before the body is validated.

Request: a flat object with op, signature and the op's fields. signature is the provider wallet's signature over the op's signed message: Claim, Settle, Fail, SetIdentity or RequestCapacity.

{ "op": "claim", "job_id": "0x…", "issued_at": 1786000000, "signature": "0x…" }
  • settle takes prompt_tok, cached_tok and completion_tok (integers) and rate_in_cached (USD per 1M, a decimal string), all signed, and exactly one of result (the sealed result, base64, non-empty) and result_cid (the vorq.cid of a result upload by this session's address).
  • 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: after the receipt. On settle only, result_cid is the IPFS CID the result was stored under.

Errors

StatusBody or codeCause
400result_required, result_ambiguous, unknown_result, or nullA malformed op (param names the field), or a missing, doubled or unknown result.
401invalid_sessionNo valid session. Answered before the body is validated.
403type invalid_op_signatureThe signature does not recover to a registered provider.
409{"ok": false, "reason": "<ContractError>"}The chain refuses the op, for example StaleOp, NotOpen, AtCapacity, SlaExpired. When reason is unknown, raw carries the revert data. x-vorq-retryable: false.
429, 503, 504See Errors. A 504 message names the route to poll.

POST /evm/simulate/claim

An advisory check before signing a claim, for a job_id and the provider wallet address. It reads the chain, not the index, so it is accurate while the index lags.

Auth: public · Index-backed: no

Response 200: {"ok": true}, or {"ok": false, "reason": …} with the first failing check, in the contract's order: UnknownJob, NotOpen, UnknownProvider, NotListed, ModelNotAllowed, NotDesignated, AtCapacity, InsufficientFunds (the owner's balance is below the escrow pull). It does not check the signature or the ±600-second window; POST /evm/ops simulates the real transaction.

Reads are pinned to the node's floor block and shared within it: a burst of checks — a batch's lines claimed one after another — reads the owner's balance and each provider gate once per block, and only getJob once per job.

Asks

PUT /evm/asks

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

A missing session answers 401 before the body is validated.

Request

{
  "snapshot": {
    "provider_id": 7,
    "signed_at": 1786000000,
    "quotes": [
      { "model_id": 3, "sla": 3600, "rate_in": "0.0015", "rate_out": "0.006", "rate_in_cached": "0.00075" }
    ]
  },
  "signature": "0x…"
}
  • snapshot.provider_id must be the signer's provider id.
  • snapshot.signed_at must be newer than the provider's latest snapshot and at most one hour ahead of the node's clock.
  • Each quote sets the ask for its (model_id, sla); both rates 0 withdraws it.
  • rate_in_cached is optional and not signed: the cached input rate listed with the ask, at most rate_in. Absent lists rate_in.
  • signature is the provider wallet's AskSnapshot signature.

Response 200: after the publication is mined and confirmed.

Errors

StatuscodeCause
400nullA malformed field, with param naming it as a path such as snapshot.quotes[3].rate_in; signed_at too far ahead.
401invalid_sessionNo valid session. Answered before the body is validated.
403invalid_signatureThe signature does not recover over the snapshot.
403not_registeredThe signer is not a registered provider.
403provider_mismatchThe signer operates a different provider than snapshot.provider_id.
409stale_snapshotsigned_at is not newer than the provider's latest.
409supersededA newer snapshot is already on chain.
503publication_skippedMined, but the chain recorded no publication. Retry.
504tx hashNo receipt within 60 seconds. The snapshot is stored; check GET /evm/asks rather than pushing it again.

GET /evm/asks

Published asks of listed providers.

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

{
  "asks": [
    { "provider_id": 7, "model_id": 3, "sla": 3600, "rate_in": "0.0015", "rate_out": "0.006", "rate_in_cached": "0.00075" }
  ],
  "as_of_block": 123456
}
  • rate_in, rate_out are the on-chain ask.
  • rate_in_cached is the provider's listed rate for cached input, at most rate_in; equal to rate_in when it lists no discount. Settle signs the rate charged.

Providers and catalog

GET /evm/providers

Registered providers, by id.

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

  • name is the display name this coordinator gives the provider; null when it gives none. It is not on chain.
  • box_key is the X25519 key designated orders are sealed to; null until set.
  • evidence is the identity evidence published with set_identity, or null.
  • reputation is 100–1000.
  • capacity is the effective capacity: max(1, reputation × min(requested, ceiling) / 1000).
  • active_jobs counts the jobs it currently holds claimed.

GET /evm/providers/{id}

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/models

Every registered model, disabled ones included, in the shape of GET /v1/models.

GET /evm/allowlist

Entries of the contracts' attestation allowlist.

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

On this page