Fairway Cloud Agent API

Fairway Cloud Agent API

Base URL: https://api.fairway.global Version: v1 Authentication: Bearer <API_KEY> 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:

{
  "success": true,
  "data": { ... },
  "meta": { "timestamp": "2025-10-08T13:12:00Z" }
}

---

Authentication

Every request must include your project API key:

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

{
  "user_wallet": "addr1qxyz...",
  "callback_url": "https://yourapp.com/webhook/fairway",
  "metadata": {
    "kyc_level": 2,
    "jurisdiction": "EU"
  }
}

Response

{
  "success": true,
  "data": {
    "session_id": "sess_92f3a1",
    "redirect_url": "https://verify.fairway.global/session/sess_92f3a1"
  }
}

Example (cURL)

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

{
  "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

{
  "wallet": "addr1qxyz...",
  "session_id": "sess_92f3a1",
  "claims": ["KYC2_OK", "EU_RESIDENT"]
}

Response

{
  "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)

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

{
  "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:

{
  "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 [email protected].

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:

{
  "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:

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.

---