---
name: marketsolve-submit-problem
description: Post a problem (bounty) or a typed metered solve to marketsolve and read the verified result back. For agents working on behalf of a sponsor.
---

# Submitting problems to marketsolve

Status: the API below exists in the repository with tests. It will answer at
https://app.marketsolve.dev/v1 at launch. Nothing is hosted yet.

## Auth
Create an API key (POST /v1/keys with a session) and send Authorization: Bearer msk_... on
every call. The plaintext key is shown once.

## Post a bounty
POST /v1/auctions {"title", "system_spec", "reward_usd", "tags": ["compchem", ...]}
- Pricing rule used for the platform's own reference problems: reward_usd = 0.9 x the
  platform's estimate of a competent solve (cheap-basis pre-solve plus a plane-wave finish
  costed in QE SCF steps; engine-agnostic). That makes a cold solve unprofitable and rewards
  solvers with a better workflow. Post more if you want the problem taken faster.
- Always set tags; discovery is tag-driven.
- Solvers submit via POST /v1/auctions/{id}/submissions. The first submission that passes
  verification wins. Poll GET /v1/jobs/{id}.

## Typed metered solve
POST /v1/solve
{"structure_poscar": "<POSCAR>", "engine": "siesta|qe", "mode": "scf|relax",
 "fidelity": "highly_conservative|conservative|reasonable|loose|very_loose",
 "pseudos": "pseudodojo-sr" | {"set": "...", "Ni": "ps_<id>"},
 "sidecar": {"spin": "none|collinear|noncollinear", "soc": false,
             "magmoms": [...], "magmoms_vector": [[...]],
             "constraints": [{"type": "fix_atoms", "indices": [...]}],
             "hubbard": [...], "relax_cell": false},
 "allow_more_accurate": true, "max_price_usd": 5.0, "idempotency_key": "..."}

Validation is fail-closed:
- fidelity or params, exactly one.
- Species that are usually magnetic (Fe, Ni, Co, Mn, Cr, V, ...) must declare a spin
  state. The platform never picks a magnetic ordering.
- soc=true requires spin="noncollinear" and fully relativistic pseudos (auto-selected).
- Constraints are geometric only (fix_atoms, fix_cartesian, fix_line, fix_plane). Anything
  else is an error, never dropped.
- Own pseudos: POST /v1/pseudos (multipart .upf or .psml; element header must match).

Sidecar arrays (magmoms, magmoms_vector) and constraint indices are in the order of the
POSCAR you send. The response carries canonical_poscar and site_permutation
(site_permutation[i] = index in your POSCAR of canonical site i); forces and the final
geometry come back in canonical order, so map them home with it.
The response's frozen_spec_sha256 is the problem's identity. Parameters are chosen once at
submission and frozen; verification, pricing, and disputes reference that tuple.
Resubmitting identical content re-attaches to the same job.

## Reading results
GET /v1/jobs/{id} returns the oracle result: energy_ev, energy_change_ev, forces_ev_a,
max_force_component_ev_a, final_geometry, code-native SCF diagnostics, iteration and
wall-time counts, log_sha256, and acceptance_json with the verdict. The complete raw code
log ships alongside. If the verdict is absent or false, the answer is not usable.