# Fairway Cloud Agent API ## Fairway Cloud Agent API > Base URL: `https://api.fairway.global`\ > Version: `v1`\ > Authentication: `Bearer ` in the `Authorization` header.\ > Format: JSON (UTF-8). *** ### Overview The **Fairway Cloud Agent API** lets you integrate **KYC verification, proof generation, and on-chain eligibility publishing** into your own apps and backends. You can: * Trigger user verification sessions. * Query verification results. * Request **ZK-proof generation** on Midnight. * Retrieve **proof metadata** (Merkle root, `midnight_ref`, signature). * Sync compliance state with Cardano or EVM contracts. All responses follow this standard envelope: ```json { "success": true, "data": { ... }, "meta": { "timestamp": "2025-10-08T13:12:00Z" } } ``` *** ### Authentication Every request must include your project API key: ```http Authorization: Bearer YOUR_API_KEY Content-Type: application/json ``` ::: info\ You can generate or rotate keys in the Fairway Developer Console.\ ::: *** ### Endpoints #### 1. Create Verification Session **POST** `/v1/kyc/session` Initiate a new user KYC flow. **Request** ```json { "user_wallet": "addr1qxyz...", "callback_url": "https://yourapp.com/webhook/fairway", "metadata": { "kyc_level": 2, "jurisdiction": "EU" } } ``` **Response** ```json { "success": true, "data": { "session_id": "sess_92f3a1", "redirect_url": "https://verify.fairway.global/session/sess_92f3a1" } } ``` **Example (cURL)** ```bash curl -X POST https://api.fairway.global/v1/kyc/session \ -H "Authorization: Bearer sk_live_xxx" \ -H "Content-Type: application/json" \ -d '{"user_wallet":"addr1qxyz...","callback_url":"https://yourapp.com/webhook"}' ``` *** #### 2. Get Verification Status **GET** `/v1/kyc/status/{session_id}` Check the result of a user’s KYC verification. **Response** ```json { "success": true, "data": { "session_id": "sess_92f3a1", "wallet": "addr1qxyz...", "kyc_verified_at": "2025-10-08T11:45:23Z", "risk_profile_score": 12, "status": "approved" } } ``` Status values: * `pending` — still in progress. * `approved` — verified and ready for proof generation. * `rejected` — failed verification or expired. *** #### 3. Generate Proof (Midnight) **POST** `/v1/proof/generate` Trigger creation of a **Midnight ZK-proof** for a verified user. **Request** ```json { "wallet": "addr1qxyz...", "session_id": "sess_92f3a1", "claims": ["KYC2_OK", "EU_RESIDENT"] } ``` **Response** ```json { "success": true, "data": { "midnight_ref": "0xdeadbeef#0", "kyc_verified_at": "2025-10-08T11:45:23Z", "sanctions_epoch": 452, "fairway_sig": "sig(fairway_key, ...)", "commitment_root": "0xabc123..." } } ``` **Example (TypeScript SDK)** ```ts const proof = await fairway.proofs.generate({ wallet: "addr1qxyz...", session_id: "sess_92f3a1", claims: ["KYC2_OK", "EU_RESIDENT"] }); console.log(proof.midnight_ref); ``` *** #### 4. Fetch Proof Metadata **GET** `/v1/proof/{wallet}` Get latest proof metadata for a wallet. **Response** ```json { "success": true, "data": { "wallet": "addr1qxyz...", "midnight_ref": "0xdeadbeef#0", "sanctions_epoch": 452, "kyc_verified_at": "2025-03-15T10:00:00Z", "risk_profile_score": 17, "status": "active" } } ``` *** #### 5. Webhooks Your app can receive asynchronous events for: | Event | Description | | ------------------ | ------------------------------------------------ | | `kyc.completed` | A user finished KYC verification. | | `proof.generated` | A ZK-proof was generated and posted to Midnight. | | `sanctions.update` | A sanctions epoch increment affected the wallet. | Webhook payload example: ```json { "event": "proof.generated", "data": { "wallet": "addr1qxyz...", "midnight_ref": "0xdeadbeef#0", "sanctions_epoch": 452, "kyc_verified_at": "2025-03-15T10:00:00Z" }, "signature": "sig(fairway_key, ...)" } ``` Verify webhook authenticity with Fairway’s public key from:\ `GET https://api.fairway.global/v1/public-keys` *** ### Rate Limits Default: **60 requests/minute per API key**.\ Bursting and enterprise tiers available — contact . On limit exceeded → HTTP `429 Too Many Requests`. *** ### Errors | Code | Meaning | Typical Cause | | ----- | -------------- | ----------------------------- | | `400` | Bad Request | Missing or invalid parameters | | `401` | Unauthorized | Missing or invalid API key | | `403` | Forbidden | Insufficient permissions | | `404` | Not Found | Unknown session or wallet | | `429` | Rate limited | Too many requests | | `500` | Internal error | Unexpected backend issue | Error example: ```json { "success": false, "error": { "code": 401, "message": "Invalid API key" } } ``` *** ### Security & Compliance Notes * All endpoints use **TLS 1.3+**. * No PII ever leaves your infrastructure — the Agent API works only with hashed and encrypted data. * `kyc_verified_at` and `sanctions_epoch` values are deterministic and audit-friendly. * Webhooks are signed for integrity; always verify before processing. *** ### SDKs * **TypeScript/Node.js SDK** → `npm install @fairway/sdk` * **Python SDK (beta)** → `pip install fairway-sdk` Example: ```ts import { FairwayClient } from "@fairway/sdk"; const fairway = new FairwayClient({ apiKey: process.env.FAIRWAY_KEY }); const session = await fairway.kyc.createSession({ wallet: "addr1qxyz...", callback_url: "https://yourapp.com/webhook" }); ``` *** ### Next Steps * See Decentralized Vaults → how KYC data is stored off-chain. * Explore Midnight ZK Proofs → how proofs are generated and linked cross-chain. * Implement Webhook Handlers → to sync proof events. * Read Build on Cardano or Build on EVM for on-chain integration. *** --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.fairway.global/developers/apis-and-sdks/fairway-cloud-agent-api.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.