# ModelWorks

> AI circuit marketplace. Build, share, and run AI workflows as circuits — composable pipelines that fetch data, call LLMs, and return structured output. Run circuits via HTTP API. Pay per-call with USDC using the x402 protocol, or use an API key.

## How to search and run a circuit

### 1. Find a circuit
GET /api/search?q=<query>&type=circuit
No auth required. Returns matching circuits with UIDs, names, descriptions, and owners.

### 2. Run a circuit
POST /api/circuit-adaptors/:adaptor_uid/query
Two ways to authenticate:

  a) API key (Bearer token):
     Authorization: Bearer mw_xxx
     Uses existing billing — credits deducted from your wallet.

  b) x402 payment (no key needed):
     Send request with no auth → receive 402 with payment-required header →
     sign USDC payment → retry with payment-signature header → receive 200.
     Accepted: USDC on Base, Ethereum, Polygon, Solana.
     Pricing: per-circuit (shown in the 402 response). Free circuits: $0.01 minimum.
     See /.well-known/x402.json for the payment manifest.

### 3. Get circuit details
GET /api/circuits/:circuit_uid
No auth required. Returns circuit metadata, input schema, and description.

## API reference

### No auth required
- GET /api/search?q=<query>&type=circuit — Search circuits and users
- GET /api/home/featured-circuits — List featured circuits
- GET /api/circuits/:circuit_uid — Get circuit details
- GET /api/circuit-versions/:circuit_version_uid — Get circuit version details

### API key required (Bearer token)
- POST /api/circuit-runs — Create a circuit run
- POST /api/circuits — Create a circuit
- POST /api/circuit-versions — Create a circuit version
- PUT /api/circuit-versions/:circuit_version_uid/state — Update version state
- GET /api/circuit-versions/:circuit_version_uid/prompts — List prompts
- GET /api/users/:user_uid/circuits — List user's circuits
- POST /api/circuits/:circuit_uid/stars — Star a circuit
- DELETE /api/circuits/:circuit_uid/stars — Unstar a circuit
- GET /api/circuits/:circuit_uid/stars — Check star status
- POST /api/circuit-boards — Create a board
- GET /api/circuit-boards — List boards
- POST /api/boards/:board_uid/circuits — Add circuit to board
- GET /api/blobs/:blob_uid — Get a blob

### x402 payment or API key
- POST /api/circuit-adaptors/:adaptor_uid/query — Run a circuit via its adaptor
  With Bearer token: uses existing billing (credits from wallet).
  Without auth: x402 payment (USDC, per-call). See /.well-known/x402.json.

### Web session required (sign in at modelworks.ai)
These endpoints require a web session token (TokenWeb role) and cannot be
accessed via API key alone. Sign in at https://modelworks.ai to get a session token.

- POST /api/user-tokens — Create an API key
- GET /api/user-tokens — List your API keys
- DELETE /api/user-tokens/:token_uid — Delete an API key
- POST /api/secrets/circuits/:circuit_version_uid — Set circuit secrets
- GET /api/secrets/circuits/:circuit_version_uid — Get circuit secrets
- GET /api/user-wallet — Get your wallet balance
- GET /api/user-wallet/transactions — List wallet transactions
- POST /api/user-wallet/transactions/external — External wallet operations
- POST /api/user-organizations — Create organization membership
- GET /api/user-organizations — List your organizations
- POST /api/user-x-adaptors — Link an external adaptor
- GET /api/user-x-adaptors — List linked adaptors

## Payment manifest
See /.well-known/x402.json for the machine-readable x402 payment manifest
with supported chains, USDC contract addresses, and treasury addresses.