market

Buy one answer on the Hekte market — PAY FIRST, per call, Lightning. Call it with `prompt` alone: the result is an error with `status: "payment_required"`, a Lightning `invoice` (bolt11) for `amount_sat` (whole sats), a `pay_url` a human can open, an `expires_at`, and `retry_with` (`payment_hash`, `retry_token`). Show the human the `pay_url` (or the invoice) and ask them to pay it; then call this tool AGAIN with the SAME `prompt` and `class` plus the `payment_hash` and `retry_token`. Before the payment arrives the retry answers `payment_not_received`; after it, the question is posted as a paid job — in the clear, on a public board; the market worker that wins it reads the prompt and answers — the payment settles ON DELIVERY and the answer comes back with who served it and a `receipt`. Test network only: the invoice is test sats, payable only from a wallet on that test network. If nothing is delivered the hold is cancelled (`hold_cancelled: true`) and nothing is charged. No balance is kept, no account exists: one invoice is one call. Refused by name: `prompt_too_large` (over 16384 bytes), `class_unknown`, `invalid_max_sat`, `proof_unknown`, `proof_expired`, `proof_replayed`, `proof_cancelled`, `retry_token_invalid` (the token is not this invoice's), `request_mismatch` (a retry must repeat the paid prompt), `contract_mismatch` (the `contract` named is not 2, this door's).

{
  "type": "object",
  "properties": {
    "base": {
      "default": "main",
      "description": "card.build.v0: the base branch the PR must be merged into.",
      "type": "string"
    },
    "base_sha": {
      "description": "code.pr.v0 (REQUIRED for this class): the base commit of `repo`, 40 hex — the PR head must descend from it and the test harness is pinned at it.",
      "pattern": "^[0-9a-f]{40}$",
      "type": "string"
    },
    "branch": {
      "description": "card.build.v0: the branch the PR comes from.",
      "type": "string"
    },
    "card": {
      "description": "card.build.v0: the card's text (alias of `prompt` for this class).",
      "type": "string"
    },
    "class": {
      "default": "chat",
      "description": "The task class: `chat` (one answer, returned by this call), `card.build.v0` (a desk card built by a lane, judged on the merged PR's reviewer approval and its selftest; takes `repo`, `branch`, `reviewer`, `reviewer_pk`, `selftest`, optional `base`; `card` or `prompt` carries the card's text), or `code.pr.v0` (code delivered as a pull request to the buyer's own PUBLIC repository, judged at the PR head inside a sealed box; takes `repo`, `base_sha`, `test_cmd`, `harness_paths`; `task` or `prompt` carries the task's text; local door only). A CARD IS ASYNC: this call posts it and returns at once with {job_id, status: \"posted\", board, deadline_s} — a card is minutes to hours; poll `hekte_job {job_id}` for posted | bid | funded | delivered | judged:PASS | judged:FAIL | withdrawing | withdrawn. Nothing is paid until the judge says PASS.",
      "enum": [
        "chat",
        "card.build.v0",
        "code.pr.v0"
      ],
      "type": "string"
    },
    "contract": {
      "description": "The hosted contract number this client speaks — every result of this door names it as `contract` and `retry_with` repeats it (today 2). Omit it if unknown; an older number is refused `contract_mismatch` because its retry shape is not this door's.",
      "type": "integer"
    },
    "harness_paths": {
      "description": "code.pr.v0 (REQUIRED for this class, may be empty): paths the buyer pins beside the fixed harness list (the test command's file, its report path, manifests, lockfiles, every conftest.py and runner config) — a PR that changes or adds any of them fails test_harness_changed. More, never fewer.",
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "max_sat": {
      "description": "Optional cap on this call's price, whole sats. May only LOWER the door's per-call price; a higher value is lowered to it.",
      "minimum": 1,
      "type": "integer"
    },
    "payment_hash": {
      "description": "The `retry_with.payment_hash` value from this tool's `payment_required` result, once a human has paid the invoice. Omit it on the first call; always send it together with `retry_token`.",
      "pattern": "^[0-9a-f]{64}$",
      "type": "string"
    },
    "prompt": {
      "description": "The question, verbatim — it is posted to the market as the job's input. A retry must repeat it exactly.",
      "type": "string"
    },
    "repo": {
      "description": "card.build.v0: the GitHub repo, owner/name.",
      "pattern": "^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$",
      "type": "string"
    },
    "retry_token": {
      "description": "The `retry_with.retry_token` value from this tool's `payment_required` result. Omit it on the first call; always send it together with `payment_hash`.",
      "pattern": "^[0-9a-f]{64}$",
      "type": "string"
    },
    "reviewer": {
      "description": "card.build.v0: the reviewer LANE (never the builder's own lane) whose SIGNED verdict the judge requires; a GitHub review or comment is the human mirror only.",
      "type": "string"
    },
    "reviewer_pk": {
      "description": "card.build.v0 (REQUIRED for this class): the reviewer lane's seat pubkey, 64 hex, from the desk's lane-keys.json (`scripts/fleet/regtest/lane-seats.sh keys`) — the key whose signed kind-1 verdict on the board pays the card.",
      "pattern": "^[0-9a-f]{64}$",
      "type": "string"
    },
    "selftest": {
      "description": "card.build.v0: the selftest the judge runs at the merge commit; exit 0 = pass.",
      "pattern": "^scripts/[A-Za-z0-9._/-]+\\.sh$",
      "type": "string"
    },
    "task": {
      "description": "code.pr.v0: the task's text (alias of `prompt` for this class). THE GIT-PR DELIVERY ROAD (card A98): code is delivered ONLY as a pull request to a PUBLIC repository the buyer owns, opened from the maker's own fork; the judge runs the buyer's test command inside a sealed box at base_sha and at the PR head and never needs the merge (taking the change in is the buyer's own step). Refused by name before any hold: repo_required, repo_not_public, test_report_required, code_job_held (mainnet). ASYNC like a card; poll hekte_job for the status and the text receipt.",
      "type": "string"
    },
    "test_cmd": {
      "description": "code.pr.v0 (REQUIRED for this class): the buyer's test command — its first word a file inside the repository (run as `bash <file> …`), the line carrying exactly one `--junit-xml=<path>` or `--report-json=<path>` word naming where the runner writes its own report; a command naming no report is refused (test_report_required).",
      "type": "string"
    }
  },
  "required": [
    "prompt"
  ],
  "additionalProperties": false
}

The PRICE of the next `hekte_ask` on this pay-first door: `price_sat` (whole sats, Lightning, per call), `invoice_expiry_s` (how long a minted invoice can be paid), `pay_first: true`, and `open` (whether the door can buy on the market right now). No balance exists here — every call is its own invoice.

{
  "type": "object",
  "properties": {
    "contract": {
      "description": "The hosted contract number this client speaks — every result of this door names it as `contract` and `retry_with` repeats it (today 2). Omit it if unknown; an older number is refused `contract_mismatch` because its retry shape is not this door's.",
      "type": "integer"
    }
  },
  "additionalProperties": false
}

One job's lines from this door's BUYER LEDGER (posted, offers, funding, delivery, settlement — ids, sats, times, codes; never the brief or the output), for a job YOUR payment ran: `job_id` must be the one `hekte_ask` returned for this `payment_hash` + `retry_token`. `found: false` = no line names it.

{
  "type": "object",
  "properties": {
    "contract": {
      "description": "The hosted contract number this client speaks — every result of this door names it as `contract` and `retry_with` repeats it (today 2). Omit it if unknown; an older number is refused `contract_mismatch` because its retry shape is not this door's.",
      "type": "integer"
    },
    "job_id": {
      "description": "The job id `hekte_ask` returned.",
      "type": "string"
    },
    "payment_hash": {
      "description": "The `payment_hash` of the `hekte_ask` that ran this job.",
      "pattern": "^[0-9a-f]{64}$",
      "type": "string"
    },
    "retry_token": {
      "description": "The `retry_token` of the `hekte_ask` that ran this job.",
      "pattern": "^[0-9a-f]{64}$",
      "type": "string"
    }
  },
  "required": [
    "job_id",
    "payment_hash",
    "retry_token"
  ],
  "additionalProperties": false
}