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:

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

Response

Example (cURL)


2. Get Verification Status

GET /v1/kyc/status/{session_id}

Check the result of a user’s KYC verification.

Response

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

Response

Example (TypeScript SDK)


4. Fetch Proof Metadata

GET /v1/proof/{wallet}

Get latest proof metadata for a wallet.

Response


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:

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:


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 SDKnpm install @fairway/sdk

  • Python SDK (beta)pip install fairway-sdk

Example:


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.


Last updated

Was this helpful?