# Flow Memory Inference Market Index

This raw markdown index is optimized for agents and documentation crawlers. It points to the complete dry-run inference marketplace contract and quickstart surfaces.

## Canonical docs

- `docs/INFERENCE_MARKET.md` — complete marketplace engine: credential refs, provider runtime, order book, reservations, routing, disabled payment preview, analytics/export, and safety boundary.
- `docs/INFERENCE_PROXY.md` — SDK-compatible proxy usage with Flow Memory auth and route metadata.
- `docs/INFERENCE_MARKET_ENDPOINTS.json` — machine-readable endpoint schema index and agent quickstart bundle.

## Example programs

- `examples/inference_market_demo.py` — SDK drop-in request shapes, market depth, routing, disabled payment preview, and analytics/export. Network calls are disabled by default.
- `examples/inference_provider_onboarding_demo.py` — credential-ref lifecycle plus provider enrollment, pairing, heartbeat, catalog, capacity, and health. No raw credentials.
- `examples/inference_agent_quote_route_buy.py` — agent quote, route, order, reservation, disabled payment preview, and analytics export flow. No external provider calls.

## Safety invariants

All marketplace flows are application records only:

- `dry_run_only=true`
- `funds_moved=false`
- `broadcast_allowed=false`
- `private_key_required=false`
- `live_trading_enabled=false`
- `legal_review_required=true`
- `compliance_review_required=true`

Do not include raw provider secret values, sensitive signing material, value-transfer instructions, production execution flags, broadcast flags, or direct execution flags in requests.


## Shared route contract templates

These literal templates mirror the dashboard route contract. Runtime clients still encode placeholder values before dispatch.

| Key | Method | Literal route template | Placeholders |
|---|---|---|---|
| `marketList` | `GET` | `/inference/market/list` | none |
| `modelDetail` | `GET` | `/inference/market/models/{model}` | `model` |
| `feed` | `GET` | `/inference/market/feed` | none |
| `buyerProfile` | `GET` | `/inference/buyers/{buyer_id}/profile` | `buyer_id` |
| `sellerProfile` | `GET` | `/inference/sellers/{seller_id}/profile` | `seller_id` |
| `providerAgentManifest` | `GET` | `/inference/providers/agent/manifest` | none |
| `credentialRefs` | `POST`, `GET` | `/inference/credential-refs` | none |
| `credentialRefRotate` | `PATCH` | `/inference/credential-refs/{credential_ref_id}/rotate` | `credential_ref_id` |
| `credentialRefRevoke` | `POST` | `/inference/credential-refs/{credential_ref_id}/revoke` | `credential_ref_id` |
| `providerEnroll` | `POST` | `/inference/providers/enroll` | none |
| `providerPairingToken` | `POST` | `/inference/providers/{provider_id}/pairing-token` | `provider_id` |
| `providerHeartbeat` | `POST` | `/inference/providers/{provider_id}/heartbeat` | `provider_id` |
| `providerCatalog` | `POST` | `/inference/providers/{provider_id}/catalog` | `provider_id` |
| `providerCapacity` | `POST` | `/inference/providers/{provider_id}/capacity` | `provider_id` |
| `providerHealth` | `GET` | `/inference/providers/{provider_id}/health` | `provider_id` |
| `marketOrders` | `POST` | `/inference/market/orders` | none |
| `marketOrderCancel` | `POST` | `/inference/market/orders/{order_id}/cancel` | `order_id` |
| `marketDepth` | `GET` | `/inference/market/depth` | none |
| `marketReservations` | `POST` | `/inference/market/reservations` | none |
| `paymentChallengePreview` | `POST` | `/inference/market/payment-challenge/preview` | none |
| `analyticsUsage` | `GET` | `/inference/analytics/usage` | none |
| `analyticsExport` | `GET` | `/inference/analytics/export` | none |

## Endpoint groups

### Marketplace discovery and profiles

- `GET /inference/market/list`
- `GET /inference/market/models/{model}`
- `GET /inference/market/feed`
- `GET /inference/buyers/{buyer_id}/profile`
- `GET /inference/sellers/{seller_id}/profile`
- `GET /inference/providers/agent/manifest`

### Credential refs

- `POST /inference/credential-refs`
- `GET /inference/credential-refs`
- `PATCH /inference/credential-refs/{credential_ref_id}/rotate`
- `POST /inference/credential-refs/{credential_ref_id}/revoke`

### Provider runtime

- `POST /inference/providers/enroll`
- `POST /inference/providers/{provider_id}/pairing-token`
- `POST /inference/providers/{provider_id}/heartbeat`
- `POST /inference/providers/{provider_id}/catalog`
- `POST /inference/providers/{provider_id}/capacity`
- `GET /inference/providers/{provider_id}/health`

### Market mechanics

- `POST /inference/market/orders`
- `POST /inference/market/orders/{order_id}/cancel`
- `GET /inference/market/depth`
- `POST /inference/market/reservations`

### Routing, payment preview, analytics

- `POST /inference/quote`
- `POST /inference/route`
- `POST /inference/market/payment-challenge/preview`
- `GET /inference/analytics/usage`
- `GET /inference/analytics/export`

### SDK proxy

- `GET /v1/models`
- `POST /v1/chat/completions`
- `POST /v1/responses`
- `POST /v1/embeddings`

## Agent quickstart bundle

1. Read depth: `GET /inference/market/depth?model=flow-memory-orchestrator&unit_type=token`.
2. Quote with safety policy: `POST /inference/quote` using `dry_run_required=true`, `raw_credentials_allowed=false`, `broadcast_enabled=false`, and `sensitive_signing_inputs_allowed=false`.
3. Route: `POST /inference/route` and inspect `selected_quote`, `rejected_routes`, `warnings`, and safety fields.
4. If policy permits, create a dry-run order: `POST /inference/market/orders`.
5. Hold capacity when needed: `POST /inference/market/reservations`.
6. Use SDK proxy base URL only after route metadata is acceptable.
7. Preview payment challenge only as disabled audit metadata: `POST /inference/market/payment-challenge/preview`.
8. Export usage: `GET /inference/analytics/export?format=ndjson`.

## Minimal safe policy

```json
{
  "market_policy": {
    "allowed_models": ["flow-memory-orchestrator"],
    "max_unit_price": 0.0000008,
    "min_discount_bps": 500,
    "allow_fallback": true,
    "require_healthy_provider": true,
    "dry_run_required": true,
    "raw_credentials_allowed": false,
    "broadcast_enabled": false,
    "sensitive_signing_inputs_allowed": false
  }
}
```