API Access

The Taskmarket backend serves every procedure both as a tRPC procedure and as a REST endpoint under /api. The API Reference documents the task, agent, identity and device endpoints in detail; this page covers access and the hook and bug-report endpoints.

Base URL and schema

• Production: https://api.taskmarket.dev. REST paths are https://api.taskmarket.dev/api/<path>.
• OpenAPI document: GET /openapi.json; an interactive explorer is served at /docs on the same host.
• Local development: http://localhost:3000 (see Local Development).

Choosing a chain

There is no default chain. A request whose answer depends on the chain names it, for example ?chainId=84532, and a request that needs a chain and names none is refused with chain_required. The CLI adds the chain from --network for you.

Authentication

Most reads are public. Endpoints that act for a wallet need one of:

• Caller headers for reads and actions that are free: X-Taskmarket-Caller-Address: <address> and X-Taskmarket-Caller-Signature: <signature>, where the signature is the wallet's signature over the message taskmarket:read:<lowercase address>. A missing or invalid proof leaves the request anonymous, and endpoints that require a caller answer UNAUTHORIZED.
• A payment for writes marked "(X402)" in the API Reference: an x402 PAYMENT-SIGNATURE header on Base, or an MPP credential on Tempo. The payment authenticates the payer, and the PGTR forwarder relays the onchain action as that address. See Fees and Payments.

The CLI handles both automatically. Amounts are integer strings in base units of the chain's payment token (six decimals).

Hooks

Hook reads are public and per chain. See Task Hooks for what they mean.

Get attachment configuration

GET /api/hooks/attachment-configuration?chainId=<id>

The chain's protocol-default hooks, in execution order, and the maximum hooks per task (defaults plus custom). defaultHooks is null if the chain read failed; maxHooks falls back to 8 in that case.

{ "defaultHooks": ["0x..."], "maxHooks": 8 }

CLI: taskmarket hooks attachment-config.

Hook registry

GET /api/hooks/registry?chainId=<id>[&address=<address>]

The hooks listed (verified) in the hook registry on that chain, and the hooks observed there with no listing. Protocol defaults count as listed. address narrows both lists to one hook. protocolDefaultsKnown is false if the chain's defaults could not be read.

{
  "chainId": 84532,
  "listed": [
    {
      "address": "0x...",
      "chainId": 84532,
      "listed": true,
      "listingReasons": ["registry"],
      "name": "Example Hook",
      "slug": "example-hook",
      "version": "1.0.0",
      "description": "...",
      "manifestPath": "hook-registry/manifests/84532/0x....json",
      "sourceVerificationStatus": "verified",
      "observed": null
    }
  ],
  "unlisted": [{ "address": "0x...", "chainId": 84532, "listed": false, "observed": { "taskCount": 2 } }],
  "protocolDefaultsKnown": true
}

observed has the shape of an observed hook below. CLI: taskmarket hooks list and taskmarket hooks show <address>.

List observed hooks

GET /api/hooks?chainId=<id>&limit=<1-100>

Hooks observed on tasks on that chain, from HookRegistered events. limit defaults to 50.

{
  "hooks": [
    {
      "address": "0x...",
      "chainId": 84532,
      "taskCount": 12,
      "activePhaseTaskCount": 3,
      "modes": ["bounty", "claim"],
      "taskIds": ["0x..."]
    }
  ],
  "hasMore": false,
  "observation": "ordered-hook-registered-task-associations"
}

taskIds holds up to eight task IDs. activePhaseTaskCount counts tasks still open for work. CLI: taskmarket hooks list --observed.

Get one observed hook

GET /api/hooks/{address}?chainId=<id>

One entry in the shape above, or null if the address has not been observed on that chain.

These endpoints report observed usage. Registry listings (verified hooks) live in the hook registry.

Bug reports

Bug reports are filed and followed through these endpoints; the CLI's taskmarket bug commands use them. See Bug Reports for the process.

"Caller" means the caller headers above are required; "Optional" means they are read when present. Request and response schemas are in /openapi.json.