> ## Documentation Index > Fetch the complete documentation index at: https://docs.lucid.foundation/llms.txt > Use this file to discover all available pages before exploring further. # Plan a route (match + resolve endpoint) > Perform compute matching and resolve an executable inference endpoint in a single call. Returns the matched compute node, model, endpoint URL, runtime, policy hash, and fallback options. ## OpenAPI ````yaml /openapi-spec.yaml post /v1/route openapi: 3.0.3 info: title: LucidLayer API version: 1.0.0 description: > LucidLayer API — the verifiable AI execution layer. Blockchain-anchored infrastructure giving AI assets (models, agents, tools, compute, datasets) provable identity, cryptographic receipts, and reputation backed by real traffic data. **Open-source and self-hostable.** Run your own instance with `docker compose up` or `npm start` (port 3001). The SDK defaults to `http://localhost:3001` — no cloud account required. This OpenAPI spec is the source of truth for all backend routes and is used to generate SDK clients via [Speakeasy](https://speakeasy.com). ## Version Strategy | Prefix | Status | Description | |--------|--------|-------------| | `/v1/*` | **Stable** | Core API — passports, receipts, epochs, payouts, inference, agent deployment. Production-ready and covered by semver guarantees. | | `/v2/*` | **Stable** | Cross-chain and reputation APIs — EVM multi-chain, ERC-8004, pluggable reputation. Production-ready. | | `/api/agents/*` | **Deprecated** | Legacy agent MMR orchestration. Retained for SDK backward compatibility only. Migrate to `/v1/agents/*` (AgentDeploy, AgentMirror). Will be removed in a future major version. | | `/health/*` | **Stable** | System health probes — not versioned (infrastructure endpoints). | ### Migration Path (legacy `/api/agents/*` to `/v1/agents/*`) 1. Replace `init_agent` + `process_agent_epoch` with `lucid_deploy_agent` (one-click deployment). 2. Replace `generate_agent_proof` with `lucid_get_agent_proof` / `lucid_get_agent_run_proof` (AgentMirror). 3. Replace `get_agent_stats` / `get_agent_history` with `lucid_get_agent_receipts` + `lucid_get_agent_epoch`. 4. All legacy operationIds will be removed when the next major version ships. ## Route Groups - `/v1/*` — Passports, Match, Run, Receipts, Epochs, Payouts, Compute - `/v1/agents/*` — Agent Deployment, Wallet, Revenue, Mirror (receipts/proofs) - `/v1/a2a/*` — A2A Protocol (Agent-to-Agent) - `/v1/config/*` — Payment configuration and grants - `/v2/chains/*` — Cross-chain status and routing - `/v2/agents/*` — ERC-8004 agent registration and reputation - `/v2/reputation/*` — Pluggable reputation scoring, cross-chain aggregation - `/v2/payouts/*` — On-chain payout execution - `/health/*` — System health and dependency checks - `/api/agents/*` — Legacy agent MMR orchestration (deprecated) servers: - url: http://localhost:3001 description: Local / self-hosted (default for open-source users) x-speakeasy-server-id: local - url: https://{host}:{port} description: Self-hosted instance (custom host and port) x-speakeasy-server-id: self-hosted variables: host: default: localhost description: Hostname or IP of your Lucid instance port: default: '3001' description: Port your Lucid instance listens on - url: https://api.lucid.foundation description: Managed cloud (Raijin Labs hosted) x-speakeasy-server-id: cloud security: - BearerAuth: [] - {} tags: - name: Passports description: >- AI asset identity — create, list, update, delete model/compute/tool/dataset/agent passports - name: Match description: Policy-based compute matching and route planning - name: Run description: OpenAI-compatible inference (chat completions) and model listing - name: Receipts description: Cryptographic receipts — create, verify, and generate MMR inclusion proofs - name: Epochs description: Epoch lifecycle — creation, finalization, on-chain anchoring, and retry - name: Payouts description: Revenue split calculation and payout execution (basis-point math) - name: Compute description: Compute node heartbeat registration and health monitoring - name: Health description: System health — liveness, readiness, and per-dependency status checks - name: Agents description: >- DEPRECATED: Legacy agent MMR orchestration (use AgentDeploy, AgentMirror instead) - name: Shares description: Share token launch and revenue airdrop for fractional AI asset ownership - name: Escrow description: Cross-chain escrow lifecycle — create, release, dispute, and query - name: Disputes description: Escrow dispute resolution — open, submit evidence, resolve, appeal - name: Paymaster description: >- ERC-4337 gas sponsorship — sponsor transactions, estimate fees, check rates - name: Identity description: >- Cross-chain identity bridging — CAIP-10 linking, resolution, and chain discovery - name: TBA description: ERC-6551 Token Bound Accounts — create and query agent wallets - name: Modules description: >- ERC-7579 module management — install, uninstall, and configure policy/payout modules - name: zkML description: >- Zero-knowledge ML — prove inference, verify proofs, register models on-chain - name: Payments description: >- x402 payment configuration — pricing, facilitators, grants, and subscription - name: AgentDeploy description: >- Agent deployment lifecycle — deploy, status, logs, scale, terminate across 6 targets - name: AgentWallet description: Agent PDA wallet — balance, send, policy limits, and transaction history - name: AgentRevenue description: >- Agent revenue pools — earnings tracking, airdrop triggers, and pool queries - name: A2A description: Google A2A protocol — agent cards, task submission, and task lifecycle - name: Reputation description: >- Pluggable reputation scoring — algorithms, compute scores, and composite aggregation - name: CrossChain description: >- EVM multi-chain operations — chain status, ERC-8004 registration, cross-chain reputation and payouts - name: AgentMirror description: >- Read-only agent proof endpoints — receipts, epochs, and MMR proofs (admin auth required) - name: Memory description: >- Agent memory — episodic, semantic, procedural, entity, trust-weighted, temporal types with hash-chain provenance - name: Anchoring description: >- DePIN anchoring control plane — query, verify, and trace artifact anchor records - name: AgentLaunch description: >- Agent activation — launch via image or base runtime, blue-green rollout, promotion, and rollback - name: Webhooks description: >- Deployment webhook receivers — normalizes provider-specific callbacks into deployment events paths: /v1/route: post: tags: - Match summary: Plan a route (match + resolve endpoint) description: > Perform compute matching and resolve an executable inference endpoint in a single call. Returns the matched compute node, model, endpoint URL, runtime, policy hash, and fallback options. operationId: lucid_route requestBody: required: true content: application/json: schema: type: object properties: model_meta: $ref: '#/components/schemas/ModelMeta' policy: $ref: '#/components/schemas/Policy' compute_catalog: type: array items: $ref: '#/components/schemas/ComputeMeta' request_id: type: string require_live_healthy: type: boolean default: true responses: '200': description: OK content: application/json: schema: type: object required: - success - route - explain properties: success: type: boolean request_id: type: string route: type: object properties: compute_passport_id: type: string model_passport_id: type: string endpoint: type: string runtime: type: string policy_hash: type: string fallbacks: type: array items: type: object additionalProperties: true explain: type: object additionalProperties: true '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/InternalServerError' x-codeSamples: - lang: typescript label: Typescript (SDK) source: |- import { RaijinLabsLucidAi } from "raijin-labs-lucid-ai"; const raijinLabsLucidAi = new RaijinLabsLucidAi(); async function run() { const result = await raijinLabsLucidAi.match.planRoute({}); console.log(result); } run(); components: schemas: ModelMeta: type: object description: >- Metadata for a model passport. Validated against schemas/ModelMeta.schema.json (additionalProperties: false). required: - schema_version - model_passport_id - format - runtime_recommended properties: schema_version: type: string enum: - '1.0' model_passport_id: type: string minLength: 10 format: type: string enum: - safetensors - gguf - api runtime_recommended: type: string enum: - vllm - tgi - tensorrt - trustgate - openai name: type: string description: type: string provider: type: string description: Provider name (e.g. trustgate, openai) base: type: string enum: - hf - openai - anthropic - google - cohere - custom_endpoint default: hf hf: type: object properties: repo_id: type: string revision: type: string context_length: type: integer minimum: 1 quantizations: type: array items: type: string enum: - fp16 - int8 - awq - gptq - gguf_q4 requirements: $ref: '#/components/schemas/ModelRequirements' endpoints: type: object properties: openai_compat_base_url: type: string auth_mode: type: string enum: - byok - lucid_key - none default: none artifacts: type: array items: type: string weights_uri: type: string weights_hash: type: string Policy: type: object required: - policy_version additionalProperties: false properties: policy_version: type: string description: Policy schema version, e.g. '1.0' allow_regions: type: array items: type: string residency_required: type: boolean attestation: type: object additionalProperties: false properties: attestation_required: type: boolean require_cc_on: type: boolean fallback_allowed: type: boolean latency: type: object additionalProperties: false properties: p95_ms_budget: type: integer hard_timeout_ms: type: integer cost: type: object additionalProperties: false properties: max_price_per_1k_tokens_usd: type: number spot_only: type: boolean privacy: type: object additionalProperties: false properties: store_inputs: type: boolean redact_pii: type: boolean ComputeMeta: type: object description: >- Metadata for a compute provider passport. Validated against schemas/ComputeMeta.schema.json (additionalProperties: false). required: - schema_version - compute_passport_id - provider_type - regions - hardware - runtimes - endpoints properties: schema_version: type: string enum: - '1.0' compute_passport_id: type: string minLength: 10 provider_type: type: string enum: - depin - cloud - onprem - managed execution_mode: type: string enum: - byo_runtime - managed_endpoint operator_pubkey: type: string pattern: ^[a-f0-9]{64}$ description: ed25519 public key (hex) of the provider operator regions: type: array items: type: string minItems: 1 residency_supported: type: boolean default: false hardware: $ref: '#/components/schemas/ComputeHardware' gpu_fingerprint: type: string nullable: true description: GPU hardware fingerprint. Must be null for managed_endpoint mode. runtime_hash: type: string nullable: true pattern: ^sha256:[a-f0-9]{64}$ description: Docker image digest. Must be null for managed_endpoint mode. runtimes: type: array items: $ref: '#/components/schemas/ComputeRuntime' minItems: 1 capabilities: $ref: '#/components/schemas/ComputeCapabilities' network: type: object properties: p95_ms_estimate: type: integer minimum: 0 bandwidth: type: string limits: type: object properties: max_context: type: integer minimum: 0 max_batch: type: integer minimum: 0 max_input_tokens: type: integer minimum: 1 max_output_tokens: type: integer minimum: 1 requests_per_minute: type: integer minimum: 1 pricing: type: object properties: price_per_1k_tokens_estimate: type: number minimum: 0 price_per_minute_estimate: type: number minimum: 0 per_input_token: type: number minimum: 0 per_output_token: type: number minimum: 0 currency: type: string enum: - lamports - usd_cents - credits endpoints: $ref: '#/components/schemas/ComputeEndpoints' workers: type: array items: $ref: '#/components/schemas/ComputeWorker' sla: type: object properties: tier: type: string enum: - best-effort - standard - premium - enterprise uptime_target: type: number minimum: 0 maximum: 100 policy_tags: type: array items: type: string description: Tags for matching (e.g. 'hipaa', 'gdpr', 'no-logging') metadata: type: object additionalProperties: true ModelRequirements: type: object properties: min_vram_gb: type: integer minimum: 0 gpu_classes: type: array items: type: string cuda_min: type: string ComputeHardware: type: object required: - gpu - vram_gb properties: gpu: type: string description: GPU model (e.g. 'NVIDIA-A100-40GB') vram_gb: type: integer minimum: 0 description: GPU VRAM in gigabytes arch: type: string description: GPU architecture (e.g. 'ampere', 'hopper') gpu_count: type: integer minimum: 1 default: 1 cpu_cores: type: integer minimum: 1 memory_gb: type: integer minimum: 1 description: System RAM in gigabytes ComputeRuntime: type: object required: - name properties: name: type: string enum: - vllm - tgi - tensorrt - hf-inference-api - openai-compatible - custom version: type: string image: type: string description: Docker image reference ComputeCapabilities: type: object properties: supports_streaming: type: boolean default: true supports_attestation: type: boolean default: false supports_cc_on: type: boolean default: false inference_types: type: array items: type: string enum: - text-generation - chat-completion - embeddings - image-generation - speech-to-text ComputeEndpoints: type: object required: - inference_url properties: inference_url: type: string description: URL for inference requests quote_url: type: string format: uri jobs_url: type: string format: uri health_url: type: string format: uri metrics_url: type: string format: uri ComputeWorker: type: object required: - worker_id - status properties: worker_id: type: string status: type: string enum: - online - offline - degraded - draining last_heartbeat: type: integer description: Unix timestamp of last heartbeat ErrorResponse: type: object properties: success: type: boolean error: type: string message: type: string error_code: type: string details: {} responses: UnprocessableEntity: description: Unprocessable Entity content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' InternalServerError: description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' securitySchemes: BearerAuth: type: http scheme: bearer description: Lucid API key (lk_live_... or lk_test_...) ````