> For the complete documentation index, see [llms.txt](https://docs.fairway.global/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fairway.global/developers/apis-and-sdks/fairway-cloud-agent-api.md).

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

```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 <support@fairway.global>.

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.

***