# Bind an agent
Source: https://docs.air3.com/api-reference/agents/bind-agent-key

api-reference/agent-openapi.json POST /v2/auth/agent/keys/partner
Registers an agent key for the holder authenticated by the partner access
token. Call this once per agent. `publicKey` is optional; omit it for
API-key-only agents.

`agentApiKey` is returned **once**. Store it on your backend.




# Create an agent session
Source: https://docs.air3.com/api-reference/agents/create-agent-session

api-reference/agent-openapi.json POST /v2/auth/agent/session
Issues a **15-minute** access token (`type=agent`) with no refresh token.
Create one per operation.

Identify the agent with **exactly one** of the `x-agent-api-key` header or
the body `signedMessage`. API-key-only agents must use the header.
`signedMessage` requires a public key stored at bind time.

The requested `scope` must be a subset of the bound key's scopes; omit it
to receive the full bound set. Tokens issued before a key rotation fail.




# Create a checkout session
Source: https://docs.air3.com/api-reference/agents/create-checkout-session

api-reference/agent-openapi.json POST /v2/auth/agent/checkout-session
Issues a short-lived access token (`type=agent`) for a merchant checkout.
No refresh token. The bound key must include `commerce.checkout`.

Identify the agent with **exactly one** of the `x-agent-api-key` header or
the body `signedMessage`.

The request `scope` names the merchant checkout target, not an agent
scope. `pivota.checkout` is currently the only supported value. The JWT's
`scope` equals the requested value, and its `aud` is the merchant mapped to
that target. The JWT includes the holder's abstract account address.

AIR and Credential APIs reject this token because of the audience. The
merchant must verify `aud`.




# Agent APIs
Source: https://docs.air3.com/api-reference/agents/introduction

Bind an agent to an AIR Account, mint short-lived agent JWTs, list and verify the holder's credentials, and mint merchant checkout tokens.

The Agent APIs let your backend act for a holder, the signed-in user, through a bound agent. You bind an agent once, then mint a short-lived agent JWT for each operation and use it to list or verify the holder's credentials. If the agent's key includes checkout, you can also mint a token for a merchant checkout.

For a step-by-step walkthrough with request examples, see the [Using Agentic Identity](/products/agents/partner-agent-api). Get the user's approval before you bind an agent; the bind request has no approval step of its own. See [Ask for consent before binding](/products/agents/delegation-and-consent#ask-for-consent-before-binding).

## Base URLs

The Agent APIs span two hosts. Use the pair for the same environment.

| Environment | AIR API (keys, session, checkout) | Credential API (list, verify) |
| - | - | - |
| Sandbox | `https://air.api.sandbox.air3.com` | `https://credential-testnet.api.sandbox.air3.com` |
| Production | `https://air.api.air3.com` | `https://credential-mainnet.api.air3.com` |

<Note>
  Agent keys must be enabled for your partner account. Otherwise, AIR API calls return `403 AGENT_KEYS_DISABLED`. Contact the AIR team to enable agent keys and confirm which environment is available for your integration.
</Note>

## Authentication

Each route uses a different combination of headers.

| Header | Value | Used by |
| - | - | - |
| `x-partner-id` | Your Partner ID from the Developer Dashboard | All key routes and session creation |
| `x-partner-access-token` | The holder's AIR Kit partner access token from `airService.getAccessToken()` | All key routes |
| `x-partner-jwt` | A JWT signed with your partner login key | Bind, rotate, and revoke |
| `x-agent-api-key` | The `air_ag_…` key returned at bind or rotate | Session and checkout creation |
| `Authorization: Bearer` | The agent JWT from session creation | List and verify credentials |

Sign `x-partner-jwt` on your backend with the same key you use for AIR Kit login. Its `partnerId` must match `x-partner-id` and the holder's session. See [SDK authentication](/get-started/authentication/sdk-auth) for key setup.

Session and checkout creation accept exactly one agent identity: the `x-agent-api-key` header, or a `signedMessage` in the body for agents bound with a P-256 public key.

<Warning>
  Treat `agentApiKey` and `x-partner-jwt` as backend secrets. Never send them to a browser or embed them in page JavaScript.
</Warning>

## Scopes

Bind an agent with a space-delimited `scope`. AIR adds `openid` automatically.

| Scope | Allows |
| - | - |
| `credentials.read` | List the holder's credentials. |
| `credentials.verify` | Verify the holder's credentials against a program. |
| `commerce.checkout` | Mint a merchant checkout token. |

Partner bind cannot include `wallet.sign`. A session can request a subset of the bound scopes; omit `scope` to receive all of them.

## Tokens and key lifecycle

| Item | Lifetime | Notes |
| - | - | - |
| `agentApiKey` | Until rotated or revoked | Returned only at bind and rotate. |
| Agent JWT | 15 minutes | No refresh token. Create a new session for each operation. |
| Checkout JWT | Short-lived | Its `aud` is the merchant. AIR and Credential APIs reject it. |

Rotating a key returns a new `agentApiKey` and invalidates agent JWTs already issued for that key. Revoking a key stops new sessions for it.

## Errors

Errors return a JSON body with a machine-readable `code` and a `message`.

| Status | AIR API | Credential API |
| - | - | - |
| `400` | Invalid request, for example a missing `scope` | Invalid query or body |
| `401` | Missing or invalid partner session, partner JWT, or agent identity | Missing or invalid bearer token |
| `403` | Agent keys disabled, requested scope not a subset of the bound key, or `wallet.sign` on a partner route | User JWT on verify, or agent JWT missing the required scope |
| `404` | Agent key not found | — |
| `409` | Maximum agent keys per user reached | — |
| `502` | — | Credential storage unavailable |

AIR API codes: `INVALID_PARAMETER`, `UNAUTHORIZED`, `INVALID_TOKEN`, `AGENT_KEYS_DISABLED`, `AGENT_SCOPE_DENIED`, `AGENT_SCOPED_SESSION_DISABLED`, `CONFLICT_REQUEST`, `NOT_FOUND`, and `INTERNAL_SERVER_ERROR`.

Credential API codes: `INVALID_PARAMETER`, `UNAUTHORIZED`, `FORBIDDEN`, `CREDENTIAL_STORAGE_UNAVAILABLE`, and `VERIFICATION_PROGRAM_NOT_FOUND`.

A `502 CREDENTIAL_STORAGE_UNAVAILABLE` on verify means storage could not be read. It does not mean the holder lacks the credential; that case returns `200` with `status: "NotFound"`.

## Endpoints

<CardGroup>
  <Card title="Bind an agent" icon="link" href="/api-reference/agents/bind-agent-key">
    Register an agent for the holder and receive its API key once.
  </Card>

  <Card title="Create an agent session" icon="key" href="/api-reference/agents/create-agent-session">
    Mint a 15-minute agent JWT.
  </Card>

  <Card title="List credentials" icon="list" href="/api-reference/agents/list-credentials">
    Page through the holder's credentials with optional filters.
  </Card>

  <Card title="Verify a credential" icon="badge-check" href="/api-reference/agents/verify-credential-by-agent">
    Run a verification program and receive a presentation when compliant.
  </Card>

  <Card title="Create a checkout session" icon="cart-shopping" href="/api-reference/agents/create-checkout-session">
    Mint a token for a supported merchant checkout.
  </Card>

  <Card title="Manage agent keys" icon="gear" href="/api-reference/agents/list-agent-keys">
    List, rename, rotate, and revoke bound agents.
  </Card>
</CardGroup>


# List bound agents
Source: https://docs.air3.com/api-reference/agents/list-agent-keys

api-reference/agent-openapi.json GET /v2/auth/agent/keys/partner
Keys this partner bound for the holder identified by the partner access
token. Unbound keys and other partners' keys are omitted. `agentApiKey` is
never returned here.




# List credentials
Source: https://docs.air3.com/api-reference/agents/list-credentials

api-reference/agent-openapi.json GET /v2/credentials
Cursor-paginated list of the authenticated holder's credentials. Agent JWTs
need `credentials.read`. A holder user JWT also works.

Filters are repeatable. `vct` also accepts a comma-separated list (except
for `http(s)` URLs). Filters on different fields are combined as an
intersection.




# Revoke an agent key
Source: https://docs.air3.com/api-reference/agents/revoke-agent-key

api-reference/agent-openapi.json DELETE /v2/auth/agent/keys/partner/{id}
Removes the agent key. After revocation, session requests with that API key
(or its public key) fail. `wallet.sign` keys cannot be revoked on this path.




# Rotate an agent API key
Source: https://docs.air3.com/api-reference/agents/rotate-agent-key

api-reference/agent-openapi.json POST /v2/auth/agent/keys/partner/{id}/rotate
Issues a new `agentApiKey` (returned once), increments the key's token
version, and invalidates agent JWTs already issued for it. `wallet.sign`
keys cannot be rotated on this path.




# Update an agent nickname
Source: https://docs.air3.com/api-reference/agents/update-agent-key-nickname

api-reference/agent-openapi.json PATCH /v2/auth/agent/keys/partner/{id}
Letters, numbers, spaces, hyphens, and colons; maximum 32 characters. An
empty string clears the nickname. Does not require `x-partner-jwt`.




# Verify a credential
Source: https://docs.air3.com/api-reference/agents/verify-credential-by-agent

api-reference/agent-openapi.json POST /v2/credentials/verify-by-agent
Runs a verification program against the holder's credentials. Requires an
agent JWT with `credentials.verify`; user JWTs are rejected. Verification
always runs offchain, without a zero-knowledge proof.

`status` is `Compliant`, `Non-Compliant`, or `NotFound`.
`verifiablePresentation` is present only when the status is `Compliant`.

A storage outage returns `502 CREDENTIAL_STORAGE_UNAVAILABLE`, not
`NotFound`.




# API Reference
Source: https://docs.air3.com/api-reference/introduction

Moca Network REST API reference — server-to-server endpoints for credential issuance, issuance status, and partner operations.

The Moca Network REST API enables server-to-server operations that do not require user presence. Use it for backend automation, credential issuance into encrypted DStorage, and programmatic status checks. Issuers sign credentials with their own keys and encrypt them to the holder; AIR stores and routes opaque ciphertext and metadata only.

## Base URLs

| Environment | Base URL |
| - | - |
| Sandbox | `https://api.sandbox.mocachain.org/v1` |
| Production | `https://mocachain-mainnet.api.air3.com/v1` |

## Authentication

Authentication depends on the credential surface:

* Direct AIR endpoints (`initialize-user` and `dstorage/vcs`) use a **Partner JWT** in `x-partner-auth`.
* Your issuer backend protects `available-vc` and `issue-vc` with `x-api-key`.
* Public credential-status endpoints do not require authentication.
* Self-hosted admin endpoints use `x-admin-api-key`.

For direct AIR endpoints, sign the Partner JWT with your private key (RS256 or ES256) and include:

| Claim | Required | Description |
| - | - | - |
| `partnerId` | Yes | Your Partner ID from the Developer Dashboard |
| `scope` | Yes | Operation scope (e.g. `"issue"` or `"verify"`) |
| `exp` | Yes | Expiration timestamp (recommended: 5 minutes) |

For on-demand issuance, do not put the recipient email in the Partner JWT. Send it in the `POST /auth/initialize-user` request body instead. Other operations, such as custom user authentication, have their own claim requirements.

The JWT header must include `kid` (Key ID) matching a key in your JWKS endpoint and `typ: "JWT"`.

For full setup instructions, key generation, and code examples see [SDK authentication](/get-started/authentication/sdk-auth).

**API Playground:** Requests from the Try it out playground are sent directly from your browser to the API. Your API must allow CORS from your docs origin (e.g. your Mintlify subdomain or custom domain) for the playground to work. If you see 403 from the playground, check that the API allows the request origin and that your Partner JWT is valid.

## Credentials

On-demand credential issuance resolves the recipient and stores an issuer-signed, holder-encrypted credential in DStorage. See the [Issuance API Reference](/api-reference/issuance-api) for the `initialize-user` and `dstorage/vcs` endpoints, request and response details, and code examples.

## Agent APIs

The Agent APIs use their own hosts and authentication. They let your backend bind an agent to a user's AIR Account, mint short-lived agent JWTs, list and verify the user's credentials, and mint merchant checkout tokens.

<Card title="Agent APIs" icon="robot" href="/api-reference/agents/introduction">
  Base URLs, authentication, scopes, and endpoints for partner-bound agents.
</Card>

## Code examples

For end-to-end integration examples including issue-and-poll flows, webhook-driven issuance, and retry logic, see [Issuance API Reference](/api-reference/issuance-api).


# Issuance API Reference
Source: https://docs.air3.com/api-reference/issuance-api

AIR credential issuance API reference: the AIR API endpoints for initializing accounts and storing encrypted VCs, and the endpoints your issuer service hosts.

* Read concepts first: [Issuing Credentials](/products/identity/issuing-credentials)
* For JWT/JWKS setup and signing examples, see [SDK authentication](/get-started/authentication/sdk-auth).

This page covers two separate surfaces. Do not mix their base URLs or authentication headers.

| Surface | Base URL | Who calls it | Authentication |
| - | - | - | - |
| [AIR API](#air-api) | `{AIR_API_BASE_URL}` | Your backend | `x-partner-auth: <Partner JWT>` |
| [Your issuer service](#your-issuer-service): holder-facing routes | `{ISSUER_ORIGIN}` | AIR, during SDK issuance | `x-api-key: <API_KEY>` |
| [Your issuer service](#your-issuer-service): admin routes | `{ISSUER_ORIGIN}` | Your own servers only | `x-admin-api-key: <ADMIN_API_KEY>` |
| [Your issuer service](#your-issuer-service): public routes | `{ISSUER_ORIGIN}` | Verifiers and AIR | None |

# AIR API

## AIR API base URL

This base URL applies only to the AIR-hosted endpoints on this page — `POST /auth/initialize-user` and `POST /dstorage/vcs` — shown below as `{AIR_API_BASE_URL}`.

| Environment | Base URL |
| - | - |
| Sandbox | `https://api.sandbox.mocachain.org/v1` |
| Production | `https://mocachain-mainnet.api.air3.com/v1` |

<Note>
  `/available-vc`, `/issue-vc`, `/admin/*`, and the status endpoints are hosted on your issuer service under its public `ISSUER_ORIGIN`. You never call the AIR API base URL for them.
</Note>

<Note>
  Moca Chain mainnet is live. Production SD-JWT issuers register in the [production Developer Dashboard](https://developers.air3.com/dashboard); see [Production mainnet access](/get-started/environments/about#production-mainnet-access).
</Note>

## Authentication

Direct AIR API requests for direct issuance use a Partner JWT sent in the `x-partner-auth` header. The JWT must include the partner identity, at minimum `partnerId`, and for issuance flows should be scoped for issuance, e.g. `scope: "issue"` where required by the endpoint. The JWT should be signed with the partner’s private key and verifiable through the configured JWKS endpoint; its header should include `kid` matching the JWKS key and `typ: "JWT"`. For the newer `initialize-user` flow, the recipient/user identifier, typically `email`, is passed in the `initialize-user` request body, and the returned DID/public key are then used when storing the encrypted VC through `/dstorage/vcs`.

Your issuer service uses its own keys, described in [Your issuer service](#your-issuer-service). They are never sent to the AIR API.

## Issuance surfaces

There are two issuance patterns. In both cases, the issuer controls the signing keys and the resulting encrypted credential is stored in DStorage.

* **Hosted SDK issuance** — holder present. Your frontend calls `air.issueCredential(...)`. AIR resolves the authenticated holder and calls your registered issuer backend's `POST /available-vc` to retrieve an encrypted credential-subject preview. After the holder confirms, AIR calls `POST /issue-vc`. The issuer backend generates the authoritative claims, signs the VC, encrypts it to the holder's public key, persists the issuance record, and uploads the envelope to DStorage.
* **Direct issuance** — no holder interaction. The recipient is resolved by email with `POST /auth/initialize-user`, the VC is issuer-signed and encrypted to the returned holder public key, and the envelope is stored through `POST /dstorage/vcs`. The SD-JWT issuer service wraps these steps in `POST /admin/issue-vc` (see [Admin endpoints](#4-admin-endpoints-called-by-your-servers)). You can also call the two AIR API endpoints yourself.

## 1) Initialize or resolve an AIR account

Resolve or create the recipient’s AIR Account using their email address, and return the AIR user UUID, holder DID, and public key required for direct issuance.

```text theme={null}
POST {AIR_API_BASE_URL}/auth/initialize-user
```

### Request headers

| Header | Required | Value |
| - | - | - |
| `Content-Type` | Yes | `application/json` |
| `x-partner-auth` | Yes | Signed Partner JWT |

### Request body

```json theme={null}
{
  "email": "user@example.com"
}
```

| Field | Type | Required | Description |
| - | - | - | - |
| `email` | string | Yes | The individual recipient's AIR Account email. AIR uses this value to resolve or create the destination account. Do not use a partner, service, admin, or shared email address. |

### Response

```json theme={null}
{
  "userId": "7f01c42c-02cf-4325-96ed-ba034700f724",
  "did": "did:air:id:test:5P44fsVUhPctDTWH2Nz26pZJFsg6CqyiAELTGeVQDB",
  "publicKey": "0x04a1..."
}
```

| Field | Description |
| - | - |
| `userId` | AIR user UUID for the resolved or newly created AIR account. This is not necessarily the same identifier as the partner primary `userId` supplied to issuer-hosted endpoints. |
| `did` | Holder DID used as `holderDid` when storing the credential |
| `publicKey` | Holder public key; encrypt the VC payload to this key |

## 2) Store encrypted VC

Store an encrypted VC envelope in DStorage. Before calling this endpoint, the issuer must build and sign the VC, then encrypt the complete signed credential to the holder’s public key returned by `initialize-user`.
AIR and DStorage receive the encrypted envelope and do not construct or sign the credential.

```text theme={null}
POST {AIR_API_BASE_URL}/dstorage/vcs
```

### Request headers

| Header | Required | Value |
| - | - | - |
| `Content-Type` | Yes | `application/json` |
| `x-partner-auth` | Yes | Signed Partner JWT |

### Request body

```json theme={null}
{
  "holderDid": "did:air:id:test:5P44fsVUhPctDTWH2Nz26pZJFsg6CqyiAELTGeVQDB",
  "schemaId": "c21s70g0i54sn0023172Cv",
  "expiresAt": "2027-07-28T08:00:00.000Z",
  "data": "<base64 ciphertext>",
  "iv": "<base64 initialization vector>",
  "authTag": "<base64 authentication tag>",
  "encryptedKey": "<base64 ephemeral public key>",
  "externalId": "urn:uuid:7f01c42c-02cf-4325-96ed-ba034700f724"
}
```

| Field | Type | Required | Description |
| - | - | - | - |
| `holderDid` | string | Yes | Holder DID from `initialize-user` |
| `schemaId` | string | Yes | Schema the credential is built on |
| `expiresAt` | ISO 8601 string | Yes | Credential expiration time |
| `data` | base64 string | Yes | Encrypted, issuer-signed VC |
| `iv` | base64 string | Yes | AES-GCM initialization vector |
| `authTag` | base64 string | Yes | AES-GCM authentication tag |
| `encryptedKey` | base64 string | Yes | Ephemeral data-encryption public key |
| `externalId` | string | Yes | Stable issuer-controlled unique identifier for this credential. Reuse the same value when retrying the same storage operation; do not generate a new value for each transient retry. |

### Response 201

```json theme={null}
{
  "storagePath": "dstorage://vc/7f01c42c/c28t30c048pe502a3713w0",
  "state": "...",
  "envelopeVersion": "...",
  "createdAt": "2026-08-26T12:37:19.000Z"
}
```

# Your issuer service

These routes run on your own issuer service at its public `ISSUER_ORIGIN`, not on the AIR API. The examples follow the SD-JWT branch of the [AIR issuer service](https://github.com/MocaNetwork/air-issuer-service/tree/main). Iden3 issuers use a separate branch; see [Iden3 credentials](/products/identity/iden3-credentials).

## 3) Holder-facing endpoints (called by AIR)

Your issuer service exposes `POST /available-vc` and `POST /issue-vc` for hosted SDK issuance. AIR—not the browser—calls these registered endpoints with the holder identity resolved through the authenticated AIR session.

Both endpoints require:

```http theme={null}
Content-Type: application/json
x-api-key: <issuerBackendApiKey>
```

Configure the same key as `API_KEY` in the issuer service and register it with AIR during issuer activation. These routes are hosted under your issuer backend’s public `ISSUER_ORIGIN`, not under the AIR API base URL.

Do not authorize issuance or retrieve claims from `holderDID` alone. Use the AIR-resolved partner primary `userId` to look up the holder’s eligibility and authoritative claims in your own systems. Do not assume this value is interchangeable with the AIR user UUID returned by `initialize-user`.

### `POST {ISSUER_ORIGIN}/available-vc`

Return credentials the holder can claim. `schemaId` and `proofType` are optional filters. AIR calls this endpoint during hosted SDK issuance to discover credentials available to the authenticated holder. The issuer backend validates eligibility using `userId`, generates authoritative claims, encrypts the preview to `pubKey`, and returns it to AIR.

<Note>
  `schemaId` is a credential schema ID—not the Dashboard issuance program ID
</Note>

```json theme={null}
{
  "holderDID": "did:air:id:test:5P44fsVUhPctDTWH2Nz26pZJFsg6CqyiAELTGeVQDB",
  "pubKey": "0x04a1...",
  "userId": "partner-user-123",
  "schemaId": "c21s70g0i54sn0023172Cv",
  "proofType": "SD_JWT_VC"
}
```

| Field | Type | Required | Description |
| - | - | - | - |
| `holderDID` | string | Yes | Holder DID |
| `pubKey` | string | Yes | Holder public key used to encrypt each credential subject preview |
| `userId` | string | Yes | Partner primary identifier |
| `schemaId` | string | No | Return only this schema |
| `proofType` | string | No | Return only this proof type. The SD-JWT issuer service issues `SD_JWT_VC`; the Iden3 issuer service issues `BJJ_SIG_2021` |

Response:

```json theme={null}
{
  "data": [
    {
      "holderDID": "did:air:id:test:5P44fsVUhPctDTWH2Nz26pZJFsg6CqyiAELTGeVQDB",
      "schemaId": "c21s70g0i54sn0023172Cv",
      "credentialSubject": {
        "encryptedData": "<base64 ciphertext>",
        "iv": "<base64 initialization vector>",
        "authTag": "<base64 authentication tag>",
        "dataEncPublicKey": "<base64 ephemeral public key>"
      },
      "proofType": "SD_JWT_VC"
    }
  ]
}
```

### `POST {ISSUER_ORIGIN}/issue-vc`

AIR calls this endpoint after the holder confirms hosted issuance. The issuer backend regenerates or retrieves the authoritative claims, signs the complete VC, encrypts it to `pubKey`, persists the issuance record, uploads the encrypted envelope to DStorage, and returns HTTP `201` with an empty body.

```json theme={null}
{
  "holderDID": "did:air:id:test:5P44fsVUhPctDTWH2Nz26pZJFsg6CqyiAELTGeVQDB",
  "pubKey": "0x04a1...",
  "userId": "partner-user-123",
  "schemaId": "c21s70g0i54sn0023172Cv",
  "signingKey": { "jwk": { "kty": "EC", "crv": "P-256", "x": "...", "y": "..." } },
  "proofType": "SD_JWT_VC"
}
```

| Field | Type | Required | Description |
| - | - | - | - |
| `holderDID` | string | Yes | Holder DID |
| `pubKey` | hexadecimal string | Yes, unless `encryptionKey` is supplied | Holder public key used to encrypt the complete issued credential |
| `encryptionKey` | hexadecimal string | No | Alternative to `pubKey`. If both are present, `encryptionKey` is used for encryption |
| `signingKey` | object | No | `{ "jwk": { ... } }` holder public key. The SD-JWT issuer service writes it to the credential's `cnf` claim, binding the credential to the holder |
| `userId` | string | Yes | Partner primary identifier |
| `schemaId` | string | Yes | Schema to issue |
| `proofType` | string | No | `SD_JWT_VC` on the SD-JWT issuer service, `BJJ_SIG_2021` on the Iden3 issuer service. Each service rejects the other value |

On success, the endpoint returns `201` with an empty response body. The issuer backend uploads the encrypted credential and stores the DStorage response internally; callers should not expect a `storagePath` in this response. A missing or mismatched `x-api-key` on either issuer-hosted endpoint returns `403`, not `401`.

## 4) Admin endpoints (called by your servers)

Admin routes require `x-admin-api-key: <ADMIN_API_KEY>`. Call them only from your own servers; never from a browser or through AIR.

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/admin/issue-vc` | Issue directly to a user by email, without a user session |
| `POST` | `/admin/revoke` | Revoke a credential by its `revocationNonce`. See [Revoke credentials](/products/identity/revocation) |
| `GET` | `/admin/issuance-history` | Paginated issuance history (`page`, `limit`, `order`, `holderDid`, `schemaId`, `revocationNonce`) |
| `POST` | `/admin/publish-token-status-list` | Rebuild and publish status list partitions, when the [token status list](/products/identity/revocation#token-status-list) is enabled |

### `POST {ISSUER_ORIGIN}/admin/issue-vc`

Resolves the holder through AIR `initialize-user`, signs the SD-JWT VC, encrypts it to the holder, and uploads it to DStorage. No registered schema class is needed.

```json theme={null}
{
  "userId": "member@example.com",
  "schemaId": "c21s70g0i54sn0023172Cv",
  "vct": "c21s70g0i54sn0023172Cv",
  "expiration": "2030-01-01T00:00:00Z",
  "credentialSubject": { "tier": "Gold" },
  "disclosureFrame": { "_sd": ["tier"] }
}
```

| Field | Type | Required | Description |
| - | - | - | - |
| `userId` | string | Yes | The email AIR knows the user by |
| `schemaId` | string | Yes | Schema the credential is built on |
| `vct` | string | Yes | Credential type |
| `expiration` | ISO 8601 string | Yes | Must be in the future |
| `credentialSubject` | object | Yes | Claims. Must not contain `cnf`, `exp`, `iat`, `id`, `iss`, `nonce`, `status`, `sub`, `vct`, or `vct#integrity` |
| `disclosureFrame` | object | No | Selectively disclosable claims. Defaults to every top-level claim |

Credentials issued this way have no `cnf` holder key.

## 5) Public endpoints (called by verifiers)

These routes do not require an API key. `ISSUER_ORIGIN` must be the stable public HTTPS origin of the issuer service, without a trailing slash. For SD-JWT issuers it also defines the issuer DID (`did:web:<host>`), so changing it changes your issuer identity.

| Endpoint | Purpose | Response |
| - | - | - |
| `GET /.well-known/did.json` | Issuer `did:web` document with the keys that verify your credentials | DID document |
| `GET /.well-known/jwt-vc-issuer` | SD-JWT VC issuer metadata | `{ issuer, jwks }` |
| `GET /.well-known/air-partner-info` | Partner info referenced from the DID document | `{ partnerId }` |
| `GET /revocation-status/:nonce` | Check whether a credential has been revoked | `{ "isRevoked": boolean }` |
| `GET /statuslist/:partition` | Signed token status list partition, when enabled | `application/statuslist+jwt` |

The Iden3 issuer service also serves `GET /credential-status/:nonce`, which returns the non-revocation Merkle proof and issuer tree state. See [Iden3 credentials](/products/identity/iden3-credentials).

Example revocation status response:

```json theme={null}
{
  "isRevoked": false
}
```

## Error reference

| HTTP status | Likely cause | Suggested fix |
| - | - | - |
| 400 | Missing/invalid request fields | Verify `email`, `holderDid`, `schemaId`, and all encrypted payload fields |
| 401 | Invalid/expired JWT, JWKS mismatch | Validate signature, `kid`, `typ: "JWT"`, token expiry |
| 403 | Feature not enabled or schema not allowed | Enable feature in dashboard, verify schema ownership |
| 404 | Unknown issuer/program/user | Recheck IDs and recipient email in dashboard |
| 409 | Consent rejected / conflict | Check user consent and duplicate handling |
| 500 | Server-side failure | Retry with backoff and inspect logs |

## Troubleshooting

* If `dstorage/vcs` succeeds, record the `storagePath`; the credential is available for the holder to present to any AIR verifier.
* If AIR never calls `/available-vc` or `/issue-vc`, confirm that the Issuer DID, Partner ID, API key, and both public endpoint URLs have been registered and activated by AIR.
* For authentication errors, verify the JWT contains `partnerId` and `scope: "issue"` (not the recipient email), and that the header includes `typ: "JWT"`.
* Ensure your JWKS endpoint is public and `kid` maps to the signing key.
* The SDK’s `credentialId` is the Dashboard issuance program ID. The issuer backend receives `schemaId`. Passing one in place of the other can result in “schema not found” or routing failures.


# Migration & Compatibility
Source: https://docs.air3.com/api-reference/migration-compatibility

Browser, Node.js, and framework compatibility requirements for AIR Kit and AIR Kit Connector packages — including passkey support and migration notes.

## Browser Compatibility

### Minimum Requirements

Due to passkey authentication requirements, AIR Kit requires:

**Minimum Supported Versions:**

* **iOS**: 16+
* **Android**: 10+
* **Safari**: 16+
* **Chromium**: 126+
* **Firefox**: 97+

**Required Features:**

* Passkey support (WebAuthn)
* Iframe support
* PostMessage API
* ES6+ JavaScript support

## Package Compatibility

### AIR Kit (`@mocanetwork/airkit`)

**Distribution Formats:**

* **ESM**: `dist/airkit.esm.js` (ES6 modules)
* **CommonJS**: `dist/airkit.cjs.js` (ES5 format)
* **UMD**: `dist/airkit.umd.min.js` (browser use)

**Requirements:**

* Node.js >=18.x
* npm >=9.x

### AIR Kit Connector (`@mocanetwork/airkit-connector`)

**Peer Dependencies:**

* `@wagmi/core` ^2.x
* `viem` ^2.x

**Requirements:**

* Node.js >=18.x
* npm >=9.x

## Framework Support

**Framework-Agnostic Design:**
Since AIR Kit spawns iFrames to run the wallet and UI, it should work with most JavaScript frameworks. The SDK communicates and provides an EIP-1193 provider interface, making it compatible with:

* React
* Next.js
* Vue
* Angular
* Svelte
* SolidJS
* And other modern JavaScript frameworks


# Release Notes
Source: https://docs.air3.com/api-reference/release-notes

AIR Kit SDK release notes — version history, new features, breaking changes, deprecations, and migration notes for partners upgrading their integration.

## **Version 1.12.1 (Sep 16, 2026)**

### ✨ **New Features**

* **Japanese, Vietnamese, and Turkish UI localization** — the SDK UI now ships `ja`, `vi`, and `tr` catalogs alongside existing locales. They are picked up automatically via `sessionConfig.locale` or browser language detection; no partner action needed unless you restrict `supportedLocales`
* **Scoped agent keys** — `registerAgentKey` now accepts an OAuth `scope`, so you can bind credential-only agent keys without a signing key. `AgentPublicKey` now returns optional `scope` and `nickname` fields, and `getAgentKeys` returns the same enriched shape
* **Optional `nonce` for SD-JWT verification** — `nonce` is no longer required for `SD_JWT_VC` programs. Omit it to skip the key-binding JWT entirely; when supplied, a KB-JWT is attached only if the issuer JWT carries `cnf.jwk` — see [Verifying credentials](/products/identity/verify)
* **Nested selective disclosure for SD-JWT** — `fieldsToDisclose` now accepts dotted claim paths (e.g. `address.city`) to disclose nested claims on `SD_JWT_VC` programs
* **Issuer revocation checks** — verification programs can enable issuer-revocation checking; revoked credentials are excluded from verification and a `Revoked` result is returned when every matching credential is revoked

### ➕ **Improvements**

* More reliable SDK initialization and popup flows — the iframe/popup handshake was unified, eliminating missed-announcement failures during init
* Faster first load — improved build chunking, deferred loading, and preloading of the credential flow
* Wallet actions now validate the session first — fixes users appearing logged in after their tokens were deleted (e.g. clicking "Deploy Smart Account" with an expired session)
* Recovery and PIN signature payloads now include a timestamp for replay protection
* Credential holder signatures now use ERC-7739 typed-data signing — relevant if you verify holder signatures server-side
* New `CHANNEL_CLOSED` error name, thrown when the user closes a popup or the messaging channel closes mid-flow — handle it alongside `USER_CANCELLED` if you switch on error names

### 📋 **Migration Guide**

**SD-JWT nonce is now optional:**

```js theme={null}
  // Before (1.11.x) — nonce required for SD_JWT_VC programs
  await airService.verifyCredential({ programId, fieldsToDisclose, nonce });

  // After (1.12.x) — omit nonce to skip the KB-JWT
  await airService.verifyCredential({ programId, fieldsToDisclose });

  // Nested claims via dotted paths
  await airService.verifyCredential({
    programId,
    fieldsToDisclose: ["address.city", "age"],
  });
```

<Note>
  When nonce is omitted, the compliant presentation's `verifiableCredential[0]` is `<Issuer-JWT>~<disclosures>~` with no KB-JWT segment — update verifier-side parsing if you assumed three segments.
</Note>

## **Version 1.11.1 (Aug 13, 2026)**

<Note>
  `1.11.1` is a patch over `1.11.0` with no SDK behavior changes between them. Everything below landed in the 1.11 line — upgrade directly from `1.10.0` to `1.11.1`.
</Note>

### ✨ **New Features**

* **W3C Verifiable Presentation on every compliant verification** — `verifyCredential` now returns the disclosed claims and any proof material on `verifiablePresentation` — see [Verifying credentials](/products/identity/verify#response)
* **SD-JWT VC verification** — verification programs can use the `SD_JWT_VC` proof type. These programs require both `fieldsToDisclose` and the new `nonce` parameter
* **`IDEN3` proof type** available for verification programs alongside `BJJ_SIG_2021`
* Verification programs with multiple ZK queries return one proof per query on `verifiablePresentation.proof`

### ➕ **Improvements**

* Google login now works in mobile in-app browsers and Android Custom Tabs via a server-side redirect fallback
* The SDK removes its transient `airkit_handoff` and `airkit_login_error` parameters from your page URL after login, so a page refresh cannot replay a consumed one-time code
* The partner linking confirmation screen is removed from login, reducing steps for new users
* Improved session cleanup when a user requests account deletion
* Package license changed from MIT to Apache 2.0

### ⚠️ **Breaking Changes**

* **`AirUserDetails.partnerUserId` is removed.** AIR no longer stores partner-local user IDs — key off the AIR user UUID (`user.id`) and keep the join in your own system.
* **`verifyCredential` no longer accepts `offchain`.** Off-chain versus on-chain mode is configured on the verification program in the Developer Dashboard.
* **`zkProofs`, `transactionHash`, and `disclosedData` are deprecated and no longer populated** on compliant verification results. Read `verifiablePresentation` instead.

### 📋 **Migration Guide**

**Reading verification results:**

```js theme={null}
// Before (1.10.0 and earlier)
if (result.status === "Compliant") {
  console.log(result.transactionHash);
  console.log(result.zkProofs);
  console.log(result.disclosedData.credentialSubject);
}

// After (1.11.x)
if (result.status === "Compliant") {
  const vp = result.verifiablePresentation;

  // Disclosed claims live on the embedded credential
  const [credential] = vp?.verifiableCredential ?? [];
  if (credential && typeof credential !== "string") {
    console.log(credential.credentialSubject);
  }

  // proof is present only when the program requires a ZKP
  const proof = Array.isArray(vp?.proof) ? vp.proof[0] : vp?.proof;
  console.log(proof?.transactionHash); // on-chain programs only
  console.log(proof?.proofValue);
}
```

<Warning>
  When a verification program is not configured to require a zero-knowledge proof, the presentation has **no `proof` block** — it is unsigned and carries no cryptographic guarantee. In that case the verification session status is the only trust anchor. Ask the verifier owner to enable the ZKP requirement if you need an attested result.
</Warning>

For `SD_JWT_VC` programs, `verifiableCredential[0]` is a compact string rather than an object, and both `fieldsToDisclose` and `nonce` are required on the call. See [Verifying credentials](/products/identity/verify).

**Replacing `partnerUserId`:**

```js theme={null}
const { user } = await airService.getUserInfo();
// Persist the AIR user UUID against your own user record
await db.users.update(localUserId, { airUserId: user.id });
```

***

## **Version 1.10.0 (June 11, 2026)**

### ✨ **New Features**

* Program-driven verification modes — proof type, ZKP requirement, and off-chain / on-chain mode configured centrally — see [Issuing credentials](/products/identity/issuing-credentials) and [Verifying credentials](/products/identity/verify)
* Selective and full data disclosure on verify (`fieldsToDisclose`) — see [Selective Disclosure](/products/identity/selective-disclosure)
* In-wallet Transfer and Receive UIs: `showTransferUI`, `showReceiveUI`
* Agent key management: `getAgentKeys`, `registerAgentKey`, `removeAgentKey`
* Streamlined PIN setup / confirmation / recovery and account recovery entry points (`startRecovery`)
* Login / `getUserInfo` payloads: optional `user.wallet` and `abstractAccountAddresses`

### ➕ **Improvements**

* More reliable recovery OTP and Forgot PIN flows (including Safari)

### ⚠️ **Breaking Changes**

* Sandbox no longer accepts `credentialNetwork` — it is **Testnet-only**. Devnet opt-in is removed.
* `CredentialNetwork` is now `"testnet" | "mainnet"` (no longer `"devnet" | "testnet"`)
* Private Mainnet requires `buildEnv: BUILD_ENV.PRODUCTION` with `credentialNetwork: "mainnet"`
* Credentials and programs issued on Devnet are not available on Testnet or Mainnet — re-issue on the target network

### 📋 **Migration Guide**

**Sandbox (Testnet only):**

```js theme={null}
import { AirService, BUILD_ENV } from "@mocanetwork/airkit";

const airService = new AirService({
  partnerId: YOUR_PARTNER_ID
});
await airService.init({
  buildEnv: BUILD_ENV.SANDBOX,
  enableLogging: true
});
```

**Private Mainnet (production):**

```js theme={null}
await airService.init({
  buildEnv: BUILD_ENV.PRODUCTION,
  credentialNetwork: "mainnet",
  enableLogging: true
});
```

If you previously passed `credentialNetwork: "devnet"` (or any Sandbox `credentialNetwork`), remove it. Re-issue test credentials on Testnet or Mainnet as needed.

Moca Chain Mainnet is currently private. For production launches, use the production AIR pages and contact Moca for mainnet access and \$MOCA gas tokens. See [Production mainnet access](/get-started/environments/about#production-mainnet-access).

***

## **Flutter SDK 1.6.0**

### ✨ **New Features**

* Credential issuance and verification (`issueCredential`, `verifyCredential`, `preloadCredential`)
* Google and email passwordless login

### ➕ **Improvements**

* Credential stability improvements

Install with `version: ^1.6.0` via OnePub — see [Flutter installation](/get-started/sdks/flutter/installation).

***

## **Version 1.8.0 (Feb 9, 2026)**

### ✨ **New Features**

* Credential payment support
* Issue credentials on behalf of users
* Compliance encryption keys support for credential issuance and verification
* Display currency configuration (USD, EUR, CNY, KRW, TRY)
* New `air_accounts` RPC method to check account status across all supported chains
* `wallet_sendCalls` RPC method for batch transaction execution
* Temporary Devnet opt-in on Sandbox via `credentialNetwork: "devnet"` (removed in 1.10.0)

### ➕ **Improvements**

* Credential issuance and verification UI improvements and bug fixes
* Swap and OnRamp UI improvements and bug fixes
* WalletConnect stability improvements

### ⚠️ **Breaking Changes**

* Sandbox environment now defaults to **Moca Chain Testnet** instead of Devnet
* Credentials issued on Devnet will not be available on Testnet
* Devnet support remained available via `credentialNetwork: "devnet"` until **1.10.0**, when it was removed

### 📋 **Migration Guide**

After upgrading to `1.8.0`, Sandbox connects to Testnet by default. If your integration was not ready, you could temporarily stay on Devnet:

```js theme={null}
import { AirService, BUILD_ENV } from "@mocanetwork/airkit";

const airService = new AirService({
  partnerId: YOUR_PARTNER_ID
});
await airService.init({
  buildEnv: BUILD_ENV.SANDBOX,
  credentialNetwork: "devnet", // Temporary opt-in; removed in 1.10.0
  enableLogging: true
});
```

We recommend migrating to Testnet as soon as possible. Re-issue any test credentials on Testnet. **As of 1.10.0, Devnet opt-in is removed** — see the 1.10.0 migration guide above.

***

## **Version 1.7.0 (Nov 18, 2025)**

### ✨ **New Features**

* Cross-chain credential verification support
* Transaction payment token support
* Custom RPC URL configuration
* Automatic in-wallet login flow

### ➕ **Improvements**

* Credential UI updates
* Passkey UI updates
* Significant Air Services performance improvements
* Improved Credential error handling
* Swap UI improvements and bug fixes

## **Version 1.6.0 (Sept 16, 2025)**

### ✨ **New Features**

* Initial Air Credential support
* Flutter SDK released (version 1.5.0)
* Swap beta support
* OnRamp beta support
* Account deletion (via air3.com/recovery)
* Additional chains added:
  * Ethereum Testnet & Mainnet
  * Moca Testnet
  * Gnosis Testnet & Mainnet
  * Edu Testnet & Mainnet

### ➕ **Improvements**

* Air theme update
* Improved wallet login and mobile support
* Improved i18n support
* Improved error handling
* Overall Air Services stability

### ⚠️ **Notes**

* Air theme uses light theme only now

## **Version 1.5.0 (July 30, 2025)**

### ✨ **New Features**

* Flutter SDK beta released (version `1.5.0-beta.x`)
* Account email update and recovery (via air3.com/recovery)
* Additional chains added:
  * BNB Smart Chain
  * Kaia and Kairos

### ➕ **Improvements**

* Improved iOS Safari PWA support

### ⚠️ **Notes**

* `eth_accounts` will only return AA from now on

## **Version 1.4.0 (June 26, 2025)**

### ✨ **New Features**

* Moca Devnet chain added

### ➕ **Improvements**

* New SANDBOX environment for development and testing

## **Version 1.3.0 (June 5, 2025)**

### ➕ **Improvements**

* Captcha required during OTP for enhanced security
* Signing screen shows actual message
* Improved security by moving signing and transaction screens into separate window
* Improved Passkey provider suggestions
* Wagmi connect method now exposes authToken parameter
* Access token contains `sourcePartnerId` in case of cross partner rehydration
* Many small stabilization improvements

### ⚠️ **Notes**

* Signing and transaction screens are now shown in a separate browser window instead of iframe modals

## **Version 1.2.0 (May 7, 2025)**

### ✨ **New Features**

* User login token refresh support

### ➕ **Improvements**

* Improved MFA setup and verification flow
* More user-friendly transaction screen
* Bottom sheet instead of modal on mobile screens
* Animations for smoother transitions
* Support of small mobile screens
* Improved session key support
* Improved provider error handling

## **Version 1.1.0 (March 27, 2025)**

### ✨ **New Features**

* Persistent user sessions across AIR Kit dApps
* Protect user accounts with MFA via Passkey
* Login via EoA wallet
* Soneium chain support (Testnet / Mainnet)

### ➕ **Improvements**

* Simplified transaction screens
* Improved modal UI
* Wallet can be preloaded in the background
* Provider can be retrieved and subscribed to before wallet initialization
* Paymaster policies can be defined per chain
* Various minor bug fixes and optimizations

### ⚠️ **Notes**

* The AA will only be returned after the user has MFA set up
* MFA setup will automatically trigger on any wallet action

## **Version 1.0.0 (Feb 27, 2025)**

### ✨ **New Features**

* Smart accounts (AA) can be checked for deployment
* Smart accounts (AA) can be deployed without minting an Air Id
* Experimental session key support

### ➕ **Improvements**

* Full wallet services support
* Improved token refresh mechanism
* Login rehydration across partners

### ⚠️ **Notes**

* The `getUserInfo()` and `getPartnerUserInfo()` methods have been merged into `getUserInfo()`

## **Version 0.6.0 (Feb 17, 2025)**

### ✨ **New Features**

* Beta version of wallet services

### ➕ **Improvements**

* Small UI updates
* More helpful error messages

### ⚠️ **Notes**

* The wallet initialized event also returns the Smart Account (AA) address from now on

## **Version 0.5.0 (Feb 11, 2025)**

The first official release of AIR Kit, rebranded from Realm SDK, focuses on drastic performance and UX improvements and sets the foundation for upcoming features.

### ✨ **New Features**

* Customizable language support, including localized emails
* Toggleable email input field
* Support for custom authentication (Bring Your Own Auth)
* Optional partner user linking flow
* Introduction of a Global User ID to unify multiple Air IDs

### ➕ **Improvements**

* Simplified design tokens for UI customization
* Significantly faster initialization time and login experience
* Keep login session alive by automatic token refresh
* Backward compatibility down to ES2020
* Various minor bug fixes and optimizations

### ⚠️ **Notes**

* The MPC Signer address is no longer being returned
* External wallet login (e.g. MetaMask) is not yet supported
* Wallet-related services, including EIP1193 provider support, are unavailable in this version
* Smart Account (AA) addresses created in this version are different from previous versions


# Web SDK reference
Source: https://docs.air3.com/api-reference/sdk-reference

AIR Kit Web and Flutter SDK reference — AirService class, type definitions, and methods for AIR Account login, smart accounts, and credentials.

Your app works with AIR Kit through one class, `AirService`. It handles login, smart accounts, and issuing and verifying credentials.
This page lists every method and type in the Web and Flutter SDKs. To issue credentials from your server without the user presence, see the [REST API Reference](/api-reference/introduction).

## Platforms

<CardGroup>
  <Card title="Web SDK" icon="browser" href="#web">
    npm package `@mocanetwork/airkit`. Browser-first; works in any JS framework.
  </Card>

  <Card title="Flutter SDK" icon="mobile" href="#flutter">
    OnePub package `airkit`. Native iOS and Android via platform channels.
  </Card>
</CardGroup>

## Install

| Platform | Package | Guide |
| - | - | - |
| Web | `@mocanetwork/airkit` | [Installation](/get-started/sdks/web) |
| Flutter | `airkit` (OnePub) | [Flutter installation](/get-started/sdks/flutter/installation) |

See [Initialization](/get-started/sdks/web) for `init` options and environment selection.

## Authentication

* **AIR Account login** — the SDK runs the user flow and returns an access token. See [User authentication](/get-started/authentication/login).
* **Partner authentication (JWT)** — your backend signs a Partner JWT with your private key for server-to-server calls. See [Partner authentication](/get-started/authentication/sdk-auth).

<Note>
  Pick an environment per `BUILD_ENV` (`SANDBOX` or `PRODUCTION`). Production serves Moca Chain mainnet — see [Production mainnet access](/get-started/environments/about#production-mainnet-access).
</Note>

<Tabs>
  <Tab title="Web">
    ### AirService

    ```ts theme={null}
    class AirService {
      constructor({ partnerId: string; });
      get buildEnv(): BUILD_ENV_TYPE;
      get isInitialized(): boolean;
      get isLoggedIn(): boolean;
      get isWalletInitialized(): boolean;
      get provider(): EIP1193Provider;
      init({
        buildEnv: BUILD_ENV_TYPE;
        // Only when buildEnv is PRODUCTION:
        credentialNetwork?: "testnet" | "mainnet";
        enableLogging: boolean;
        skipRehydration: boolean;
        preloadWallet: boolean;
        preloadCredential: boolean;
        sessionConfig?: Partial<AirSessionConfig>;
      }): Promise<AirLoginResult | null>;
      login(options?: { authToken?: string }): Promise<AirLoginResult>;
      isSmartAccountDeployed(): Promise<boolean>;
      deploySmartAccount(): Promise<{ txHash: string }>;
      getProvider(): EIP1193Provider;
      preloadWallet(): Promise<void>;
      preloadCredential(): Promise<void>;
      setupOrUpdateMfa(): Promise<void>;
      getUserInfo(): Promise<AirUserDetails>;
      goToPartner(partnerUrl: string): Promise<{ urlWithToken: string }>;
      getAccessToken(): Promise<{ token: string }>;
      updateSessionConfig(config: Partial<AirSessionConfig>): Promise<AirSessionConfig>;
      showSwapUI(options?: ShowSwapUIOptions): Promise<{
        txHash: `0x${string}`;
        /** `amount` is in base units — divide by 10 ** decimals to display. */
        from: Token & { amount: string };
        to: Token & { amount: string };
      }>;
      showOnRampUI(options: {
        displayCurrencyCode: string;
        targetCurrencyCode?: string;
      }): Promise<void>;
      showTransferUI(options?: ShowTransferUIOptions): Promise<ShowTransferUIResult>;
      showReceiveUI(): Promise<void>;
      getAgentKeys(): Promise<AgentPublicKey[]>;
      registerAgentKey(publicKey: string): Promise<AgentPublicKey>;
      removeAgentKey(id: string): Promise<void>;
      claimAirId(options?: ClaimAirIdOptions): Promise<ClaimAirIdResult>;
      startRecovery(payload?: StartRecoveryPayload): Promise<void>;
      issueCredential({
        authToken: string;
        issuerDid: string;
        credentialId: string;
        credentialSubject: Record<string, unknown>;
        curve?: "secp256r1" | "secp256k1";
        waitForOnchainCompletion?: boolean;
      }): Promise<{ cakPublicKey?: string }>;
      verifyCredential({
        authToken: string;
        programId: string;
        redirectUrl?: string;
        fieldsToDisclose?: "*" | string[];
        nonce?: string;
      }): Promise<CredentialVerificationResult>;
      logout(): Promise<void>;
      cleanUp(): Promise<void>;
      on(listener: AirEventListener): void;
      off(listener: AirEventListener): void;
    }
    ```

    `claimAirId` and the `show*UI` methods are experimental and may change in future releases.

    `fieldsToDisclose` is required for `SD_JWT_VC` verification programs; `"*"` discloses every field, and dotted paths such as `address.city` select nested fields. See [Selective Disclosure](/products/identity/selective-disclosure). `nonce` is optional: pass a fresh value from your backend so that credentials with a holder key return a key-binding JWT. See [Verify SD-JWT on your backend](/products/identity/verify-sd-jwt).

    ### Types

    ```ts theme={null}
    export type AirIdDetails = {
      id: string;
      name?: string;
      node: string;
      status: "minting" | "minted";
      chainId: number;
      imageUrl?: string;
    };

    export type AbstractAccountAddressEntry = {
      readonly address: string;
      readonly chainIds: readonly string[];
    };

    export type AirUserDetails = {
      partnerId?: string;
      airId?: AirIdDetails;
      user: {
        id: string;
        abstractAccountAddress?: string;
        email?: string;
        wallet?: string;
        isMFASetup: boolean;
      };
    };

    export type AirInitializationResult = {
      rehydrated: boolean;
    };

    export type AirLoginResult = {
      isLoggedIn: boolean;
      id: string;
      abstractAccountAddress?: string;
      abstractAccountAddresses?: readonly AbstractAccountAddressEntry[];
      token: string;
      isMFASetup: boolean;
    };

    export type AirWalletInitializedResult = {
      abstractAccountAddress: string | null;
      isMFASetup: boolean;
    };

    export type AgentPublicKey = {
      id: string;
      publicKey: string;
      createdAt: string;
    };

    export type TokenSymbol = {
      symbol: string;
      chainId: number;
    };

    export type Token = TokenSymbol & {
      decimals: number;
      address: `0x${string}`;
    };

    export type ShowSwapUIOptions = {
      /** Preferred "from" token. Used when the user holds a balance and the token is supported. */
      initialFromToken?: TokenSymbol;
      /** "From" token to show when the user holds no assets. */
      fallbackFromToken?: TokenSymbol;
      /** Preferred "to" token. */
      initialToToken?: TokenSymbol;
      /** Slippage tolerance, in percent. Omitted or out-of-range values use automatic slippage. */
      defaultSlippage?: number;
    };

    export type ShowTransferUIOptions = {
      tokenSymbol?: string;
      chainId?: number;
      recipientAddress?: string;
      /** Display decimal string, e.g. "1.5" — not base units. */
      amount?: string;
    };

    export type ShowTransferUIResult = {
      txHash: `0x${string}`;
      symbol: string;
      chainId: number;
      decimals: number;
      address: `0x${string}`;
      recipientAddress: string;
      /** Display decimal string, as entered by the user. */
      amount: string;
    };

    export type CredentialProof = {
      type: string;
      coreClaim?: string;
      issuerData?: Record<string, unknown>;
      signature?: string;
      /** Compact SD-JWT presentation string (SD-JWT VC proof type). */
      jwt?: string;
      mtp?: Record<string, unknown>;
    };

    /** @deprecated No longer populated. Read verifiablePresentation instead. */
    export type DisclosedCredentialData = {
      credentialSubject: Record<string, unknown>;
      credentialType: string;
      issuerDid: string;
      issuanceDate: string;
      expirationDate: string;
      proof?: CredentialProof[];
    };

    /** A credential embedded in a Verifiable Presentation. */
    export type PresentationVerifiableCredential = {
      "@context": string[];
      type: string[];
      issuer: string;
      issuanceDate: string;
      expirationDate?: string;
      /** Disclosed subject fields, respecting selective disclosure. */
      credentialSubject: Record<string, unknown>;
      proof?: CredentialProof[];
    };

    /**
     * Presentation-level proof. Present only when the verification program
     * requires a zero-knowledge proof.
     */
    export type VerifiablePresentationProof = {
      type: string;
      proofPurpose: "authentication";
      circuitId: string;
      /** Present when the program has multiple ZK queries. */
      zkQueryId?: string;
      proofValue: {
        pi_a: string[];
        pi_b: string[][];
        pi_c: string[];
        protocol?: string;
        curve?: string;
      };
      publicSignals: string[];
      /** On-chain submission hash, for on-chain programs only. */
      transactionHash?: string;
    };

    export type AirVerifiablePresentation = {
      "@context": string[];
      type: string[];
      /** The holder DID. */
      holder: string;
      /**
       * Embedded credentials. For SD_JWT_VC programs, an
       * EnvelopedVerifiableCredential whose `id` is a `data:` URL carrying the
       * compact SD-JWT. W3C VC objects for BJJ_SIG_2021 programs.
       * Type-check each entry before reading it.
       */
      verifiableCredential: Array<PresentationVerifiableCredential | string>;
      /** Omitted when the program does not require a ZKP. */
      proof?: VerifiablePresentationProof | VerifiablePresentationProof[];
    };

    export type CredentialVerificationResult =
      | {
          status:
            | "Non-Compliant"
            | "Pending"
            | "Revoking"
            | "Revoked"
            | "Expired"
            | "NotFound";
        }
      | {
          status: "Compliant";
          verifiablePresentation?: AirVerifiablePresentation;
          cakPrivateKey?: string;
          /** @deprecated Not populated. Use verifiablePresentation.proof. */
          zkProofs?: Record<string, string>;
          /** @deprecated Not populated. Use verifiablePresentation.proof.transactionHash. */
          transactionHash?: string;
          /** @deprecated Not populated. Use verifiablePresentation.verifiableCredential. */
          disclosedData?: DisclosedCredentialData;
        };

    export type ClaimAirIdResult = {
      airId: AirIdDetails;
    };

    export type StartRecoveryOptions = {
      type?:
        /** Delete the current user's account. Performs its own email step-up. */
        | "delete"
        /** Create or rotate the current user's recovery key. Requires a session. */
        | "recovery_key_setup"
        /** Recover an account when the user lost email access, then set a new PIN. */
        | "email_recovery"
        /** Recover an account when the user forgot their PIN but still controls their email. */
        | "pin_recovery"
        /** Update the current user's email address. Requires a session. */
        | "update_email"
        /** Update the current user's PIN. Requires a session. */
        | "update_pin";
    };

    export type StartRecoveryPayload = {
      options?: StartRecoveryOptions;
    };

    export type AirEventOnInitialized = {
      event: "initialized";
      result: AirInitializationResult;
    };

    export type AirEventOnLoggedIn = {
      event: "logged_in";
      result: AirLoginResult;
    };

    export type AirEventOnAirIdMintingStarted = {
      event: "air_id_minting_started";
    };

    export type AirEventOnAirIdMintingFailed = {
      event: "air_id_minting_failed";
      errorMessage?: string;
    };

    export type AirEventOnLoggedOut = {
      event: "logged_out";
    };

    export type AirEventOnWalletInitialized = {
      event: "wallet_initialized";
      result: AirWalletInitializedResult;
    };

    export type AirEventData =
      | AirEventOnInitialized
      | AirEventOnLoggedIn
      | AirEventOnWalletInitialized
      | AirEventOnAirIdMintingStarted
      | AirEventOnAirIdMintingFailed
      | AirEventOnLoggedOut;

    export type AirEventListener = (data: AirEventData) => void;

    export type CredentialNetwork = "testnet" | "mainnet";

    export type SupportedCurrencyCode = "EUR" | "USD" | "CNY" | "KRW" | "TRY";

    export type AirSessionConfig = {
      locale: string;
      currency: SupportedCurrencyCode;
    };

    export type ClaimAirIdOptions =
      | {
          token?: string;
          background?: false;
          offchain?: boolean;
        }
      | {
          token: string;
          background: true;
          offchain?: boolean;
        };
    ```
  </Tab>

  <Tab title="Flutter">
    ### AirService

    ```dart theme={null}
    class AirService {

      Stream<AirEvent> get airEvents;

      void on(AirEventListener listener);
      void off(AirEventListener listener);
      void clearEventListeners();

      bool get isInitialized;

      Future<void> initialize({
        required String partnerId,
        Environment env = Environment.production,
        required GlobalKey<NavigatorState> navigatorKey,
        bool enableLogging = false,
        SessionConfig? sessionConfig,
      });

      Future<LoginResult> login({
        String? authToken,
      });

      Future<LoginResult> rehydrate();

      Future<UserInfo> getUserInfo();

      Future<SessionConfig> updateSessionConfig({
        String? locale,
        String? currency,
      });

      Future<void> preloadWallet();

      Future<void> preloadCredential();

      Future<CredentialIssuanceResult> issueCredential({
        required String authToken,
        required String issuerDid,
        required String credentialId,
        required Map<String, dynamic> credentialSubject,
        String? curve,
      });

      Future<CredentialVerificationResult> verifyCredential({
        required String authToken,
        required String programId,
        String? redirectUrl,
      });

      Future<String?> getAbstractAccountAddress();

      Future<List<String>> getAccounts();

      Future<void> setupOrUpdateMfa();

      Future<BigInt> getBalance(String address);

      Future<EthereumRpcSuccessResponse> call(
        String address,
        String function,
        List<dynamic> params,
        String abi,
      );

      Future<String> signMessage(String message);

      Future<String> sendTransaction(Transaction transaction);

      Future<EthereumRpcSuccessResponse> sendEthereumRpcRequest(
        EthereumRpcRequest request
      );

      Future<String> deploySmartAccount();

      Future<bool> isSmartAccountDeployed();

      Future<void> showSwapUi();

      Future<void> showOnRampUi({
        required String displayCurrencyCode,
        String? targetCurrencyCode,
      });

      Future<void> logout();

      void cleanup();
    }
    ```

    ### Models

    ```dart theme={null}
    enum Environment { staging, uat, sandbox, production }

    class SessionConfig {
      final String? locale;
      final String? currency;
    }

    class LoginResult {
      final bool isLoggedIn;
      final String? id;
      final String? abstractAccountAddress;
      final String? token;
      final bool? isMFASetup;
    }

    enum AirIdStatus {
      minting,
      minted,
    }

    class AirId {
      final String id;
      final String name;
      final String node;
      final AirIdStatus status;
      final int? chainId;
      final String? imageUrl;
    }

    class UserInfo {
      final AirId? airId;
      final String? partnerId;
      final User? user;
    }

    class User {
      final String id;
      final String? abstractAccountAddress;
      final String? email;
      final bool isMFASetup;
    }

    class CredentialIssuanceResult {
      final String? cakPublicKey;
    }

    class EthereumRpcRequest {
      final String method;
      final List<dynamic> params;
      final String? requestId;
    }

    class EthereumRpcSuccessResponse {
      final dynamic response;
    }

    class AirEvent { }

    class AirInitializedEvent extends AirEvent {}

    class AirLoggedInEvent extends AirEvent {
      final LoginResult payload;
    }

    class AirLoggedOutEvent extends AirEvent { }

    class AirWalletInitializedEvent extends AirEvent { }

    typedef AirEventListener = void Function(AirEvent event);

    enum ExceptionType {
      client,
      sdk,
      server,
      unknown,
    }

    class AirKitException implements Exception {
      final String message;
      final ExceptionType type;
    }
    ```
  </Tab>
</Tabs>


# Custom Auth
Source: https://docs.air3.com/get-started/authentication/custom-auth

Let users already signed in to your app use AIR Kit without logging in again, by passing their email in a Partner JWT at login.

With Custom Auth, users who are already signed in to your app skip the AIR Kit login dialog. Your backend signs a [Partner JWT](/get-started/authentication/sdk-auth) that includes the user's email, and your app passes it to `login({ authToken })`. AIR Kit then creates or loads the AIR Account for that email.

The first time an email is used, AIR verifies it with a one-time password sent to that address, because the email identifies the user across AIR. Later logins with the same email skip this step.

Custom Auth needs a registered [JWKS endpoint](/get-started/authentication/jwks-endpoint), like any Partner JWT.

## JWT payload

```json theme={null}
{
  "partnerId": "your-partner-id",
  "email": "user@example.com",
  "iat": 1728970084,
  "exp": 1728973684
}
```

| Claim | Required | Description |
| - | - | - |
| `partnerId` | Yes | Your Partner ID |
| `email` | Yes | The user's verified email, used as their AIR Account identifier |
| `exp` | Yes | Expiration time; 5 minutes is recommended |
| `iat` | Recommended | Issued-at time |

Sign the token on your server with a `kid` header that matches your JWKS.

For a full implementation with backend and frontend code, see the [Bring your own auth](/get-started/recipes/bring-your-own-auth) recipe.


# JWKS endpoint
Source: https://docs.air3.com/get-started/authentication/jwks-endpoint

Set up the public HTTPS JWKS endpoint AIR uses to validate your Partner JWTs, register its URL in the Dashboard, match the kid, and test locally.

A JWKS (JSON Web Key Set) endpoint publishes the public key that matches the private key you sign [Partner JWTs](/get-started/authentication/sdk-auth) with. AIR fetches it to check every Partner JWT, so credential calls fail until it is live and registered.

| Operation | JWKS required? |
| - | - |
| `issueCredential` and `verifyCredential` (SDK) | Yes |
| [Direct issuance](/products/identity/issuing-credentials#direct-issuance) (AIR API) | Yes |
| `login` with a Partner JWT (Flutter, [Custom Auth](/get-started/authentication/custom-auth), or optionally on Web) | Yes |
| `login` without a Partner JWT (Web) | No |

## How AIR uses your JWKS

```mermaid theme={null}
sequenceDiagram
    participant App as Your backend
    participant SDK as AIR Kit SDK
    participant AIR as AIR Kit servers
    participant JWKS as Your /api/.well-known/jwks

    App->>App: Sign Partner JWT with private key<br/>header.kid = partnerId
    App->>SDK: authToken (signed JWT)
    SDK->>AIR: issueCredential / verifyCredential<br/>with authToken
    AIR->>JWKS: GET registered JWKS URL
    JWKS-->>AIR: { keys: [ { kid, n, e, ... } ] }
    AIR->>AIR: Validate JWT signature + kid match
    AIR-->>SDK: Proceed (or 401 if anything fails)
```

If AIR cannot fetch your JWKS, or no key in it matches the JWT's `kid`, the request fails with `401`.

## Step 1: Implement the route

This Next.js route is the one used by every issuer and verifier app in [`air-examples`](https://github.com/MocaNetwork/air-examples). It converts your public key from PEM to JWK with [`jose`](https://github.com/panva/jose) and sets `kid` to your Partner ID.

```ts app/api/.well-known/jwks/route.ts theme={null}
import { NextResponse } from "next/server";
import * as jose from "jose";

export async function GET() {
  try {
    const publicKeyPEM = `-----BEGIN PUBLIC KEY-----\n${process.env.PARTNER_PUBLIC_KEY!}\n-----END PUBLIC KEY-----`;
    const publicKey = await jose.importSPKI(publicKeyPEM, process.env.SIGNING_ALGORITHM!);
    const jwk = await jose.exportJWK(publicKey);

    return NextResponse.json(
      {
        keys: [
          {
            ...jwk,
            kid: process.env.NEXT_PUBLIC_PARTNER_ID!,
            use: "sig",
            alg: process.env.SIGNING_ALGORITHM!,
          },
        ],
      },
      {
        headers: {
          "Content-Type": "application/json",
          "Cache-Control": "public, max-age=3600",
        },
      },
    );
  } catch {
    return NextResponse.json({ error: "Failed to generate JWKS" }, { status: 500 });
  }
}
```

Required environment variables (server-side only — never expose `PARTNER_PRIVATE_KEY`):

| Variable | Used for |
| - | - |
| `PARTNER_PUBLIC_KEY` | The base64 body of your RS256 or ES256 public key (between the BEGIN/END markers). |
| `PARTNER_PRIVATE_KEY` | The matching private key used to sign your Partner JWT. **Server-only.** |
| `SIGNING_ALGORITHM` | `RS256` or `ES256`. Must match the key type. |
| `NEXT_PUBLIC_PARTNER_ID` | Your Partner ID. Used as `kid` so the JWKS key matches the JWT header. |

Generate the key pair as described in [SDK authentication](/get-started/authentication/sdk-auth#generating-an-rs256-key-pair).

## Step 2: Register the URL in the Dashboard

1. Open the [Developer Dashboard](https://developers.sandbox.air3.com/dashboard).
2. Go to **Account → General Settings**.
3. Paste the full HTTPS URL into **JWKS URL**, for example `https://app.example.com/api/.well-known/jwks`, and save.

AIR fetches exactly this URL, with no path discovery or fallback. Register the path your app actually serves: `/api/.well-known/jwks` for the route above, or whatever route you defined yourself.

Each Partner ID has one JWKS URL. If your issuer and verifier apps share a Partner ID, register one JWKS and sign all Partner JWTs with a `kid` it contains. If you need separate JWKS per service, request a second Partner ID.

## Step 3: Match the `kid`

The `kid` in each Partner JWT header must appear as a `keys[].kid` in your JWKS. The examples use your Partner ID for both. If you use another convention, such as key-rotation IDs, the rule is the same.

Check the endpoint before you call the SDK:

```bash theme={null}
curl https://app.example.com/api/.well-known/jwks
# → { "keys": [ { "kty": "RSA", "kid": "<your-partner-id>", "alg": "RS256", ... } ] }
```

## Local development (HTTPS tunnel)

AIR servers cannot reach `localhost`. Expose your dev server over public HTTPS and register the tunnel URL:

<Tabs>
  <Tab title="ngrok">
    ```bash theme={null}
    ngrok http 3000
    # → forwarding https://abc123.ngrok.app -> http://localhost:3000
    ```

    Register `https://abc123.ngrok.app/api/.well-known/jwks` in the dashboard.
  </Tab>

  <Tab title="cloudflared">
    ```bash theme={null}
    cloudflared tunnel --url http://localhost:3000
    # → trycloudflare https://random-words.trycloudflare.com
    ```

    Register `https://random-words.trycloudflare.com/api/.well-known/jwks` in the dashboard.
  </Tab>
</Tabs>

## Troubleshooting

If AIR still rejects your Partner JWT, see [Common issues](/help/common-issues#jwt-and-jwks-errors):

* [JWKS endpoint unreachable](/help/common-issues#jwks-endpoint-unreachable) — AIR cannot fetch your URL.
* [Invalid signature](/help/common-issues#invalid-signature-or-jwt-verification-failed) — JWKS reachable but signature does not validate.
* [kid not found](/help/common-issues#kid-not-found) — JWT header `kid` is not present in `keys[]`.


# User login
Source: https://docs.air3.com/get-started/authentication/login

Log users in with AIR Kit using built-in Google and passwordless email login, and request optional EOA wallet authentication from the AIR team.

## Using AIR Kit as your authentication provider

By default, users can log in with:

* Google
* Passwordless email

Wallet (EOA) login is not enabled by default. The AIR team enables it on request; see [EOA wallet authentication](#eoa-wallet-authentication-optional-add-on). To change which methods appear and in what order, see [Login options](/get-started/customization/login-options).

See the [single sign-on demo](https://air-bd-v2.netlify.app/demo/single-sign-on) for a click-through of the login flow. It is a walkthrough, not a live session.

<Warning>
  **Google sign-in redirect on recent Apple OSes.** On **iOS 26.5.2 and above (any browser)** and **macOS 26.5.2 with Safari**, Google sign-in completes through a full-page redirect instead of a popup. Single-page apps — or any app whose state is not fully represented by the URL — must persist and restore their page state across the redirect so the user returns to where they left off after authenticating.
</Warning>

<Tabs>
  <Tab title="Web">
    ```tsx theme={null}
    login(options?: { authToken?: string }): Promise<AirLoginResult>
    ```
  </Tab>

  <Tab title="Flutter">
    On Flutter, call `login` with a **Partner JWT** after `initialize()`:

    ```dart theme={null}
    Future<LoginResult> login({
      required String authToken,
      OnOtpRequest? onOtpRequest,
    });
    ```

    See the [SDK reference](/api-reference/sdk-reference) (Flutter tab).
  </Tab>
</Tabs>

Calling `login()` opens the AIR Kit login dialog with your enabled login methods. On Web, `authToken` is optional but recommended: pass a [Partner JWT](/get-started/authentication/sdk-auth) to identify your app, or one that includes the user's email for [Custom Auth](/get-started/authentication/custom-auth). On Flutter, `authToken` is required.

After login, see [Sessions & user info](/get-started/authentication/sessions).

## EOA Wallet Authentication (optional add-on)

EOA-based authentication is available as an optional customization on top of the default AIR Account login flow.
This allows your users to authenticate using any EOA wallet (e.g., MetaMask, Trust Wallet) while still benefiting from the AIR Account identity stack. The EOA wallet is used only for authentication and identity verification. It does not replace the underlying MPC-based account abstraction or control mechanisms. In effect, the wallet address serves purely as a login identifier, while account control remains securely managed by AIR.

### Why enable EOA auth?

* Seamlessly supports existing “Connect Wallet” flows
* Zero disruption to current users
* Adds AIR Account–powered authentication without requiring UX changes
* Works alongside Web2 and other login methods

If your application already uses EOA wallet login, you can enable AIR Account authentication on top of it—ensuring a unified identity experience while preserving your existing flow.

### How to request EOA authentication

EOA auth is not enabled by default.
To enable it for your project, please contact our support team with the following details:

### EOA auth enablement request template

**Subject:** Request to Enable EOA Authentication for \<Project Name >

**Email Body:**

```
Hi Team,

I would like to request **EOA authentication** to be enabled for our project.

**Project Name:**
**Partner ID: (Can be obtained from the Dev dashboard: https://developers.sandbox.air3.com/dashboard/general):**
**Environment:** (Production / Sandbox / Both)

**Current Login Method:**
(e.g., Connect Wallet, Web2 login, AIR Account)

**Reason for Enabling EOA Auth:**
(e.g., we support existing EOA wallet login and want to integrate AIR Account without disrupting our users)

Please let us know if you require any additional information or configuration details.

Thank you!
```


# Multi-factor authentication (MFA)
Source: https://docs.air3.com/get-started/authentication/mfa

Set up passkey-based multi-factor authentication for AIR Kit users with setupOrUpdateMfa, and decide when to prompt for it.

## setupOrUpdateMfa()

Sets up or updates multi-factor authentication for the user's account. This method guides the user through the MFA setup process using passkeys.

**Method Signature:**

```ts theme={null}
public async setupOrUpdateMfa(): Promise<void>
```

**What happens during MFA setup:**

1. The method ensures the wallet is initialized
2. Opens the MFA setup flow and guides the user through passkey creation/verification
3. Updates the user's MFA status in the system, including `loginResult` to reflect the new MFA status

**Requirements:**

* User must be logged in

**Important Notes:**

* **MFA is generally required**: If your dApp doesn't trigger `setupOrUpdateMfa()` after login and the user hasn't set up MFA, it will be triggered automatically with any wallet related request, requiring the user to complete setup before the request can be processed
* **Currently only passkey is supported** as the MFA method
* **Only MFA setup is currently implemented, not updates**: It's recommended to check if the user has already set up MFA before calling this method to avoid unnecessary prompts
* **Abstract Account Address availability**: The abstract account address will only be returned in user info and token if MFA is set up

## MFA setup integration

Since MFA is generally required, you can either:

**Option 1: Proactive Setup (Recommended)**

```ts theme={null}
try {
  const userInfo = await airService.getUserInfo();
  if (!userInfo.user.isMFASetup) {
    await airService.setupOrUpdateMfa();
    // Abstract account address will now be available
  }
} catch (error) {
  // Handle error appropriately
}
```

**Option 2: Let AIR Kit Handle Automatically**
Simply proceed with wallet operations - MFA will be prompted automatically if required.


# SDK authentication (Partner JWT)
Source: https://docs.air3.com/get-started/authentication/sdk-auth

Sign a short-lived Partner JWT on your backend to authenticate AIR Kit credential operations and Custom Auth login, with required claims and headers.

A Partner JWT proves that a request comes from your app. Your backend signs it with your private key, your app passes it to AIR Kit, and AIR checks the signature against the public key in your registered [JWKS endpoint](/get-started/authentication/jwks-endpoint).

You need a Partner JWT for:

* `issueCredential` and `verifyCredential` in the SDK
* [Direct issuance](/products/identity/issuing-credentials#direct-issuance) through the AIR API
* `login` on Flutter, and `login` with [Custom Auth](/get-started/authentication/custom-auth) on Web

On Web, standard AIR login works without a Partner JWT, but passing one is recommended. Always sign Partner JWTs on your server, never in the browser.

## JWT requirements

| Part | Requirement |
| - | - |
| Algorithm | `RS256` or `ES256`, matching the key type in your JWKS |
| Header | `kid` set to a key ID in your JWKS, and `typ: "JWT"` |
| `partnerId` claim | Always required: your Partner ID |
| `scope` claim | `"issue"` for `issueCredential` and direct issuance, `"verify"` for `verifyCredential` |
| `email` claim | Only for Custom Auth login. For direct issuance, send the recipient's email to `initialize-user`, not in the JWT. |
| `exp` claim | Required. Keep tokens short-lived; 5 minutes is recommended. |

To learn more about JWTs, see [jwt.io](https://www.jwt.io).

## Next.js Partner JWT endpoint

Install `jose`:

```bash theme={null}
npm i jose
```

Create a server-only endpoint that returns a five-minute token. This example signs an issuance token; use `scope: "verify"` for verification.

```ts app/api/partner-jwt/route.ts theme={null}
import { NextResponse } from "next/server";
import * as jose from "jose";

function wrapPrivateKeyPem(body: string): string {
  const trimmed = body.trim();
  if (trimmed.includes("BEGIN")) return trimmed;

  return `-----BEGIN PRIVATE KEY-----\n${trimmed}\n-----END PRIVATE KEY-----`;
}

export async function POST() {
  try {
    const privateKeyBody = process.env.PARTNER_PRIVATE_KEY;
    const algorithm = process.env.SIGNING_ALGORITHM;
    const partnerId = process.env.NEXT_PUBLIC_PARTNER_ID;

    if (!privateKeyBody || !algorithm || !partnerId) {
      return NextResponse.json(
        { error: "Missing Partner JWT configuration" },
        { status: 500 },
      );
    }

    const privateKey = await jose.importPKCS8(
      wrapPrivateKeyPem(privateKeyBody),
      algorithm,
    );
    const now = Math.floor(Date.now() / 1000);

    const token = await new jose.SignJWT({
      partnerId,
      scope: "issue",
    })
      .setProtectedHeader({
        alg: algorithm,
        kid: partnerId,
        typ: "JWT",
      })
      .setIssuedAt(now)
      .setExpirationTime(now + 5 * 60)
      .sign(privateKey);

    return NextResponse.json({ token });
  } catch {
    return NextResponse.json(
      { error: "Failed to sign Partner JWT" },
      { status: 500 },
    );
  }
}
```

Keep `PARTNER_PRIVATE_KEY` server-only. This example uses the Partner ID as the `kid`, matching the [JWKS route](/get-started/authentication/jwks-endpoint#step-1-implement-the-route).

## Generating an RS256 key pair

Generate a private key and extract its public key with OpenSSL:

```bash theme={null}
openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out private.key
openssl pkey -in private.key -pubout -out public.key
```

Sign Partner JWTs with `private.key` and keep it secret. Publish `public.key` through your [JWKS endpoint](/get-started/authentication/jwks-endpoint).

## Examples

Sign a Partner JWT in other backend languages. Each example signs an issuance token with RS256; change `scope` for verification.

<Tabs>
  <Tab title="Node.js">
    ```js theme={null}
    const jwt = require("jsonwebtoken");
    const fs = require("fs");

    const privateKey = fs.readFileSync("path/to/private.key");
    const payload = {
      partnerId: "your-partner-id",
      scope: "issue",
      exp: Math.floor(Date.now() / 1000) + 5 * 60 // 5 minutes expiry
    };

    const token = jwt.sign(payload, privateKey, {
      algorithm: "RS256",
      header: {
        kid: "your-key-id",
        typ: "JWT"
      }
    });
    console.log(token);
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    import com.auth0.jwt.JWT;
    import com.auth0.jwt.algorithms.Algorithm;
    import java.util.HashMap;
    import java.util.Map;

    Algorithm algorithm = Algorithm.RSA256(null, privateKey); // Use your private key
    Map<String, Object> headerClaims = new HashMap<>();
    headerClaims.put("kid", "your-key-id");
    headerClaims.put("typ", "JWT");

    String token = JWT.create()
                    .withHeader(headerClaims)
                    .withClaim("partnerId", "your-partner-id")
                    .withClaim("scope", "issue")
                    .withExpiresAt(new Date(System.currentTimeMillis() + 5 * 60 * 1000))
                    .sign(algorithm);

    System.out.println(token);
    ```
  </Tab>

  <Tab title="C#">
    ```csharp theme={null}
    using System;
    using System.IdentityModel.Tokens.Jwt;
    using System.Security.Claims;
    using Microsoft.IdentityModel.Tokens;
    using System.Collections.Generic;

    // Load your private key and create signing credentials
    var securityKey = new RsaSecurityKey(yourPrivateRsa);
    var credentials = new SigningCredentials(securityKey, SecurityAlgorithms.RsaSha256);

    var claims = new[] {
            new Claim("partnerId", "your-partner-id"),
            new Claim("scope", "issue"),
    };

    var header = new JwtHeader(credentials); // sets typ: "JWT"
    header["kid"] = "your-key-id";

    var token = new JwtSecurityToken(
            header,
            new JwtPayload(
                    claims: claims,
                    expires: DateTime.UtcNow.AddMinutes(5),
                    notBefore: null,
                    issuedAt: null,
                    audience: null,
                    issuer: null
            )
    );

    var jwt = new JwtSecurityTokenHandler().WriteToken(token);
    Console.WriteLine(jwt);
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    import (
            "fmt"
            "time"
            "github.com/golang-jwt/jwt/v5"
    )

    func main() {
            privateKey := []byte("your-private-key") // Use PEM for RS256/ES256
            claims := jwt.MapClaims{
                    "partnerId": "your-partner-id",
                    "scope":     "issue",
                    "exp":       time.Now().Add(5 * time.Minute).Unix(),
            }
            token := jwt.NewWithClaims(jwt.SigningMethodRS256, claims)
            token.Header["kid"] = "your-key-id" // golang-jwt sets typ: "JWT" by default
            signedToken, err := token.SignedString(privateKey)
            if err != nil {
                    panic(err)
            }
            fmt.Println(signedToken)
    }
    ```
  </Tab>
</Tabs>

Replace `your-partner-id`, `your-key-id`, and the key paths with your own values. For ES256, use the matching signing method and an EC key.


# Sessions & user info
Source: https://docs.air3.com/get-started/authentication/sessions

Work with AIR Kit sessions after login — the login result token, automatic session rehydration, logout, and retrieving user information with getUserInfo.

## Login result token

After a successful login, `login()` returns an `AirLoginResult`. Its `token` property is a JWT issued by AIR with these claims:

```json theme={null}
{
  sub: string,
  abstractAccountAddress: string,
  partnerId: string,
  sourcePartnerId?: string
}
```

To trust this token on your backend, validate it against AIR's JWKS at [https://static.air3.com/.well-known/jwks.json](https://static.air3.com/.well-known/jwks.json).

## Session management

AIR Kit manages sessions for you. Returning users are logged in automatically for up to 30 days, unless they logged out.

<Tabs>
  <Tab title="Web">
    * To require users to log in every time they visit your app, set `skipRehydration` to true when initializing the SDK.
    * Call `isLoggedIn` to check the login state of a user.
    * To log out, call `logout()`.
    * To change locale or currency after initialization, call `updateSessionConfig()`. See [Language support](/get-started/customization/language) and [Other options](/get-started/customization/other-options).
  </Tab>

  <Tab title="Flutter">
    * To keep users logged in after an app restart, call `rehydrate()`. It logs in a returning user who still has a valid session; otherwise, call `login()`.
  </Tab>
</Tabs>

## User information

### getUserInfo()

Retrieves detailed information about the currently logged-in user.

**Method Signature:**

```ts theme={null}
public async getUserInfo(): Promise<AirUserDetails>
```

**Returns:**

```ts theme={null}
{
  partnerId?: string;
  airId?: AirIdDetails;
  user: {
    id: string;
    abstractAccountAddress?: string;
    email?: string;
    wallet?: string;
    isMFASetup: boolean;
  };
}
```

**Requirements:**

* User must be logged in

**Example:**

```ts theme={null}
try {
  const userInfo = await airService.getUserInfo();
} catch (error) {
  console.error("Failed to get user info:", error);
  // Handle error appropriately
}
```


# Connect your agent
Source: https://docs.air3.com/get-started/build-with-your-agent

Connect your agent to the AIR documentation MCP server, try your first prompt, and choose between Docs MCP, the AIR skill, and static docs while building.

## Connect via MCP

Choose your tool below and add the AIR documentation server:

```text theme={null}
https://docs.air3.com/mcp
```

<Tabs>
  <Tab title="Claude">
    <Steps>
      <Step title="Add the Moca Network MCP server to Claude">
        1. Navigate to the [Connectors](https://claude.ai/settings/connectors) page in the Claude settings.
        2. Select **Add custom connector**.
        3. Add the Moca Network MCP server:
           * Name: `MocaNetwork`
           * URL: `https://docs.air3.com/mcp`
        4. Select **Add**.
      </Step>

      <Step title="Access the MCP server in your chat">
        1. When using Claude, select the attachments button (the plus icon).
        2. Select the MocaNetwork MCP server.
        3. Ask Claude a question about Moca Network or AIR Kit.
      </Step>
    </Steps>

    See the [Model Context Protocol documentation](https://modelcontextprotocol.io/docs/tutorials/use-remote-mcp-server#connecting-to-a-remote-mcp-server) for more details.
  </Tab>

  <Tab title="Claude Code">
    <Steps>
      <Step title="Add the MCP server to Claude Code">
        Run the following command:

        ```bash theme={null}
        claude mcp add --transport http MocaNetwork https://docs.air3.com/mcp
        ```
      </Step>

      <Step title="Test the connection">
        Verify the connection by running:

        ```bash theme={null}
        claude mcp list
        ```
      </Step>
    </Steps>

    See the [Claude Code documentation](https://docs.anthropic.com/en/docs/claude-code/mcp#installing-mcp-servers) for more details.
  </Tab>

  <Tab title="Cursor">
    <Steps>
      <Step title="Open MCP settings">
        1. Use <kbd>Command</kbd> + <kbd>Shift</kbd> + <kbd>P</kbd> (<kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>P</kbd> on Windows) to open the command palette.
        2. Search for "Open MCP settings".
        3. Select **Add custom MCP**. This opens the `mcp.json` file.
      </Step>

      <Step title="Configure the Moca Network MCP server">
        In `mcp.json`, add:

        ```json theme={null}
        {
          "mcpServers": {
            "MocaNetwork": {
              "url": "https://docs.air3.com/mcp"
            }
          }
        }
        ```
      </Step>

      <Step title="Test the connection">
        In Cursor's chat, ask "What tools do you have available?" Cursor should show the MocaNetwork MCP server as an available tool.
      </Step>
    </Steps>

    See the [Cursor documentation](https://docs.cursor.com/en/context/mcp#installing-mcp-servers) for more details.
  </Tab>

  <Tab title="VS Code">
    <Steps>
      <Step title="Create MCP configuration">
        Create a `.vscode/mcp.json` file in your project root.
      </Step>

      <Step title="Configure the Moca Network MCP server">
        In `.vscode/mcp.json`, add:

        ```json theme={null}
        {
          "servers": {
            "MocaNetwork": {
              "type": "http",
              "url": "https://docs.air3.com/mcp"
            }
          }
        }
        ```
      </Step>
    </Steps>

    See the [VS Code documentation](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) for more details.
  </Tab>
</Tabs>

For another MCP-compatible tool, add the URL as a remote HTTP MCP server in its connection settings.

## Try your first prompt

Once connected, ask your agent to look up the docs and help with a specific task:

```text theme={null}
Use the AIR docs MCP server to help me add AIR Kit login to my app.
Check my framework and existing authentication, then explain the setup
and changes before implementing them.
```

You can also ask about credential issuance and verification, wallet transactions, or integration errors. Include your framework and what you have already built.

## Choose your setup

| Option | What it provides | When to use it |
| - | - | - |
| **Docs MCP** | Searchable AIR documentation, SDK guides, and API references. | Start here for current reference material. |
| **AIR skill** | Integration workflows and checks for setup, authentication, and common errors. | Add alongside MCP for guidance while building. |
| **Static docs** | Documentation files you attach or index in your tool. | Use when your tool cannot connect through MCP; refresh the files as docs change. |

Your agent uses these resources to plan, write, and review integration code. Live AIR operations run through your application's configured account, authentication, and programs.

## Add the AIR skill (optional)

For tools that support [Agent Skills](https://agentskills.io/home), run:

```bash theme={null}
npx skills add https://docs.air3.com
```

Select your agent in the CLI to install the skill.

<Accordion title="Before issuing or verifying credentials">
  Ask your agent to confirm these prerequisites before generating application code:

  * Your partner's public JWKS endpoint is reachable over HTTPS.
  * The exact JWKS URL is registered in the Developer Dashboard.
  * Your JWT signing key stays server-side, and its `kid` matches a published JWKS key.

  Follow [JWKS endpoint setup](/get-started/authentication/jwks-endpoint), then use the [issuance](/products/identity/issuing-credentials) or [verification](/products/identity/verify) guide for your flow.
</Accordion>

<Accordion title="Use static documentation files">
  ## Static docs files

  If your AI tool does not support MCP yet, you can use one of Moca Network's static documentation files instead.

  <Warning>
    Static files are snapshots and may not include the latest updates. Use MCP when possible for always-current docs.
  </Warning>

  ## Which file should I use?

  * **`llms.txt`** — A curated overview of Moca Network. Use it to route an agent to the right docs, understand product structure, and choose the right integration path.
  * **`llms-full.txt`** — A full static snapshot of the documentation. Use it when your tool needs more exhaustive reference material in one file.

  ## Setup with Cursor

  <Steps>
    <Step title="Open docs settings">
      Go to **Settings** → **Features** → **Docs**.
    </Step>

    <Step title="Add the overview file">
      Click **Add new doc** and paste: `https://docs.air3.com/llms.txt`
    </Step>

    <Step title="Optionally add the full snapshot">
      If your agent needs deeper static reference coverage, add: `https://docs.air3.com/llms-full.txt`
    </Step>

    <Step title="Reference in chat">
      Use **@docs** → **Moca** in your AI chat to reference the documentation.
    </Step>
  </Steps>

  ## Setup with Claude Desktop

  <Steps>
    <Step title="Download the overview file">
      Download the curated overview from: [https://docs.air3.com/llms.txt](https://docs.air3.com/llms.txt)
    </Step>

    <Step title="Optionally download the full snapshot">
      Download the full documentation snapshot from: [https://docs.air3.com/llms-full.txt](https://docs.air3.com/llms-full.txt)
    </Step>

    <Step title="Add to your project">
      Save one or both files in your project directory or another known location on your system.
    </Step>

    <Step title="Reference in chat">
      Drag and drop the file into your Claude Desktop chat, or use the attachment button to upload it. Claude will then have access to the uploaded Moca Network documentation context for that conversation.
    </Step>
  </Steps>
</Accordion>


# Language support
Source: https://docs.air3.com/get-started/customization/language

Choose AIR Kit languages, customize copy with hosted JSON, and set or change the language with the Web SDK.

AIR Kit includes English (`en`), Japanese (`ja`), Korean (`ko`), Turkish (`tr`), and Vietnamese (`vi`). English is always the fallback for missing translations. To override copy or add languages, host JSON files and register them through `localeUrls` in partner configuration. The SDK selects the language; it does not accept translation strings.

## How language selection works

AIR Kit selects the language in this order:

1. The SDK's `sessionConfig.locale`, if set.
2. The user's browser language preferences, unless detection is disabled.
3. Your `defaultLocale`, or `en` if unset.

Regional tags resolve to available catalogs, such as `ko-KR` to `ko` and `en-US` to `en`, with region fallback. A language must be bundled or have a registered JSON URL, and must pass your `supportedLocales` allowlist. Adding a code to the allowlist does not provide translations.

Browser language changes are followed when detection is enabled and no SDK locale is explicitly set.

## Partner configuration

Set these fields through partner configuration (backend or dashboard), separate from SDK initialization:

| Field | Purpose |
| - | - |
| `localeUrls` | Recommended: locale code → JSON URL, with one combined file per language for all AIR Kit interfaces. |
| `defaultLocale` | Fallback language when no SDK or browser language is selected. Defaults to `en`. |
| `supportedLocales` | Allowed languages. Empty means no restriction, including bundled languages. A non-empty list rejects other locales; use it to opt out of a bundled language. English remains the fallback. |
| `disableBrowserLocaleDetection` | Ignore browser language preferences and use `defaultLocale`, unless the SDK sets a locale. |

## Customize copy or add a language

1. Use the combined English catalog's key structure, which covers all interfaces.
2. Host a JSON file for each locale, such as `en.json` or `es.json`. Include only the keys you want to change; nested objects are merged and missing keys fall back to English.
3. Register the URLs in `localeUrls` in partner configuration. If you use a non-empty `supportedLocales` list, include the new locale.

For example, register one combined Spanish translation across all four interfaces:

```json theme={null}
{
  "defaultLocale": "es",
  "localeUrls": { "es": "https://cdn.example.com/airkit/i18n/es.json" }
}
```

<Note>
  English overrides customize the fallback copy. Bundled translations take precedence over that copy, so also provide a locale-specific override to customize wording for Japanese, Korean, Turkish, or Vietnamese users.
</Note>

### Translate selected interfaces

If you use only a subset of AIR Kit, you can fully translate those interfaces with separate files instead of working from the combined catalog. Each file should follow that interface's composed English catalog.

Use `authLocaleUrls` for login, `walletLocaleUrls` for the wallet, `recoveryLocaleUrls` for recovery, or `credentialLocaleUrls` for credentials. Each maps a locale code to a JSON URL. For example, an integration using only login and credentials can register translations in `authLocaleUrls` and `credentialLocaleUrls`.

If you also use `localeUrls`, interface-specific overrides take precedence for the same locale.

## Set or change the language with the Web SDK

Set `sessionConfig.locale` at [initialization](/get-started/sdks/web#initialize) to override browser detection and the partner default. Omit it to allow automatic selection.

```tsx theme={null}
await airService.init({
  buildEnv: BUILD_ENV.SANDBOX,
  sessionConfig: {
    locale: "ja"
  }
});
```

Change the language after initialization across all loaded AIR Kit interfaces:

```tsx theme={null}
await airService.updateSessionConfig({ locale: "ko" });
```

To set the display currency, see [Other options](/get-started/customization/other-options).


# Login options
Source: https://docs.air3.com/get-started/customization/login-options

Customize the AIR Kit login screen via partner config — control available login methods, branding, and how the login interface appears to your users.

## Login Methods (`loginMethods`)

Control which authentication methods are available on the login screen:

```tsx theme={null}
type LoginMethod =
  | "passwordless" // Email-based passwordless login
  | "passwordlessToggle" // Email input revealed behind a link
  | "google" // Google OAuth login
  | "wallet" // Wallet connection login
  | "passkey"; // Passkey login
```

**Available Options:**

* **`passwordless`**: Email-based passwordless authentication, with the email input shown up front
* **`passwordlessToggle`**: Same as `passwordless`, but the input starts collapsed behind a link and appears once the user taps it. Useful when you want social or wallet login to be the visually dominant option
* **`google`**: Google OAuth login integration
* **`wallet`**: Wallet-based authentication. Requires [EOA wallet authentication](/get-started/authentication/login#eoa-wallet-authentication-optional-add-on), which the AIR team enables on request.
* **`passkey`**: Passkey login

**Example Configuration:**

```tsx theme={null}
// Email and Google
loginMethods: ["passwordless", "google"];

```

**Note:** The order in the array determines the display order in the UI (top to bottom).

**Defaults and automatic adjustments:**

* If `loginMethods` is omitted or empty, AIR Kit falls back to `["passwordless", "google"]`.
* Inside webviews, `google` is dropped automatically, since Google blocks OAuth in embedded browsers. If neither `passwordless` nor `passwordlessToggle` was configured, AIR Kit adds `passwordless` so users always have a way to sign in.
* Unknown and duplicated values are ignored.

### Wallet Login Methods (`walletLoginMethods`)

When `wallet` is included in `loginMethods`, specify which wallet providers are available:

```tsx theme={null}
type LoginWalletId =
  | "bybit" // Bybit Wallet
  | "coinbase" // Coinbase Wallet
  | "crypto.com" // Crypto.com DeFi Wallet
  | "metamask" // MetaMask
  | "okx" // OKX Wallet
  | "phantom" // Phantom Wallet
  | "rabby" // Rabby Wallet
  | "rainbow" // Rainbow Wallet
  | "trust" // Trust Wallet
  | "walletConnect"; // WalletConnect
```

**Example Configuration:**

```tsx theme={null}
// Enable wallet login with specific providers
loginMethods: ["wallet"],
walletLoginMethods: ["metamask", "coinbase", "walletConnect"]

// Default wallet providers if not specified
walletLoginMethods: undefined;
// ["metamask", "phantom", "okx", "coinbase", "rabby", "walletConnect"]
```

<Info>
  The order in the array determines the display order in the UI (left to right, top to bottom). Since AIR accounts are shared across partners, consider including email-based login to avoid forcing users to link wallets to existing accounts.
</Info>

### Style Configuration (`style`)

Customize the visual appearance of the login interface:

```tsx theme={null}
type PartnerConfigStyle = {
  passwordlessButtonVariant?: "inline" | "standalone";
  airLogoTheme?: "default" | "reverse" | "dark_only" | "light_only";
};
```

**Style Options:**

* **`passwordlessButtonVariant`**: Controls how the passwordless login button appears
  * `"inline"`: Button appears inline with other elements
  * `"standalone"`: Button appears as a standalone element below the input
* **`airLogoTheme`**: Controls the AIR logo appearance
  * `"default"`: Standard logo theme
  * `"reverse"`: Reversed color scheme
  * `"dark_only"`: Dark theme only
  * `"light_only"`: Light theme only

**Example Configuration:**

```tsx theme={null}
style: {
  passwordlessButtonVariant: "standalone",
  airLogoTheme: "dark_only",
}
```

## OTP delivery customization

OTP delivery branding can be customized for your project:

* **SMS sender name**: Use `{Partner Name} via AIR`, such as `Minds via AIR`.
* **Email logo**: Display your logo in OTP emails.
* **Email sender domain**: Send OTP emails from your domain by providing your own SMTP server. You can use providers such as Mailgun, SendGrid, or AWS SES.

<Info>
  These customizations are enabled by the AIR team and are not configured through the SDK. Contact us to request custom OTP delivery branding for your project.
</Info>


# Other options
Source: https://docs.air3.com/get-started/customization/other-options

Other AIR Kit session options — set the display currency for wallet balances, transactions, and on-ramp and swap interfaces.

Session options are set in `sessionConfig` when you call `init()`, and can be changed later with `updateSessionConfig()`. For language, see [Language support](/get-started/customization/language).

## Currency

Set the optional `sessionConfig.currency` at initialization, or update it alongside the locale:

```tsx theme={null}
const updatedConfig = await airService.updateSessionConfig({ currency: "EUR" });
```

Supported currencies are `EUR` (Euro), `USD` (US Dollar), `CNY` (Chinese Yuan), `KRW` (South Korean Won), and `TRY` (Turkish Lira). Currency controls monetary display in wallet balances, transaction amounts, and on-ramp/swap interfaces. The update returns the complete `AirSessionConfig`, including locale and currency.


# Theming
Source: https://docs.air3.com/get-started/customization/theming

Customize AIR Kit UI appearance with CSS variables — override text colors, button styles, backgrounds, and fonts to match your brand.

## Customizable Elements

| Element Category | CSS Variables | Description |
| - | - | - |
| **Text Colors** | `--air-text-primary-color` `--air-text-secondary-color` `--air-text-placeholder-color` | Primary text, secondary text, input placeholders |
| **Button Colors** | `--air-button-primary-color` `--air-button-secondary-color` `--air-button-outlined-color` | Primary buttons, secondary buttons, outlined buttons |
| **Background Colors** | `--air-background-color` `--air-surface-color` `--air-container-primary-color` | Main background, surface areas, containers |
| **Border Colors** | `--air-border-color` `--air-border-focus-color` | Default borders, focused input borders |
| **Status Colors** | `--air-status-success-color` `--air-status-error-color` `--air-status-pending-color` | Success, error, pending states |
| **Icon Colors** | `--air-icon-primary-color` `--air-icon-secondary-color` `--air-icon-hover-color` | Primary icons, secondary icons, hover states |
| **Logo** | `--air-logo` | Custom logo URL |
| **Font Family** | `--air-font-family` | Custom font family (requires font import) |

## Example Partner Theme

The Mocaverse theme used on mocaverse.xyz:

```css theme={null}
:root {
  --mocaverse-air-logo: url(https://static.air3.com/assets/mocaverse.svg);

  --mocaverse-air-text-primary-color: #ffffff;
  --mocaverse-air-text-secondary-color: #b0b0b0;
  --mocaverse-air-text-placeholder-color: #767676;
  --mocaverse-air-text-disabled-color: #ffffff40;
  --mocaverse-air-text-inverse-color: #000000;
  --mocaverse-air-text-on-color: #ffffff;

  --mocaverse-air-button-primary-color: #ff49a0;
  --mocaverse-air-button-primary-hover-color: #000000;
  --mocaverse-air-button-secondary-color: #2450ee;
  --mocaverse-air-button-secondary-hover-color: #ffffff;
  --mocaverse-air-button-disabled-color: #3a3a3a;
  --mocaverse-air-button-outlined-color: #ffffff;
  --mocaverse-air-button-outlined-hover-color: #ffffff14;
  --mocaverse-air-button-outlined-secondary-color: #4e4150;
  --mocaverse-air-button-outlined-secondary-hover-color: #ffffff14;

  --mocaverse-air-border-color: #ffffff40;
  --mocaverse-air-border-focus-color: #ffffff;

  --mocaverse-air-link-color: #3c8cff;
  --mocaverse-air-text-button-color: #ef6aba;

  --mocaverse-air-icon-primary-color: #ffffff;
  --mocaverse-air-icon-secondary-color: #b0b0b0;
  --mocaverse-air-icon-hover-color: #000000;
  --mocaverse-air-icon-disabled-color: #00000040;

  --mocaverse-air-status-success-color: #74ffcd;
  --mocaverse-air-status-error-color: #ff49a0;
  --mocaverse-air-status-pending-color: #f99247;

  --mocaverse-air-surface-color: #110a17;
  --mocaverse-air-surface-dim-color: #343a3b;

  --mocaverse-air-overlay-color: #00000080;

  --mocaverse-air-container-primary-color: #1d1d1d;
  --mocaverse-air-container-secondary-color: #2f2f2f;

  --mocaverse-air-decorative-color: #ef6aba;
  --mocaverse-air-secondary-5-color: #ffffff;

  --mocaverse-air-background-color: linear-gradient(90deg, #202734 0.5%, #3c253c 100.5%);
}
```

## Testing Your Theme

The best way to test your custom theme is to use browser developer tools to manipulate CSS custom properties in real-time:

1. **Open Developer Tools**: Press F12 or right-click → Inspect
2. **Navigate to Elements Tab**: Find the `<html>` element
3. **Access CSS Variables**: In the Styles panel, look for `:root` or `html[theme='your-theme']`
4. **Modify Properties**: Click on any CSS custom property value to edit it
5. **See Changes Instantly**: Changes apply immediately without page refresh

This allows you to:

* Test different color combinations quickly
* Verify contrast ratios
* Ensure your theme works across all screens
* Fine-tune values before finalizing your CSS file

## Best Practices

* **Accessibility**: Ensure sufficient contrast ratios for text and backgrounds. Adjust our AIR logo via config value if necessary
* **Dark/Light Mode**: Consider both light and dark theme variations
* **Font Testing**: Test custom fonts across different devices and browsers


# Setting up your partner account
Source: https://docs.air3.com/get-started/dashboard/account-setup

Set up your AIR Kit partner account on the Developer Dashboard: get your Partner ID, add your domains, register your JWKS URL, and enable credential services.

Every AIR Kit integration starts with a partner account in the <a href="https://developers.sandbox.air3.com">Developer Dashboard</a>. Sign in by connecting your EVM wallet, then set up the following.

| Setting | Where | Needed for |
| - | - | - |
| **Partner ID** | **Account → General Settings** (copy it) | Everything. You pass it to the SDK and your backend. |
| **Name, logo, and website** | **Account → General Settings** | Shown to users during login, issuance, and verification. |
| **Domains** | **Account → Domains** | Loading AIR Kit from your app's origin. |
| **JWKS URL** | **Account → General Settings** | Issuing or verifying credentials, and [Custom Auth](/get-started/authentication/custom-auth). See [JWKS endpoint](/get-started/authentication/jwks-endpoint). |

If you only use login, the Partner ID and domains are enough.

## Enable credential services

To issue or verify credentials, register your own DID with AIR. AIR does not create one for you: you publish it from your domain with your own keys. Until a DID is registered, the **Issuer** and **Verifier** menus stay hidden. See [Issuing credentials](/products/identity/issuing-credentials) for the steps.

For a tour of every Dashboard section, see [Features](/get-started/dashboard/features). This page uses the sandbox Dashboard; production has its own, covered in the [Launch checklist](/get-started/launch-checklist).


# Developer Dashboard features
Source: https://docs.air3.com/get-started/dashboard/features

What each section of the AIR Kit Developer Dashboard does — account settings and domains, issuer schemas and programs, and verifier programs and fee wallet.

The <a href="https://developers.sandbox.air3.com/dashboard">Developer Dashboard</a> is where you configure your AIR Kit integration. You sign in by connecting an EVM wallet, which identifies your partner account. It has three sections:

* **Account:** your partner settings and allowed domains.
* **Issuer:** schemas, issuance programs, and issuance records.
* **Verifier:** verification programs, verification records, and the fee wallet.

The Issuer and Verifier sections appear once you register your DID. See [Setting up your account](/get-started/dashboard/account-setup).

## Account

### General Settings

| Field | Description |
| - | - |
| **Partner ID** | Your AIR Kit partner ID. Read-only; copy it into your SDK and backend configuration. |
| **Name** | Your app's name, shown to users during login, wallet transactions, issuance, and verification. |
| **Logo URL** | Your app's logo, shown in the same places as the name. |
| **Website URL** | Your app's website, for users who want to learn more about your app. |
| **JWKS URL** | The public HTTPS URL of your JWKS. Required for issuing and verifying credentials and for Custom Auth. See [JWKS endpoint](/get-started/authentication/jwks-endpoint). |

### Domains

AIR Kit only loads on domains you allow. You can add up to 3 domains or subdomains, and wildcards such as `*.myapp.example.com` are supported. Some domains are blocked for security reasons; contact the AIR team if you need one of them.

<Info>
  In sandbox, `localhost` is allowed on ports `3000`, `5173`, and `8200`, and you cannot add it to the list yourself. Production requires HTTPS domains.
</Info>

## Issuer

The Issuer section is for partners that issue credentials. It has three areas: the schema builder, issuance programs, and issuance monitoring.

### 1. Schema Builder

This is the starting point for creating any new credential. A Schema acts as a blueprint, defining the structure, data type, and rules for a specific type of credential.

* **Create Schemas**: Issuers can build custom schemas by defining a title, version, and description.
* **Define Attributes**: Within each schema, issuers add specific data fields (attributes). For each attribute, they define a name, data type (e.g., string, number, boolean), a descriptive title, and can mark it as required.
* **Publish**: Publish the schema to use it in issuance programs. See [Schema creation](/products/identity/schema-creation) for field types and design rules.

Here is an example of a simple schema for a "DAO Membership" credential:

```json theme={null}
{
  "title": "DAO Membership",
  "version": "1.0",
  "description": "Verifies that the holder is a member of a specific DAO.",
  "attributes": [
    {
      "name": "daoName",
      "type": "string",
      "title": "DAO Name",
      "required": true
    },
    {
      "name": "memberSince",
      "type": "date",
      "title": "Member Since",
      "required": true
    },
    {
      "name": "votingPower",
      "type": "number",
      "title": "Voting Power",
      "required": false
    }
  ]
}
```

### 2. Issuance Program

An issuance program defines a credential your issuer service can issue, based on a published schema.

* **Select a Schema**: The process begins by selecting the appropriate schema, which loads its predefined attributes.
* **Set Issuance Rules**: Issuers can configure key parameters for the credential, such as:
  * **Accessible Until**: An optional date range during which the credential is valid.
  * **Maximum Issuance**: An optional cap on the total number of credentials that can be claimed.
  * **Expiration Duration**: The lifespan of the credential after it has been issued to a user (e.g., 90 days, 1 year, permanent).
* **Use the program ID**: Pass the program ID to `issueCredential` in your app. Your [issuer service](/products/identity/backend-hosting) signs and issues the credential when the user claims it.

### 3. Issuer Dashboard Monitoring

This section provides a high-level overview and detailed logs of all issuance activity.

* **Key Metrics**: View statistics like the Total Issued Number (the total number of credentials claimed by users) and the Total Credential Number (the number of different credential types created).
* **Claim Records**: See a detailed list of every credential that has been claimed by a user, including the Holder ID, Credential ID, and the Claimed Time. Issuers can also revoke a claimed credential directly from this interface.

## Verifier

The Verifier section is for partners that check users' credentials. It is centered on verification programs.

### 1. Verification Program Management

A verification program defines which credentials you accept and which claims you request.

* **Choose the credential**: Select the schema, the issuers you trust, and the accepted proof type (`SD_JWT_VC` by default).
* **Request claims**: Choose which claims the user is asked to disclose. The user sees them on the consent screen and shares only those. See [Selective disclosure](/products/identity/selective-disclosure).
* **Use the program ID**: Pass the program ID to `verifyCredential` in your app.

Conditions on a value without revealing it, such as "age greater than 18", and on-chain verification need [Iden3 credentials](/products/identity/iden3-credentials).

### 2. Verifier Dashboard Monitoring

This dashboard provides a comprehensive record of all verification activities.

* **Key Metrics**: View the Total Verified Number of credentials and other relevant statistics.
* **Verification Records**: Access a detailed log of all verification attempts, including the Holder ID, the Program Name used, the Verified Time, and the Current Status (e.g., Passed, Verification Failed).

### 3. Settings and Fee Wallet

Issuers and verifiers each have a settings panel. For verifiers, it includes a fee wallet: issuance and verification can incur on-chain gas fees, so you can pre-fund this wallet with \$MOCA. Fees for verification transactions are deducted from it, and the Dashboard shows the history of deposits and charges.


# Environments
Source: https://docs.air3.com/get-started/environments/about

Switch between AIR Kit Sandbox and Production environments — Sandbox uses Moca Chain Testnet; Production supports Testnet or Moca Chain mainnet.

<Warning>
  Sandbox always uses **Moca Chain Testnet**.
</Warning>

| Environment | Moca Chain | Purpose | Developer Dashboard |
| - | - | - | - |
| Development + Testing | Testnet (222888) | Partners still on Testnet credentials | [https://developers.sandbox.air3.com/dashboard](https://developers.sandbox.air3.com/dashboard) |
| Production + `credentialNetwork: "mainnet"` | Mainnet (2288) | Production launches | [https://developers.air3.com/dashboard](https://developers.air3.com/dashboard) |

## Production mainnet access

Moca Chain mainnet is live. Production launches use the production AIR pages, including the [production Developer Dashboard](https://developers.air3.com/dashboard), and configure AIR Kit with `BUILD_ENV.PRODUCTION` and `credentialNetwork: "mainnet"`.

Production is self-serve for SD-JWT credentials: register your issuer, schemas, and programs in the production Dashboard the same way you did in sandbox. To use Iden3 credentials in production, contact the AIR team; see [Iden3 credentials](/products/identity/iden3-credentials).

For every step and a go-live checklist, see [Launch checklist](/get-started/launch-checklist). See [Moca Chain network information](/technicals/mocachain/network-information) for RPC and explorer URLs.

<Card title="Need \$MOCA for gas?" icon="coins" href="/technicals/mocachain/how-to-get-moca">
  \$MOCA is the gas token on Moca Chain mainnet. See how to bridge or buy it.
</Card>

## Initializing AirService with the correct environment

<Tabs>
  <Tab title="Web">
    **Sandbox (Testnet):**

    ```js theme={null}
    import { AirService, BUILD_ENV } from "@mocanetwork/airkit";

    const airService = new AirService({
      partnerId: YOUR_PARTNER_ID
    });
    await airService.init({
      buildEnv: BUILD_ENV.SANDBOX,
      enableLogging: true
    });
    ```

    **Mainnet (production):**

    ```js theme={null}
    await airService.init({
      buildEnv: BUILD_ENV.PRODUCTION,
      credentialNetwork: "mainnet",
      enableLogging: true
    });
    ```

    `credentialNetwork` is only accepted when `buildEnv` is `BUILD_ENV.PRODUCTION`. Values: `"testnet"` | `"mainnet"`.
  </Tab>

  <Tab title="Flutter">
    ```dart theme={null}
    await airService.initialize(
      partnerId: 'YOUR_PARTNER_ID',
      navigatorKey: navigatorKey,
      env: Environment.sandbox, // or Environment.production
      enableLogging: true,
    );
    ```
  </Tab>
</Tabs>

## Chains

| Chain | Chain ID | RPC | Explorer |
| - | - | - | - |
| Testnet | 222888 | [https://rpc.testnet.mocachain.dev](https://rpc.testnet.mocachain.dev) | [https://testnet-scan.mocachain.org](https://testnet-scan.mocachain.org) |
| Mainnet | 2288 | [https://rpc.mocachain.org](https://rpc.mocachain.org) | [https://scan.mocachain.org](https://scan.mocachain.org) |

You can add Moca Chain mainnet to a wallet from [ChainList](https://chainlist.org/chain/2288). See [Moca Chain network information](/technicals/mocachain/network-information) for all endpoints.

Before you switch environments, read [Environment best practices](/get-started/environments/best-practices).


# Environment best practices
Source: https://docs.air3.com/get-started/environments/best-practices

Keep AIR Kit sandbox and production separate: match chains to environments, re-issue network-specific credentials, and migrate from older SDK versions.

## Match the chain to the environment

Sandbox always uses Moca Chain Testnet. Production uses Moca Chain mainnet when you set `credentialNetwork: "mainnet"`. If your app's chain does not match its build environment, you can hit unexpected errors. See [Environments](/get-started/environments/about) for the full mapping.

## Treat credentials as network-specific

Credentials, schemas, and programs are network-specific. Credentials issued on Testnet are not available on Mainnet, and Devnet-issued credentials are not available on either. When you move to a new network:

* Re-issue credentials on the target network.
* Recreate issuance schemas and programs if needed.
* Check your Issuer and Verifier DIDs, which may differ per network.

## Keep each environment separate

* Sandbox and production each have their own Developer Dashboard, and nothing you set up in sandbox carries over. Copy the Partner ID from each Dashboard; do not assume they match.
* Register a JWKS URL in each Dashboard, and keep production private keys apart from sandbox keys. See [JWKS endpoint](/get-started/authentication/jwks-endpoint).
* Read `buildEnv`, `credentialNetwork`, Partner ID, program IDs, and API origins from configuration, not hard-coded values, so a production build never ships with sandbox values.

## Test on sandbox, then launch

Build and test the full flow on sandbox first. When it works end to end, follow the [Launch checklist](/get-started/launch-checklist) to set up production.

## Migrating from older SDK versions

Starting with **AirKit 1.10.0**, Sandbox is Testnet-only — the temporary `credentialNetwork: "devnet"` opt-in is removed.

### What changed

| Before (\< 1.8.0) | 1.8.0–1.9.x | 1.10.0+ |
| - | - | - |
| Sandbox → Devnet (Chain ID: 5151) | Sandbox → Testnet by default; optional `credentialNetwork: "devnet"` | Sandbox → Testnet only; no `credentialNetwork` on Sandbox |
| Dashboard: [https://developers.sandbox.air3.com](https://developers.sandbox.air3.com) | Dashboard: [https://developers.sandbox.air3.com](https://developers.sandbox.air3.com) | Dashboard: [https://developers.sandbox.air3.com](https://developers.sandbox.air3.com) |

### Impact

* Credentials issued on Devnet are **not** available on Testnet or Mainnet
* Smart Account addresses remain the same across networks
* Re-issue test credentials on Testnet, or on Mainnet for production launches


# Launch checklist
Source: https://docs.air3.com/get-started/launch-checklist

Move an AIR Kit integration from sandbox to production on Moca Chain mainnet: Dashboard setup, SDK settings, backends, credentials, and go-live checks.

Sandbox and production are separate environments. Production runs on Moca Chain mainnet and has its own <a href="https://developers.air3.com/dashboard">Developer Dashboard</a>. Nothing you set up in sandbox carries over: you register your app, keys, issuer, schemas, and programs again, and you switch your code to the production settings.

## What changes in production

| Setting | Sandbox | Production |
| - | - | - |
| Developer Dashboard | [developers.sandbox.air3.com](https://developers.sandbox.air3.com/dashboard) | [developers.air3.com](https://developers.air3.com/dashboard) |
| Web SDK `buildEnv` | `BUILD_ENV.SANDBOX` | `BUILD_ENV.PRODUCTION`, with `credentialNetwork: "mainnet"` |
| Flutter `env` | `Environment.sandbox` | `Environment.production` |
| AIR account domain (passkeys, mobile) | `account.sandbox.air3.com` | `account.air3.com` |
| AIR API base URL (direct issuance) | `https://api.sandbox.mocachain.org/v1` | `https://mocachain-mainnet.api.air3.com/v1` |
| Issuer service `NODE_ENV` | `sandbox` | `production` |
| Moca Chain | Testnet (222888) | Mainnet (2288) |
| Allowed domains | `localhost` ports 3000, 5173, and 8200 are allowed | HTTPS domains only |

Credentials are network-specific. Credentials issued in sandbox do not exist in production. See [Environments](/get-started/environments/about).

## Step 1: Set up your production partner account

1. Sign in to the <a href="https://developers.air3.com/dashboard">production Developer Dashboard</a>.
2. In **Account → General Settings**, copy your production **Partner ID**. Do not assume it matches your sandbox Partner ID.
3. Fill in your app's **Name**, **Logo URL**, and **Website URL**. Users see them during login, transactions, issuance, and verification.
4. Register your production **JWKS URL**. It must be public HTTPS and reachable from AIR servers. See [JWKS endpoint setup](/get-started/authentication/jwks-endpoint).
5. Under **Account → Domains**, add the HTTPS domains that load AIR Kit. You can add up to 3, and wildcards such as `*.myapp.example.com` are supported. `localhost` is not available in production.

For what each setting does, see [Developer Dashboard](/get-started/dashboard/features).

## Step 2: Switch the SDK to production

<Tabs>
  <Tab title="Web">
    ```ts theme={null}
    import { AirService, BUILD_ENV } from "@mocanetwork/airkit";

    const airService = new AirService({
      partnerId: process.env.NEXT_PUBLIC_PARTNER_ID, // production Partner ID
    });

    await airService.init({
      buildEnv: BUILD_ENV.PRODUCTION,
      credentialNetwork: "mainnet",
      enableLogging: false,
    });
    ```

    `credentialNetwork` is only accepted when `buildEnv` is `BUILD_ENV.PRODUCTION`.
  </Tab>

  <Tab title="Flutter">
    ```dart theme={null}
    await airService.initialize(
      partnerId: 'YOUR_PRODUCTION_PARTNER_ID',
      navigatorKey: navigatorKey,
      env: Environment.production,
      enableLogging: false,
    );
    ```

    Keep `account.air3.com` in your Android asset statements and iOS associated domains so passkeys work in production. See [Android setup](/get-started/sdks/flutter/android-setup) and [iOS setup](/get-started/sdks/flutter/ios-setup).
  </Tab>
</Tabs>

Keep sandbox and production values in separate environment configurations, so a production build never ships with a sandbox Partner ID or program ID.

## Step 3: Point your backend at production

Your Partner JWT endpoint signs tokens for the production Partner ID:

* Sign with the private key whose public key is in your production JWKS, and set the `kid` to match.
* Keep tokens short-lived and generate them on the server only. See [SDK authentication](/get-started/authentication/sdk-auth).
* If you call the AIR API directly, for example `initialize-user` and `dstorage/vcs` for direct issuance, use the production base URL.

## Step 4: Set up credentials in production

Skip this step if you use AIR Kit only for login or wallets.

**If you issue credentials:**

1. Deploy your issuer service for production on a domain you control, with a durable database and `NODE_ENV=production`. The reference issuer service uses PostgreSQL. See [Issuer backend hosting](/products/identity/backend-hosting).
2. Register the issuer in **Issuer → Settings** on the production Dashboard: the `did:web` Issuer DID, the issuer API key, the JWKS URL, and the endpoint URLs.
3. Recreate your schemas and issuance programs in the production Dashboard, and update the program IDs in your app.
4. Decide your revocation setup, including whether to enable the [token status list](/products/identity/revocation#token-status-list), before you issue the first production credential.
5. If you issue [Iden3 credentials](/products/identity/iden3-credentials), contact the AIR team to enable them in production.

The issuer host becomes your issuer identity once you issue on mainnet, so do not change it afterwards.

**If you verify credentials:**

1. Recreate your verification programs in the production Dashboard and update the program IDs in your app.
2. Constrain each program to the production Issuer DIDs you trust.
3. Verify every presentation on your backend, with a fresh nonce per verification. See [Verify SD-JWT on your backend](/products/identity/verify-sd-jwt).

## Step 5: Set up accounts and gas

Skip this step if you do not use smart accounts.

* Contact the AIR team to set up gas sponsorship policies and the chains in your partner configuration. See [Paymaster](/products/money/paymaster).
* If your app or users pay gas on Moca Chain, see [How to get \$MOCA](/technicals/mocachain/how-to-get-moca).
* If you use [session keys](/products/money/session-keys), scope them to the smallest set of actions and give them short expiry times.

## Step 6: Test on production before launch

Run your main flows end to end with a real test account on production:

* Log in and log out, including on each mobile platform you ship.
* Issue a credential, verify it, revoke it, and confirm that verification then fails.
* Send a transaction from the smart account, if you use one.
* Check that a request from a domain that is not on your allowed list is refused.

## Go-live checklist

**Dashboard and keys**

* [ ] Signed in to the production Developer Dashboard, and copied the production Partner ID
* [ ] App name, logo URL, and website URL set
* [ ] Production JWKS URL is public HTTPS and registered
* [ ] Partner JWTs are signed server-side with a key whose `kid` is in that JWKS, and expire within 5 minutes
* [ ] Allowed domains list only your HTTPS production domains
* [ ] Private keys and API keys are stored in a secrets manager, not in source control or client code

**SDK and apps**

* [ ] Web apps initialize with `BUILD_ENV.PRODUCTION` and `credentialNetwork: "mainnet"`
* [ ] Flutter apps initialize with `Environment.production`
* [ ] Mobile apps include `account.air3.com` in their associated domains and asset statements
* [ ] No sandbox Partner ID, program ID, or URL remains in the production build
* [ ] Logging is off or reduced for production

**Issuing credentials** (if you issue)

* [ ] Issuer service deployed on a domain you control, with `NODE_ENV=production`
* [ ] The issuer database is durable and its migrations are applied
* [ ] `did:web` Issuer DID, issuer API key, JWKS URL, and endpoint URLs registered in the production Dashboard
* [ ] Schemas and issuance programs recreated in production, and their IDs updated in your app
* [ ] Revocation tested; token status list partition size final and a publish job scheduled, if you use it
* [ ] Iden3 credentials enabled by the AIR team, if you use them

**Verifying credentials** (if you verify)

* [ ] Verification programs recreated in production, and their IDs updated in your app
* [ ] Programs limited to the production Issuer DIDs you trust
* [ ] Backend verifies every presentation, including the key-binding JWT, and uses each nonce only once

**Accounts and gas** (if you use smart accounts)

* [ ] Gas sponsorship policies and chains confirmed with the AIR team
* [ ] Sponsorship spend is monitored
* [ ] Session keys are narrowly scoped with short expiry

**Operations**

* [ ] All main flows tested end to end on production
* [ ] Alerts set up for failed authentication (spikes in 401 and 403 responses) and unusual issuance volume
* [ ] A key rotation plan: add the new key to your JWKS before removing the old one

For the full list of security practices, see the [Security checklist](/technicals/architecture/security-checklist).


# Quickstart: Issuing your first credential
Source: https://docs.air3.com/get-started/quickstarts/issue-credentials

Run the AIR issuer service, register it with AIR, and issue your first SD-JWT credential to a logged-in user with AIR Kit.

This guide implements on-demand issuance with the user present. Your app calls
`issueCredential()` to open the AIR flow. The SDK handles login, credential
discovery, and user confirmation; AIR forwards issuance to your backend, which
authorizes the request, retrieves the data, creates and signs the credential,
encrypts it, and stores it in dStorage.

New issuance programs use the `SD_JWT_VC` proof type. This setup is self-serve
in both sandbox and production. To issue Iden3 (`BJJ_SIG_2021`) credentials
instead, see [Iden3 credentials](/products/identity/iden3-credentials).

<Info>
  This guide covers user-initiated SDK issuance through a self-hosted issuer
  backend. To issue from a backend event with no user session, see
  [Direct issuance](/products/identity/issuing-credentials#direct-issuance).
</Info>

## Before you start

You need:

* A supported Node.js version
* An issuer backend implementing `available-vc` and `issue-vc`, reachable by AIR
  over HTTPS. You can host it or use an HTTPS tunnel during development.
* An AIR Developer Dashboard account and Partner ID
* A server endpoint that signs Partner JWTs, and a public HTTPS JWKS endpoint (you set both up in Step 6)
* A web app whose origin is registered in the Dashboard

**A database is optional in sandbox.**
For development and testing, credential data can come from an existing API or service, or you can use static sample data.
For production, however, if you need to support features such as **credential revocation, issuance history, and token status lists,**
especially at scale with many users, you will need to persist the relevant data in your own database.

Regardless of whether you use a database, encrypted credentials are stored in dStorage.

The backend and JWKS endpoint can share a host. See [Issuer backend hosting](/products/identity/backend-hosting).

<Warning>
  Choose a stable public origin for the issuer service before you issue. The issuer DID is `did:web:<host of ISSUER_ORIGIN>`, so changing the host later changes your issuer identity.
</Warning>

## What you will build

By the end of this guide, you will have:

* A public issuer backend with `POST /available-vc`, `POST /issue-vc`, a
  revocation-status endpoint, and a `did:web` document
* A Dashboard schema and issuance program
* A schema class that produces the claims your backend signs
* A public JWKS endpoint and a server-only Partner JWT endpoint
* A web flow that logs in with AIR Kit and calls `issueCredential`

<CardGroup>
  <Card title="AIR issuer service (SD-JWT)" icon="github" href="https://github.com/MocaNetwork/air-issuer-service/tree/main">
    Issuer endpoints, schema logic, SD-JWT signing, encryption, revocation, and dStorage integration.
  </Card>
</CardGroup>

## How SDK issuance works

1. Your app starts `issueCredential()` with the issuer and issuance program.
2. The user logs in to AIR if needed.
3. The SDK requests available credentials through AIR. AIR calls the registered
   issuer backend's `POST /available-vc` and returns encrypted previews.
4. The SDK decrypts and displays the previews. The user selects a credential and
   confirms issuance.
5. The SDK requests issuance through AIR, which calls the issuer's `POST /issue-vc`
   with the resolved holder identity, encryption key, holder signing key, and schema.
6. The issuer authorizes the request, loads authoritative claims, creates and
   signs the SD-JWT VC, encrypts it, and stores it in dStorage.
7. The SDK reports completion to your app. If the user declines, issuance stops.

The browser does not need the issuer API key or a separate request to fetch claims.
See [Architecture and data flow](/technicals/architecture) for the sequence diagram.

The issuance program ID is an AIR Kit and Dashboard identifier. Your issuer
backend works with a `schemaId`, not the program ID.

## Step 1: Generate partner secrets

Clone the SD-JWT branch of the [AIR issuer service](https://github.com/MocaNetwork/air-issuer-service/tree/main),
or your fork of it, then install its dependencies:

```bash theme={null}
git clone -b main https://github.com/MocaNetwork/air-issuer-service.git
cd air-issuer-service
npm i
```

Check the branch README and `.env.example` when you upgrade.

Generate separate API keys for AIR-to-issuer calls and admin calls:

```bash theme={null}
echo "API_KEY=$(openssl rand -hex 32)"
echo "ADMIN_API_KEY=$(openssl rand -hex 32)"
```

Generate an RSA key pair for Partner JWT signing:

```bash theme={null}
openssl genpkey \
  -algorithm RSA \
  -pkeyopt rsa_keygen_bits:2048 \
  -out partner-private.pem

openssl pkey \
  -in partner-private.pem \
  -pubout \
  -out partner-public.pem
```

You will use the same key pair in three places:

* The issuer backend signs the SD-JWT credentials and its requests to dStorage
  with the private key.
* Your web server signs short-lived AIR Kit Partner JWTs with the private key.
* The public key is published through your JWKS and the issuer's `did:web`
  document, so AIR and verifiers can check both.

Never expose the private key through a `NEXT_PUBLIC_*` environment variable.

## Step 2: Configure and start the issuer backend

Create the issuer backend environment file:

```bash theme={null}
NODE_ENV=sandbox

# Optional in sandbox; required for revocation, history, and the status list at scale
# DATABASE_URL=postgres://postgres:postgres@127.0.0.1:5432/issuer-backend

# Public origin of this issuer service, without a trailing slash.
# The issuer DID is did:web:<host of this origin>.
ISSUER_ORIGIN=https://issuer.example.com

# Partner identity and signing
PARTNER_ID=<dashboard-partner-id>
PARTNER_PRIVATE_KEY_KID=<kid-in-your-jwks>
PARTNER_PRIVATE_KEY_ALG=RS256
PARTNER_PRIVATE_KEY_DER=<pkcs8-private-key-body-without-pem-markers>
PARTNER_JWKS=<public-JWKS-JSON-containing-the-matching-kid>

# AIR-to-issuer and operator authentication
API_KEY=<generated-api-key>
ADMIN_API_KEY=<generated-admin-api-key>

# Optional
# AIR_API_ORIGIN and MOCA_CHAIN_API_ORIGIN default per NODE_ENV
# SD_JWT_TSL_PARTITION_SIZE=80000   # enables the token status list; see Revoke credentials
PORT=3000
```

`PARTNER_PRIVATE_KEY_DER` is the base64 body between the `BEGIN PRIVATE KEY`
and `END PRIVATE KEY` lines in `partner-private.pem`. It must be PKCS#8.

`PARTNER_JWKS` contains public keys only, matching your Partner JWT signing key
and `kid`. Generate and publish the document using [JWKS endpoint setup](/get-started/authentication/jwks-endpoint).
The service serves these keys in its `did:web` document and issuer metadata.

If you set `DATABASE_URL` (this issuer service uses PostgreSQL), apply migrations before the first start:

```bash theme={null}
npx mikro-orm migration:up
```

Start the service:

```bash theme={null}
npm run start:dev
```

Once `ISSUER_ORIGIN` is reachable over HTTPS, confirm the public identity routes:

```bash theme={null}
curl https://issuer.example.com/.well-known/did.json
curl https://issuer.example.com/.well-known/jwt-vc-issuer
```

`did.json` returns the issuer DID (`did:web:issuer.example.com`) with your
public keys as verification methods. Credentials are signed with header
`kid` set to `<issuer DID>#<PARTNER_PRIVATE_KEY_KID>`.

<Note>
  The credential `iss` is the `did:web` DID, while `/.well-known/jwt-vc-issuer`
  identifies the HTTPS origin. AIR verification resolves the DID document.
  Some external verifiers expect these identifiers to match exactly; test with
  the verifier you plan to support.
</Note>

## Step 3: Register the issuer with AIR

Expose the issuer backend over public HTTPS. Register the issuer under
**Dashboard → Issuer → Settings** in the sandbox or production Dashboard, then
configure its endpoint URLs:

| Item | Value |
| - | - |
| Issuer DID | `did:web:<host of ISSUER_ORIGIN>` |
| Signature type | `SD_JWT_VC` |
| API key | The backend `API_KEY` |
| Partner ID | Your Dashboard Partner ID |
| Available credentials URL (`availableVcApiUrl`) | `https://issuer.example.com/available-vc` |
| Issuance URL (`issueVcApiUrl`) | `https://issuer.example.com/issue-vc` |
| Revocation status URL (`revocationStatusApiUrl`) | Your issuer's `GET /revocation-status/:nonce` route |

After registration:

1. Confirm the Issuer DID in the Dashboard matches the `id` in your
   `/.well-known/did.json`.
2. Confirm AIR can reach both registered issuer endpoints over HTTPS.
3. Keep `API_KEY` identical to the value you registered with AIR.

AIR calls these issuer endpoints with `x-api-key`. Keep the key server-side;
your browser calls AIR Kit with a short-lived Partner JWT. A missing or incorrect
issuer API key causes the backend to return `403`.

If you enable CORS on the issuer or a proxy in front of it, allow `*.air3.com`.

## Step 4: Create schema for credential issuance

After registering your issuer, create the schema and issuance program:

1. Open the <a href="https://developers.sandbox.air3.com">Sandbox Developer Dashboard</a>.
2. Go to **Issuer → Schemas**.
3. Create a schema with a string attribute named `historical_amount`.
4. Publish the schema and record its schema ID.
5. Go to **Issuer → Programs** and create an issuance program using the
   published schema.
6. Select `SD_JWT_VC` as the signature type.
7. Record the issuance program ID.

For SD-JWT credentials, the schema ID is the credential type (`vct`) unless
your schema class sets its own. For schema design rules and supported field
types, see [Schema creation](/products/identity/schema-creation).

## Step 5: Implement the credential data

Create one schema class for each Dashboard schema. The class maps a Dashboard
schema to the claims your backend will issue and marks which claims the holder
can disclose selectively.

```ts src/issuer/sd-jwt-vc-schemas/schema_<SCHEMA_ID>.ts theme={null}
import { DisclosureFrame } from "@sd-jwt/core";
import { BaseSchema } from "./base-schema";

type Claim = {
  historical_amount: string;
};

class Schema_<SCHEMA_ID> extends BaseSchema<Claim> {
  public readonly schemaId = "<SCHEMA_ID>";
  public readonly vct = undefined; // defaults to schemaId
  public readonly ["vct#integrity"] = undefined;
  public readonly disclosureFrame: DisclosureFrame<Claim> = {
    _sd: ["historical_amount"], // claims the holder can disclose selectively
  };
  public readonly expirySec = 30 * 24 * 60 * 60;

  async generateCredentialData(userId: string) {
    // Load attributes from your database or API using userId
    return {
      credentialSubject: {
        historical_amount: "1000",
      },
      expiration: Math.floor(Date.now() / 1000) + this.expirySec,
    };
  }
}

export default new Schema_<SCHEMA_ID>();
```

Register the instance so `/available-vc` and `/issue-vc` can resolve its
`schemaId`:

```ts src/issuer/sd-jwt-vc-schemas/index.ts theme={null}
import { BaseSchema } from "./base-schema";
import HistoricalAmountSchema from "./schema_<SCHEMA_ID>";

const schemas: BaseSchema<any>[] = [HistoricalAmountSchema];

export default schemas;
```

Follow these rules:

* Claim keys and JavaScript types must match the published Dashboard schema.
* Do not return reserved claims from `generateCredentialData`: `id`, `nonce`,
  `vct`, `sub`, `exp`, `cnf`, `iss`, `iat`, or `status`. The service sets them.
* `expirySec` sets the credential's `exp`. The `expiration` you return is only
  used for the preview.
* List a claim in `disclosureFrame._sd` only if verifiers may request it on
  its own. Claims outside `_sd` are always visible in a presentation.
* Keep the backend authoritative. Do not sign claim values supplied by the
  browser without validating them against your own data.
* When you replace the static example with a database or API lookup, use the
  partner user ID at the issuer boundary for eligibility and data
  retrieval.

### Issuer endpoint contract

AIR calls both issuer endpoints during on-demand issuance: `POST /available-vc`
provides encrypted previews, and `POST /issue-vc` performs issuance after the user
confirms. The issuer validates eligibility using the AIR-resolved partner user
identifier and retrieves claims from its own data source.

<Accordion title="Issuer endpoint requests and responses">
  `POST /available-vc` accepts the holder identity and optional filters:

  ```json theme={null}
  {
    "holderDID": "did:air:...",
    "pubKey": "0x...",
    "userId": "<partner-primary-id>",
    "schemaId": "<optional-schema-id>",
    "proofType": "SD_JWT_VC"
  }
  ```

  It returns encrypted previews:

  ```json theme={null}
  {
    "data": [
      {
        "holderDID": "did:air:...",
        "schemaId": "<SCHEMA_ID>",
        "credentialSubject": {
          "encryptedData": "...",
          "iv": "...",
          "authTag": "...",
          "dataEncPublicKey": "..."
        },
        "proofType": "SD_JWT_VC"
      }
    ]
  }
  ```

  `POST /issue-vc` accepts the selected schema and the holder's signing key:

  ```json theme={null}
  {
    "holderDID": "did:air:...",
    "pubKey": "0x...",
    "userId": "<partner-primary-id>",
    "schemaId": "<SCHEMA_ID>",
    "signingKey": { "jwk": { "kty": "EC", "crv": "P-256", "x": "...", "y": "..." } },
    "proofType": "SD_JWT_VC"
  }
  ```

  On success, the issuer backend:

  1. Generates the credential data.
  2. Sets `sub` to `holderDID` and, when `signingKey` is present, `cnf` to the
     holder's public key. This binds the credential to the holder.
  3. Signs the SD-JWT VC with your partner key under the `did:web` issuer DID.
  4. Encrypts the credential to `pubKey`.
  5. Persists the issuance record when database persistence is enabled.
  6. Uploads the encrypted credential to dStorage.
  7. Returns HTTP `201` with an empty response body.

  AIR sends `x-api-key: <API_KEY>` to both endpoints. This issuer HTTP response is
  distinct from the SDK result returned to your app.
</Accordion>

## Step 6: Install AIR Kit and set up Partner authentication

Install AIR Kit in your web application:

```bash theme={null}
npm i @mocanetwork/airkit
```

Add the browser-safe and server-only values to your web environment:

```bash theme={null}
# Browser-safe
NEXT_PUBLIC_PARTNER_ID=<dashboard-partner-id>
NEXT_PUBLIC_ISSUER_DID=<issuer-did>
NEXT_PUBLIC_ISSUE_PROGRAM_ID=<dashboard-program-id>
NEXT_PUBLIC_BUILD_ENV=sandbox

# Server-only
PARTNER_PUBLIC_KEY=<public-key-body-without-pem-markers>
PARTNER_PRIVATE_KEY=<pkcs8-private-key-body-without-pem-markers>
SIGNING_ALGORITHM=RS256
```

### Set up the JWKS endpoint

Issuance fails until AIR can fetch your JWKS. Follow [JWKS endpoint](/get-started/authentication/jwks-endpoint),
then check that the registered URL returns the `kid` your Partner JWT will use.

### Sign the Partner JWT

Implement the [Next.js Partner JWT
endpoint](/get-started/authentication/sdk-auth#nextjs-partner-jwt-endpoint).
The endpoint must generate a short-lived token on the server with
`scope: "issue"` and a `kid` that appears in your registered JWKS.

## Step 7: Initialize AIR Kit and issue the credential

The frontend examples use Next.js. Create a singleton AIR service and a helper
for fetching the Partner JWT. Call these helpers from a browser event handler.

```ts lib/air.ts theme={null}
import { AirService, BUILD_ENV } from "@mocanetwork/airkit";

let servicePromise: Promise<AirService> | undefined;

export function getInitializedAirService(): Promise<AirService> {
  servicePromise ??= (async () => {
    const partnerId = process.env.NEXT_PUBLIC_PARTNER_ID;
    if (!partnerId) throw new Error("NEXT_PUBLIC_PARTNER_ID is required");

    const service = new AirService({ partnerId });
    await service.init({ buildEnv: BUILD_ENV.SANDBOX });
    return service;
  })().catch((error) => {
    servicePromise = undefined;
    throw error;
  });
  return servicePromise;
}

export async function fetchPartnerJwt(): Promise<string> {
  const response = await fetch("/api/partner-jwt", { method: "POST" });
  const body = (await response.json()) as {
    token?: string;
    error?: string;
  };

  if (!response.ok || !body.token) {
    throw new Error(
      body.error ?? `Partner JWT request failed (${response.status})`,
    );
  }

  return body.token;
}
```

Log in before starting issuance, then call `issueCredential`:

```ts theme={null}
import { fetchPartnerJwt, getInitializedAirService } from "@/lib/air";

export async function issueHistoricalAmountCredential() {
  const issuerDid = process.env.NEXT_PUBLIC_ISSUER_DID;
  const credentialId = process.env.NEXT_PUBLIC_ISSUE_PROGRAM_ID;
  if (!issuerDid || !credentialId) {
    throw new Error("Issuer DID and issuance program ID are required");
  }

  const air = await getInitializedAirService();

  if (!air.isLoggedIn) {
    await air.login();
  }

  const authToken = await fetchPartnerJwt();

  return air.issueCredential({
    authToken,
    issuerDid,
    credentialId,
    credentialSubject: {},
  });
}
```

Pass `{}` as `credentialSubject`: the AIR credential UI fetches encrypted
previews through AIR and the issuer backend supplies the authoritative claims.

The SDK promise resolves on success and rejects on failure. It does not return the VC or a dStorage path. Handle the SDK result separately from backend storage records.

## Step 8: Test end to end

Add your web app's origin under **Account → Domains**. Start the issuer backend and web app, then:

1. Open the web app.
2. Log in through AIR Kit.
3. Start credential issuance.
4. Confirm the AIR Credential UI shows the available credential.
5. Approve issuance.
6. Confirm the app receives a successful `issueCredential` result.

When database persistence is enabled, you can also check the backend issuance history:

```bash theme={null}
curl -s \
  -H "x-admin-api-key: <ADMIN_API_KEY>" \
  "https://issuer.example.com/admin/issuance-history?page=1&limit=25" \
  | jq .
```

Without database persistence, an empty history is not a failed issuance.
Confirm that the SDK completes successfully and that the holder's credential
can be discovered and used in the verification flow.

## Troubleshooting

### Issuer backend returns 403

The caller is not sending the expected `x-api-key`, or the value differs from the
backend `API_KEY`. Confirm the Partner ID, Issuer DID, and API key match what you
registered with AIR.

### AIR cannot validate the Partner JWT

Confirm the token contains `scope: "issue"` and has not expired. For JWKS and
`kid` checks, see [JWKS endpoint troubleshooting](/get-started/authentication/jwks-endpoint#troubleshooting).

### No credential preview appears

Confirm AIR can call the registered `POST /available-vc` endpoint and that the
backend returns an encrypted preview for the logged-in holder. Check the
program's issuer DID, schema, proof type, and the user's eligibility.

### Schema validation fails

Confirm that:

* `schemaId` matches the published Dashboard schema.
* Claim names and types match the schema.
* Your data does not include reserved claims such as `id`, `sub`, `vct`, or `cnf`.

### Issuer backend is unreachable

Check that the service is running, both issuer endpoint URLs are registered,
and your HTTPS domain or tunnel is reachable by AIR. If a development tunnel URL
changes, update `ISSUER_ORIGIN` and the registered URLs. This also changes the
issuer DID, so only do it before you issue credentials you want to keep.

## Next steps

* [Credential verification quickstart](/get-started/quickstarts/verify-credentials)
* [Issuing credentials](/products/identity/issuing-credentials)
* [Revoke credentials](/products/identity/revocation)
* [Issuance API reference](/api-reference/issuance-api)
* [Identity & Credential troubleshooting](/help/identity-credential)
* [AIR Credential example](https://github.com/MocaNetwork/air-credential-example)


# Quickstart: Integrating AIR Kit for login
Source: https://docs.air3.com/get-started/quickstarts/login

Install the AIR Kit Web SDK, get your Partner ID, and log users in with their AIR Account in a few steps.

Add AIR login and session handling to your web app. You can use login without integrating credential issuance or verification.

To see the login experience first, open the [single sign-on demo](https://air-bd-v2.netlify.app/demo/single-sign-on). It is a click-through, not a live session.

## Before you start

* An AIR Developer Dashboard account and Partner ID
* A web app running in the browser, with its origin added in **Account → Domains**
* A supported Node.js version for your framework and AIR Kit

You don't need a database, issuer backend, credential program, or Partner JWT for the standard AIR login shown here.

## Step 1: Install the SDK

```bash theme={null}
npm i @mocanetwork/airkit
```

## Step 2: Get your Partner ID

1. Go to the <a href="https://developers.sandbox.air3.com">Developer Dashboard</a> and sign in by connecting your EVM wallet.
   <img alt="Wallet connect" />
2. Open **Account → General Settings** and copy your **Partner ID**.
   <img alt="Quickstart - get partner ID" />

## Step 3: Initialize and log in

Create the service once in browser code. Call `loginToAir()` from a user action,
such as a login button; do not run this helper during server rendering.

```ts theme={null}
import { AirService, BUILD_ENV } from "@mocanetwork/airkit";

const service = new AirService({
  partnerId: "<your-partner-id>"
});

export async function loginToAir() {
  if (!service.isInitialized) {
    await service.init({ buildEnv: BUILD_ENV.SANDBOX });
  }
  if (!service.isLoggedIn) {
    await service.login();
  }
  return service.isLoggedIn;
}
```

This will:

* Initialize the `AirService` within the [sandbox environment](/get-started/environments/about)
* Present the SSO Login screen of AIR Kit for users to log in
* Handle authentication and session setup
* Establish the user session used by Account Services and subsequent credential flows

Login does not activate your partner's issuer or verifier functionality. Credential
operations also require registered partner authentication, the appropriate
Dashboard setup, and an active issuance or verification program.

## Session lifecycle

Use `service.isLoggedIn` to check the current session. To sign the user out, call:

```ts theme={null}
await service.logout();
```

Handle cancelled login and errors in your UI, and confirm that the user can sign
out and log in again. For session rehydration and user details, see
[Sessions & user info](/get-started/authentication/sessions).

## Next steps

* [Issuing your first credential](/get-started/quickstarts/issue-credentials) and [Verifying your first credential](/get-started/quickstarts/verify-credentials), if your app needs credentials
* [Smart accounts](/products/money/smart-account), to use the user's embedded wallet
* [Customization options](/get-started/customization/theming), to change the theme, login methods, and language


# Quickstart: Verifying your first credential
Source: https://docs.air3.com/get-started/quickstarts/verify-credentials

Configure an AIR verification program, obtain user consent, and verify the SD-JWT presentation on your backend with AIR Kit.

This guide adds credential verification to your web app. Your verification
program defines the accepted credentials and requested claims. AIR Kit handles
credential discovery, the consent screen, and presentation generation. Your
backend issues a nonce and verifies the returned SD-JWT presentation.

## Before you start

You need:

* An AIR Developer Dashboard account and Partner ID, with verifier functionality enabled
* A web app with its origin registered in the Dashboard
* A public HTTPS JWKS endpoint registered for your Partner ID
* A server endpoint that signs short-lived Partner JWTs with `scope: "verify"`
* A test holder with a matching credential from an issuer accepted by your program,
  or access to that issuer's claim flow
* A supported Node.js version for your web framework and AIR Kit

You do not need to operate an issuer backend or database to verify another
issuer's credentials. The [issuance quickstart](/get-started/quickstarts/issue-credentials)
is optional. AIR login is required for this SDK flow; the code below includes it.

## Step 1: Configure a verification program

1. Open the [Sandbox Developer Dashboard](https://developers.sandbox.air3.com/dashboard)
   and copy your Partner ID from **Account → General Settings**.
2. Under **Verifier → Programs**, create a program and select the accepted schema
   and issuer configuration.
3. Select `SD_JWT_VC` as the accepted proof type and choose the claims to request.
4. Publish or apply the program so it is active, and copy its verification program ID.

Predicate checks such as "age greater than 18" without revealing the value, and
on-chain verification, need Iden3 credentials. See
[Iden3 credentials](/products/identity/iden3-credentials).

## Step 2: Configure Partner authentication

The code below uses a Next.js app. Keep the private key on the server, including
during local development.

```bash theme={null}
npm i @mocanetwork/airkit jose
```

Set your app's environment variables:

```bash theme={null}
# Browser-safe
NEXT_PUBLIC_PARTNER_ID=<dashboard-partner-id>
NEXT_PUBLIC_VERIFY_PROGRAM_ID=<verification-program-id>

# Server-only
PARTNER_PRIVATE_KEY=<pkcs8-private-key-body-without-pem-markers>
PARTNER_PUBLIC_KEY=<public-key-body-without-pem-markers>
SIGNING_ALGORITHM=RS256
```

Verification fails until AIR can fetch your JWKS. If you haven't set one up for
this Partner ID, follow [JWKS endpoint](/get-started/authentication/jwks-endpoint). If you already
issue credentials with the same Partner ID, reuse that JWKS and key pair.

Create a server endpoint for verification tokens:

```ts app/api/verification-token/route.ts theme={null}
import { randomBytes } from "node:crypto";
import { NextResponse } from "next/server";
import { importPKCS8, SignJWT } from "jose";

export async function POST() {
  // Apply your app's session and access checks before issuing a token.
  const partnerId = process.env.NEXT_PUBLIC_PARTNER_ID;
  const privateKeyBody = process.env.PARTNER_PRIVATE_KEY;

  if (!partnerId || !privateKeyBody) {
    return NextResponse.json(
      { error: "Missing Partner JWT configuration" },
      { status: 500 },
    );
  }

  try {
    const pem = privateKeyBody.includes("BEGIN PRIVATE KEY")
      ? privateKeyBody
      : `-----BEGIN PRIVATE KEY-----\n${privateKeyBody.trim()}\n-----END PRIVATE KEY-----`;
    const key = await importPKCS8(pem, "RS256");
    const token = await new SignJWT({ partnerId, scope: "verify" })
      .setProtectedHeader({ alg: "RS256", kid: partnerId, typ: "JWT" })
      .setIssuedAt()
      .setExpirationTime("5m")
      .sign(key);

    // One-time nonce for the key-binding JWT. Store it against the user's
    // session so /api/verify-presentation can check and delete it.
    const nonce = randomBytes(16).toString("base64url");
    // await saveNonceForSession(session, nonce);

    return NextResponse.json({ token, nonce });
  } catch {
    return NextResponse.json(
      { error: "Unable to sign verification token" },
      { status: 500 },
    );
  }
}
```

This example uses your Partner ID as the JWKS key's `kid`. If your registered
key uses a different `kid`, use that value in the token header.

## Step 3: Initialize AIR Kit and start verification

Call this helper from a browser event handler, such as your **Verify** button:

```ts lib/verify-credential.ts theme={null}
import { AirService, BUILD_ENV } from "@mocanetwork/airkit";

let servicePromise: Promise<AirService> | undefined;

function getAirService(): Promise<AirService> {
  servicePromise ??= (async () => {
    const partnerId = process.env.NEXT_PUBLIC_PARTNER_ID;
    if (!partnerId) throw new Error("Partner ID is required");

    const service = new AirService({ partnerId });
    await service.init({ buildEnv: BUILD_ENV.SANDBOX });
    return service;
  })().catch((error) => {
    servicePromise = undefined;
    throw error;
  });
  return servicePromise;
}

export async function verifyCredential() {
  const programId = process.env.NEXT_PUBLIC_VERIFY_PROGRAM_ID;
  if (!programId) throw new Error("Verification program ID is required");

  const service = await getAirService();
  if (!service.isLoggedIn) await service.login();

  // Your server returns a Partner JWT and a fresh nonce stored in the session
  const response = await fetch("/api/verification-token", { method: "POST" });
  const body = (await response.json()) as {
    token?: string;
    nonce?: string;
    error?: string;
  };
  if (!response.ok || !body.token || !body.nonce) {
    throw new Error(body.error ?? "Unable to obtain verification token");
  }

  return service.verifyCredential({
    authToken: body.token,
    programId,
    fieldsToDisclose: ["historical_amount"], // or "*" for every field
    nonce: body.nonce,
  });
}
```

The nonce needs at least 128 bits of randomness, as in the token route above. If your flow needs to redirect users to an issuer when they lack
a credential, add the optional `redirectUrl` pointing to that issuer's claim page.

## Step 4: Obtain consent and handle the result

During verification, AIR Kit:

1. Finds matching credentials. If none exist, the user needs to complete an
   accepted issuer's issuance flow before verification can succeed.
2. Fetches and decrypts the credential on the holder's device.
3. Shows the requested data and asks the user to consent.
4. Records consent and generates the presentation. For a holder-bound
   credential, the holder signs a key-binding JWT over your nonce.
5. Returns the outcome to your app.

Handle both returned statuses and errors, including a cancelled flow. Grant
access only after a successful result appropriate to your application's trust
requirements.

```ts theme={null}
import { verifyCredential } from "@/lib/verify-credential";

try {
  const result = await verifyCredential();
  if (result.status === "Compliant") {
    // Verify on your backend before granting access
    const check = await fetch("/api/verify-presentation", {
      method: "POST",
      headers: { "content-type": "application/json" },
      body: JSON.stringify({
        verifiablePresentation: result.verifiablePresentation,
      }),
    });
    if (!check.ok) throw new Error("Presentation rejected");
  } else {
    console.log("Verification did not pass:", result.status);
  }
} catch {
  console.log("Verification was cancelled or could not complete. Allow a retry.");
}
```

The `Compliant` check runs in the browser, and the presentation wrapper is not
signed. Your `/api/verify-presentation` route must verify the SD-JWT inside it:
issuer signature, disclosures, expiry, credential type, and the key-binding JWT
against your nonce and `programId`. Then it deletes the nonce. Follow
[Verify SD-JWT on your backend](/products/identity/verify-sd-jwt), which
includes a reference implementation.

## Step 5: Test the integration

Test with a matching credential, a credential that fails the requested condition,
and a user who declines consent. Confirm your app handles missing credentials,
expired tokens, and failed requests without granting access.

Also confirm your backend rejects a replayed presentation (same nonce twice), a
presentation made for another `programId`, and a presentation with a disclosure
removed.

## Troubleshooting

| Symptom | Check |
| - | - |
| Partner JWT rejected | Public JWKS URL, matching `kid` and key pair, `scope: "verify"`, and token expiry |
| No matching credential | Program schema and accepted issuers, holder's credentials, and issuer claim flow |
| Backend rejects with `Key Binding JWT not exist` | The credential has a holder key but the KB-JWT is missing. Check you passed `nonce` |
| Backend rejects with `Invalid Nonce` | The nonce does not match this session's stored nonce, or it was already used |
| Program unavailable | Correct environment, active program, and enabled verifier functionality |

## Next steps

* [Verification reference](/products/identity/verify)
* [Verify SD-JWT on your backend](/products/identity/verify-sd-jwt)
* [Architecture and data flow](/technicals/architecture)
* [Credential issuance quickstart](/get-started/quickstarts/issue-credentials), if you also operate an issuer


# Bring your own auth
Source: https://docs.air3.com/get-started/recipes/bring-your-own-auth

Skip the AIR Kit login dialog and pass users from Firebase, Auth0, Supabase, or your custom auth into AIR Kit sessions using a Partner JWT.

If your app already authenticates users (via Firebase, Auth0, Supabase, or a custom system), you can bypass the AIR Kit login dialog and pass the authenticated user straight into an AIR Kit session. This is called [Custom Auth](/get-started/authentication/custom-auth).

## How it works

1. Your app authenticates the user through your own system.
2. Your backend signs a Partner JWT containing the user's `email`.
3. Your frontend passes that JWT to `airService.login({ authToken })`.
4. AIR Kit creates or loads the user's AIR Account, skipping the built-in login UI.

<Note>
  The first time an email is used, AIR verifies it with a one-time password. Later logins with that email skip this step.
</Note>

## Prerequisites

* AIR Kit SDK installed and initialized. See [Web SDK](/get-started/sdks/web).
* A Partner JWT signing key, with its public key published through a registered [JWKS endpoint](/get-started/authentication/jwks-endpoint).
* The authenticated user's email address available on your backend.

## Step 1: Generate a Partner JWT on your backend

Include `email` and `partnerId`:

```js theme={null}
const jwt = require("jsonwebtoken");
const fs = require("fs");

const privateKey = fs.readFileSync("path/to/private.key");

function getAuthToken(user) {
  const now = Math.floor(Date.now() / 1000);
  return jwt.sign(
    {
      partnerId: process.env.PARTNER_ID,
      email: user.email,
      iat: now,
      exp: now + 5 * 60,
    },
    privateKey,
    { algorithm: "RS256", header: { kid: process.env.KEY_ID, typ: "JWT" } }
  );
}

// Express example
app.get("/api/air-token", requireAuth, (req, res) => {
  const token = getAuthToken(req.user);
  res.json({ token });
});
```

## Step 2: Fetch the token and log in on the frontend

```ts theme={null}
import { AirService, BUILD_ENV } from "@mocanetwork/airkit";

const airService = new AirService({ partnerId: "your-partner-id" });
await airService.init({ buildEnv: BUILD_ENV.SANDBOX });

const res = await fetch("/api/air-token");
const { token } = await res.json();

await airService.login({ authToken: token });
```

The user is now logged in without the AIR Kit login dialog, apart from the one-time email check on first use. Their AIR Account is tied to the email from your system.

## Step 3: Use AIR Kit features normally

After login, all SDK methods work as usual — issue credentials, verify credentials, access smart accounts:

```ts theme={null}
if (airService.isLoggedIn) {
  const userInfo = await airService.getUserInfo();
  console.log("User:", userInfo);
}
```

## Next steps

* [Custom Auth](/get-started/authentication/custom-auth) for the JWT payload reference
* [SDK authentication](/get-started/authentication/sdk-auth) for signing in other languages
* [Sessions & user info](/get-started/authentication/sessions) and [MFA](/get-started/authentication/mfa)


# Task-oriented AIR Kit recipes
Source: https://docs.air3.com/get-started/recipes/index

Task-oriented AIR Kit recipes — focused, copy-paste guides for KYC issuance, loyalty credentials, custom auth, wagmi, and verification flows.

Recipes are focused, task-oriented guides that show you how to accomplish specific goals with AIR Kit. Unlike the [Solutions guides](/solutions) (organized by industry vertical), recipes answer the question "How do I do X?"

<CardGroup>
  <Card title="Issue a KYC credential" icon="webhook" href="/get-started/recipes/issue-kyc-credential">
    Wire a KYC-complete webhook to server-side issuance so credentials appear in user accounts automatically.
  </Card>

  <Card title="End-to-end loyalty credential flow" icon="gift" href="/products/loyalty/loyalty-points-issuance">
    Issue tiered loyalty credentials from your backend when users hit spend or activity thresholds.
  </Card>

  <Card title="Verify a credential" icon="circle-check" href="/get-started/recipes/verify-credential">
    Prompt a user to present a credential and gate features based on the ZK verification result.
  </Card>

  <Card title="Integrate AIR Kit with wagmi" icon="ethereum" href="/products/money/wagmi-integration">
    Use the AIR Kit wagmi connector to access smart accounts and sign transactions with React Hooks.
  </Card>

  <Card title="Bring your own auth" icon="key" href="/get-started/recipes/bring-your-own-auth">
    Skip the AIR Kit login dialog and use your existing authentication system with Partner JWT.
  </Card>
</CardGroup>


# Issue a KYC credential
Source: https://docs.air3.com/get-started/recipes/issue-kyc-credential

Wire a KYC-complete webhook to AIR credential issuance so signed, encrypted verifiable credentials land in users' AIR Accounts with no active session required.

This recipe shows how to issue a verifiable KYC credential the moment your identity provider confirms a user, using [direct issuance](/products/identity/issuing-credentials#direct-issuance). The user does not need an active session.

## What you'll build

1. A webhook handler that fires when your KYC provider confirms a user.
2. A Partner JWT signed with the `issue` scope; the user's email is sent separately to `initialize-user`.
3. A call to `initialize-user` to resolve the recipient's DID and public key.
4. Issuance: build the VC, sign it with issuer keys, encrypt it to the holder, and store it in DStorage.

## Prerequisites

* A published issuance program with a schema that includes KYC fields (e.g. `kycVerified`, `kycLevel`, `verifiedAt`)
* [Partner JWT](/get-started/authentication/sdk-auth) signing configured (RS256 or ES256)
* Issuer signing keys available to your backend

## Step 1: Handle the KYC webhook

When your KYC provider (Sumsub, Onfido, Jumio, etc.) sends a verification-complete callback, extract the user email and verification result.

```js theme={null}
const express = require("express");
const app = express();
app.use(express.json());

app.post("/webhooks/kyc-complete", async (req, res) => {
  const { userEmail, kycLevel, verifiedAt } = req.body;

  if (!userEmail) return res.status(400).json({ error: "Missing userEmail" });

  try {
    const result = await issueKycCredential(userEmail, { kycLevel, verifiedAt });
    res.json({ success: true, storagePath: result.storagePath });
  } catch (err) {
    console.error("Issuance failed:", err.message);
    res.status(500).json({ error: err.message });
  }
});
```

## Step 2: Sign a Partner JWT

Generate a short-lived JWT with `scope: "issue"`. The JWT does not carry an `email` claim — the recipient is identified in the `initialize-user` call below.

<Warning>
  The recipient's email (passed to `initialize-user`) is the routing key that determines which AIR Account the credential lands in. Resolve it from the triggering event, and never reuse a partner, service, admin, or static email across recipients — every credential issued against that email lands in the same account.
</Warning>

```js theme={null}
const jwt = require("jsonwebtoken");
const fs = require("fs");

const privateKey = fs.readFileSync("path/to/private.key");

function getPartnerJwt() {
  const now = Math.floor(Date.now() / 1000);
  return jwt.sign(
    {
      partnerId: process.env.PARTNER_ID,
      scope: "issue",
      // No email claim — the recipient is passed to initialize-user, not the JWT
      iat: now,
      exp: now + 5 * 60,
    },
    privateKey,
    {
      algorithm: "RS256",
      header: { kid: process.env.KEY_ID, typ: "JWT" },
    }
  );
}
```

## Step 3: Resolve the user and issue

Resolve the recipient's AIR Account with `initialize-user`, then build, sign, encrypt, and store the credential. `buildVc`, `signVc`, and `encryptToHolder` are issuer-controlled helpers backed by your signing keys.

```js theme={null}
const { buildVc, signVc, encryptToHolder } = require("./lib/credential");

const BASE_URL =
  process.env.NODE_ENV === "production"
    ? "https://mocachain-mainnet.api.air3.com/v1"
    : "https://api.sandbox.mocachain.org/v1";

async function issueKycCredential(recipientEmail, kycData) {
  const token = getPartnerJwt();

  // 1. Resolve or create the recipient's AIR Account
  const initRes = await fetch(`${BASE_URL}/auth/initialize-user`, {
    method: "POST",
    headers: { "Content-Type": "application/json", "x-partner-auth": token },
    body: JSON.stringify({ email: recipientEmail }),
  });
  if (!initRes.ok) throw new Error(`initialize-user failed: ${initRes.status}`);
  const { did, publicKey } = await initRes.json();

  // 2. Build, sign, and encrypt the credential (issuer-controlled)
  const schemaId = process.env.CREDENTIAL_ID;
  const vc = buildVc({
    holderDid: did,
    schemaId,
    credentialSubject: {
      kycVerified: true,
      kycLevel: kycData.kycLevel,
      verifiedAt: kycData.verifiedAt || new Date().toISOString(),
    },
  });
  const signed = signVc(vc); // SD-JWT VC, issuer-controlled key
  const encrypted = encryptToHolder(signed, publicKey);

  // 3. Store the encrypted envelope in DStorage
  const storeRes = await fetch(`${BASE_URL}/dstorage/vcs`, {
    method: "POST",
    headers: { "Content-Type": "application/json", "x-partner-auth": token },
    body: JSON.stringify({
      holderDid: did,
      schemaId,
      expiresAt: vc.expirationDate,
      data: encrypted.encryptedData,
      iv: encrypted.iv,
      authTag: encrypted.authTag,
      encryptedKey: encrypted.dataEncPublicKey,
      externalId: vc.id,
    }),
  });
  if (!storeRes.ok) throw new Error(`dstorage/vcs failed: ${storeRes.status}`);
  return storeRes.json(); // { storagePath }
}
```

Issuance typically completes in \~1–4 seconds. Record the returned `storagePath` as your issuance result; the credential is immediately available for the holder to present to any AIR verifier.

## Next steps

* [Reusable KYC demo](https://air-bd-v2.netlify.app/demo/reusable-kyc) to see the issued credential reused by a partner

* [Issuance API Reference](/api-reference/issuance-api) for full endpoint details

* [Schema Creation](/products/identity/schema-creation) to define your KYC credential schema

* [Credential Verification](/products/identity/verify) to let verifiers check the credential


# Verify a credential
Source: https://docs.air3.com/get-started/recipes/verify-credential

Gate a feature in your app on a loyalty tier credential: request the tier, verify the presentation on your backend, and unlock or restrict access.

This recipe gates a feature on a loyalty tier. When a user opens a members-only page, your app asks for their tier credential, checks the result, and unlocks the page only for qualifying tiers.

It builds on the [verification quickstart](/get-started/quickstarts/verify-credentials), which covers the setup this recipe reuses: the server route that returns a Partner JWT and nonce, and the backend route that verifies the presentation.

## Prerequisites

* The verification quickstart's `/api/verification-token` and `/api/verify-presentation` routes.
* A schema with a `tier` claim, and a test user who holds a credential from an issuer you accept.

## Step 1: Create a program that requests the tier

1. In the [Developer Dashboard](https://developers.sandbox.air3.com/dashboard), go to **Verifier → Programs** and create a program.
2. Select the schema with the `tier` claim and the issuers you accept.
3. Request the `tier` claim, and publish the program.
4. Copy the verification program ID.

## Step 2: Request the tier when the user opens the page

<Tabs>
  <Tab title="Web">
    ```ts theme={null}
    async function verifyLoyaltyTier() {
      // Your server returns a Partner JWT and a one-time nonce
      const response = await fetch("/api/verification-token", { method: "POST" });
      const { token, nonce } = await response.json();

      const result = await airService.verifyCredential({
        authToken: token,
        programId: process.env.NEXT_PUBLIC_VERIFY_PROGRAM_ID,
        fieldsToDisclose: ["tier"],
        nonce,
      });

      if (result.status === "Compliant") {
        grantAccess(result.verifiablePresentation);
      } else {
        denyAccess(result.status);
      }
    }
    ```
  </Tab>

  <Tab title="Flutter">
    ```dart theme={null}
    final token = await fetchVerificationToken(); // your server endpoint

    final result = await airService.verifyCredential(
      authToken: token,
      programId: verifyProgramId,
    );

    if (result.status == "COMPLIANT") {
      grantAccess();
    } else {
      denyAccess(result.status);
    }
    ```
  </Tab>
</Tabs>

If the user doesn't hold the credential yet, pass an optional `redirectUrl` that points to the issuer's claim page.

## Step 3: Gate the feature on the result

Only `"Compliant"` results carry a `verifiablePresentation`. Other statuses, such as `"Non-Compliant"`, `"NotFound"`, `"Expired"`, or `"Revoked"`, have none. See the [response reference](/products/identity/verify#response) for the full list.

```ts theme={null}
async function grantAccess(presentation) {
  // Verify the SD-JWT on your backend before unlocking the feature.
  const check = await fetch("/api/verify-presentation", {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify({ verifiablePresentation: presentation }),
  });
  if (check.ok) unlockFeature();
}

function denyAccess(status) {
  if (status === "Non-Compliant") {
    // Credential exists but fails the program's conditions — show a restricted view.
    return;
  }
  // Missing, pending, expired, or revoked credential — send the user to the
  // issuer flow or ask them to renew. Log `status` to distinguish the cases.
}
```

Check the disclosed `tier` value on your backend when it verifies the presentation, and unlock the page only for the tiers you allow. Wrap `verifyCredential` in `try/catch`: a cancelled consent dialog or a rejected token rejects the promise instead of returning a status.

<Warning>
  A `"Compliant"` result is checked in the user's browser, and the presentation wrapper is not signed. Before granting anything of value, verify the SD-JWT inside it on your backend, including the key-binding JWT against your nonce. See [Verify SD-JWT on your backend](/products/identity/verify-sd-jwt).
</Warning>

## Next steps

* Try it live: [member discount at a café](https://air-bd-v2.netlify.app/try-it-live/member-discount) or [show a seller you passed an ID check](https://air-bd-v2.netlify.app/try-it-live/meet-verified)

* [Verifying credentials](/products/identity/verify) for the full result shape and selective disclosure

* [Verifying your first credential](/get-started/quickstarts/verify-credentials) for the full setup

* [Schema Design](/products/identity/schema-overview) to understand which fields a program can check


# Android setup
Source: https://docs.air3.com/get-started/sdks/flutter/android-setup

Configure Android for AIR Kit Flutter — Digital Asset Links, AndroidManifest entries, network security config, build.gradle settings, and SHA fingerprints.

## Prerequisites

* Android Gradle Plugin and Kotlin versions supported by your Flutter template
* **`minSdk` 26** and **`compileSdk` 34** (required for AIR Kit)

## Asset statements (Digital Asset Links)

Create or edit `android/app/src/main/res/values/strings.xml`:

```xml theme={null}
<?xml version="1.0" encoding="utf-8"?>
<resources>
    <string name="asset_statements" translatable="false">
        [
        {"include": "https://account.air3.com/.well-known/assetlinks.json"},
        {"include": "https://account.sandbox.air3.com/.well-known/assetlinks.json"}
        ]
    </string>
</resources>
```

Reference the resource from `AndroidManifest.xml` inside `<application>`:

```xml theme={null}
<meta-data
    android:name="asset_statements"
    android:resource="@string/asset_statements" />
```

## App signing and allowlisting

Provide your app’s **SHA-256 signing certificate fingerprint** and **package name** to Moca for allowlisting (debug and release may differ). Use `keytool`:

```bash theme={null}
keytool -list -v -keystore <path-to-keystore> -alias <alias>
```

## `minSdk` and `compileSdk`

In your app-level Gradle file (Kotlin DSL or Groovy), set at least:

```kotlin theme={null}
android {
    compileSdk = 34
    defaultConfig {
        minSdk = 26
    }
}
```

## Network security config

Optional: add `android/app/src/main/res/xml/network_security_config.xml` for TLS and (if needed) local dev domains:

```xml theme={null}
<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <base-config cleartextTrafficPermitted="false">
        <trust-anchors>
            <certificates src="system" />
        </trust-anchors>
    </base-config>
    <domain-config cleartextTrafficPermitted="true">
        <domain includeSubdomains="true">10.0.2.2</domain>
    </domain-config>
</network-security-config>
```

Point `<application>` to it:

```xml theme={null}
android:networkSecurityConfig="@xml/network_security_config"
```

## Permissions

Typical requirements:

```xml theme={null}
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
```

## ProGuard / R8

If you minify release builds, add keep rules for AIR Kit, WebView, and crypto dependencies. **Verify package names** against your resolved dependencies after `flutter pub get`:

```proguard theme={null}
-keepattributes Signature,*Annotation*,EnclosingMethod,InnerClasses
# Adjust package patterns to match your app’s dependencies
-keep class com.google.android.gms.** { *; }
-dontwarn com.google.android.gms.**
```

## Verify the build

```bash theme={null}
flutter clean
flutter pub get
flutter build apk
```

## Troubleshooting

| Issue | What to check |
| - | - |
| Passkey / domain errors | Asset statements JSON, signing cert vs allowlist, `meta-data` wiring |
| WebView blank / SSL | `networkSecurityConfig`, INTERNET permission |
| Gradle conflicts | `flutter clean`, `./gradlew clean` under `android/` |

More help: [Flutter troubleshooting](/help/sdk-flutter) and [Web SDK issues](/help/sdk-web).

## Next steps

* [iOS setup](/get-started/sdks/flutter/ios-setup)
* [Google Sign-In](/get-started/sdks/flutter/google-signin) (optional)
* [Initialize](/get-started/sdks/flutter/installation#initialize)

## Reference

* [Digital Asset Links](https://developers.google.com/digital-asset-links/v1/getting-started)
* [Flutter Android deploy](https://docs.flutter.dev/deployment/android)


# Google Sign-In
Source: https://docs.air3.com/get-started/sdks/flutter/google-signin

Enable Google Sign-In in AIR Kit Flutter apps — configure OAuth client IDs in Firebase, set up Info.plist on iOS, and google-services on Android.

AIR Kit can expose **Google** as a login method when your partner configuration enables it. Configure native Google Sign-In on each platform so the SDK can complete the OAuth flow.

## Prerequisites

* [Flutter installation](/get-started/sdks/flutter/installation) and platform setup ([Android](/get-started/sdks/flutter/android-setup), [iOS](/get-started/sdks/flutter/ios-setup))
* Google Cloud / Firebase project with OAuth client IDs for your Android package name and iOS bundle ID
* Google OAuth settings aligned with the [Developer Dashboard](https://developers.sandbox.air3.com/dashboard/general)

## How it connects to AIR Kit

Partner configuration supplies the Google OAuth client behavior expected by AIR Kit. Ensure the **same OAuth clients** you configure in Firebase are the ones you share with Moca for manual dashboard setup (see [Dashboard](#dashboard)).

## iOS

1. In [Firebase Console](https://console.firebase.google.com/), add an iOS app with your bundle ID.
2. Download `GoogleService-Info.plist` and add it to `ios/Runner/` in Xcode (copy if needed).
3. In `Info.plist`, add `CFBundleURLTypes` using the **`REVERSED_CLIENT_ID`** from `GoogleService-Info.plist` as the URL scheme (see Google’s Flutter / iOS Sign-In docs).

## Android

1. In Firebase, add an Android app with your **application ID** (package name).
2. Download `google-services.json` to `android/app/`.
3. In the **project** `android/build.gradle`, include the Google services classpath if required by your template.
4. In the **app** `android/app/build.gradle`, apply the Google Services plugin per [FlutterFire / Google Sign-In setup](https://pub.dev/packages/google_sign_in).

## Dashboard

Partners must provide the **Google OAuth client IDs** for iOS and Android (from Firebase / Google Cloud). The Developer Dashboard does **not** yet let partners enter these values themselves. Moca sets them **manually** for your partner, the same way as other allowlisted values (for example Android signing certificate fingerprints and iOS app identifiers — see [Android setup](/get-started/sdks/flutter/android-setup) and [iOS setup](/get-started/sdks/flutter/ios-setup)).

Enable Google as a login method in partner configuration once your client IDs are on file. To add or update client IDs, contact the AIR team.

## Troubleshooting

| Symptom | Checks |
| - | - |
| `redirect_uri_mismatch` | iOS URL scheme matches `REVERSED_CLIENT_ID`; OAuth client matches bundle ID |
| Google button missing | Partner config; correct `partnerId` and environment |
| Android build errors | `google-services.json` path; package name; Play Services on device |

## Security

* Do not commit `GoogleService-Info.plist` or `google-services.json` to public repos if they contain secrets; use CI secrets or private config distribution.

## Next steps

* [Login](/get-started/authentication/login)
* [SDK authentication](/get-started/authentication/sdk-auth)
* [Sessions & user info](/get-started/authentication/sessions)

## Reference

* [Google Sign-In for Flutter](https://pub.dev/packages/google_sign_in)
* [Google Sign-In iOS](https://developers.google.com/identity/sign-in/ios/start)
* [Google Sign-In Android](https://developers.google.com/identity/sign-in/android/start)


# Install the AIR Kit SDK
Source: https://docs.air3.com/get-started/sdks/flutter/installation

Install the AIR Kit Flutter SDK via OnePub, configure minimum platform versions for iOS and Android, and add it to your pubspec.yaml.

## Prerequisites

* Flutter SDK and Dart toolchain on your PATH
* OnePub access (credentials provided by Moca)
* Android: `compileSdk` 34+, `minSdk` 26+ (see [Android setup](/get-started/sdks/flutter/android-setup))
* iOS: platform 14.0+ in `Podfile` (see [iOS setup](/get-started/sdks/flutter/ios-setup))

<Note>
  Production mobile apps should use the production AIR pages and domains, including `account.air3.com` for passkey setup. Moca Chain mainnet is live; see [Production mainnet access](/get-started/environments/about#production-mainnet-access).
</Note>

## OnePub CLI

```bash theme={null}
dart pub global activate onepub
onepub login
```

<Warning>
  If `onepub` is not found, add Pub’s global bin directory to your PATH, for example: `export PATH=$PATH:$HOME/.pub-cache/bin`
</Warning>

## Add the dependency

**Option A — `pubspec.yaml`**

```yaml theme={null}
dependencies:
  airkit:
    hosted: https://onepub.dev/api/sxhddavuhn/
    version: ^1.6.0
```

Use the version your team recommends; check [Release notes](/api-reference/release-notes) for current Flutter SDK versions.

**Option B — CLI**

```bash theme={null}
onepub pub add airkit
```

Then run:

```bash theme={null}
flutter pub get
```

## Import

```dart theme={null}
import 'package:airkit/airkit.dart';
```

## Initialize

Create an `AirService` instance and call `initialize`:

```dart theme={null}
Future<void> initialize({
    required String partnerId,
    required GlobalKey<NavigatorState> navigatorKey,
    Environment env = Environment.production,
    bool enableLogging = false,
})
```

You receive your `partnerId` from us. The `navigatorKey` is used to overlay the dialogs that specific user flows need. During development, use `Environment.sandbox` and enable logging.

```dart theme={null}
final navigatorKey = GlobalKey<NavigatorState>();
final airService = AirService();

await airService.initialize(
  partnerId: 'YOUR_PARTNER_ID',
  navigatorKey: navigatorKey,
  env: Environment.sandbox,
  enableLogging: true,
);

// In MaterialApp: navigatorKey: navigatorKey
```

## Next steps

1. [Android setup](/get-started/sdks/flutter/android-setup) — asset statements, manifest, network security
2. [iOS setup](/get-started/sdks/flutter/ios-setup) — associated domains, `Podfile`
3. [Google Sign-In](/get-started/sdks/flutter/google-signin) if you use Google login


# iOS setup
Source: https://docs.air3.com/get-started/sdks/flutter/ios-setup

Configure iOS for AIR Kit Flutter — Associated Domains, Podfile entries, passkey entitlements, and minimum deployment target for in-app login.

## Prerequisites

* Xcode and CocoaPods
* **iOS deployment target 14.0+** in `Podfile` (required for AIR Kit)

## Associated Domains

1. Open `ios/Runner.xcworkspace` in Xcode.
2. Select the **Runner** target → **Signing & Capabilities**.
3. Add **Associated Domains**.
4. Add the domains you use:

```
webcredentials:account.air3.com
webcredentials:account.sandbox.air3.com
```

Optional for non-production testing:

```
webcredentials:account.staging.air3.com
webcredentials:account.uat.air3.com
```

<Note>
  Include only environments you actually use. Production and sandbox are the usual minimum.
</Note>

## App ID allowlisting

Provide Moca with your **Apple Team ID** and **bundle identifier** in the form `TEAMID.com.example.app`.

## Podfile

Set the platform version:

```ruby theme={null}
platform :ios, '14.0'
```

Then:

```bash theme={null}
cd ios
pod install
```

## Info.plist (optional)

If you need ATS exceptions for specific domains, configure them narrowly in `Info.plist`. Prefer default secure TLS where possible.

Optional usage strings if you add camera / photo features:

```xml theme={null}
<key>NSCameraUsageDescription</key>
<string>Required for features that use the camera.</string>
```

## Testing

* Passkeys and full WebAuthn behavior require a **physical device** in many cases.
* Build with `flutter build ios` and run from Xcode or `flutter run`.

## Troubleshooting

| Issue | What to check |
| - | - |
| Domain verification failures | Capability enabled, correct team, provisioning profile, domains spelled correctly |
| `pod install` errors | `rm -rf Pods Podfile.lock`, `pod repo update`, `pod install` |
| WebView / network | Associated Domains, device network, ATS settings |

See also [Flutter troubleshooting](/help/sdk-flutter).

## Next steps

* [Google Sign-In](/get-started/sdks/flutter/google-signin) (optional)
* [Initialize](/get-started/sdks/flutter/installation#initialize)
* [Login](/get-started/authentication/login)

## Reference

* [Associated Domains](https://developer.apple.com/documentation/xcode/supporting-associated-domains)
* [Flutter iOS deploy](https://docs.flutter.dev/deployment/ios)


# Overview
Source: https://docs.air3.com/get-started/sdks/flutter/overview

Integrate AIR Kit in Flutter apps for AIR Account login, embedded wallets, credential issuance and verification, and native UI flows on iOS and Android.

The AIR Kit Flutter SDK brings AIR Account login, the embedded wallet, and credential issuance and verification to iOS and Android apps. Set it up with [Installation](/get-started/sdks/flutter/installation), then [Android setup](/get-started/sdks/flutter/android-setup) and [iOS setup](/get-started/sdks/flutter/ios-setup). See [Platform support](/get-started/sdks/platform-support) for supported versions.

## Credentials on Flutter

`issueCredential` and `verifyCredential` are available on Flutter. The [issuance](/get-started/quickstarts/issue-credentials) and [verification](/get-started/quickstarts/verify-credentials) quickstarts use Web code, but the issuer service, Dashboard setup, and Partner JWT steps are the same. [Direct issuance](/api-reference/issuance-api) runs on your backend, so it works with any client.

## Authentication on Flutter

On Flutter, sign-in uses `login` with a **Partner JWT** (`authToken`) after `initialize()`. See [Login](/get-started/authentication/login) (Flutter tab) and [SDK authentication](/get-started/authentication/sdk-auth).

## Environment and dashboard

Use the [Developer Dashboard](https://developers.sandbox.air3.com/dashboard) for partner ID, programs, and configuration. Environment values match [Environments](/get-started/environments/about) (`Environment.sandbox`, `production`, etc.).

## Troubleshooting

See [Flutter troubleshooting](/help/sdk-flutter) for common setup and login issues.


# Provider functions
Source: https://docs.air3.com/get-started/sdks/flutter/provider-functions

Call EIP-1193 Ethereum JSON-RPC methods through AirService on Flutter — eth_accounts, eth_chainId, eth_sendTransaction, and more for smart accounts.

On Flutter, `AirService.sendEthereumRpcRequest` exposes an **EIP-1193-style** surface for common RPC methods. Use it directly or wrap it for libraries like **web3dart**.

<Note>
  **wagmi** is for web React apps. For wagmi, see [Wagmi integration](/products/money/wagmi-integration) and the Web SDK [provider](/products/money/provider-functions) docs.
</Note>

## Request and response shapes

See [Reference](/api-reference/sdk-reference) (Flutter tab) for `EthereumRpcRequest` and `EthereumRpcSuccessResponse`.

## Examples

### `eth_accounts` and `eth_chainId`

```dart theme={null}
final accountsRes = await airService.sendEthereumRpcRequest(
  EthereumRpcRequest(method: 'eth_accounts', params: []),
);
final chainRes = await airService.sendEthereumRpcRequest(
  EthereumRpcRequest(method: 'eth_chainId', params: []),
);
```

### `eth_getBalance`

```dart theme={null}
final address = await airService.getAbstractAccountAddress();
if (address != null) {
  final res = await airService.sendEthereumRpcRequest(
    EthereumRpcRequest(
      method: 'eth_getBalance',
      params: [address, 'latest'],
    ),
  );
}
```

### Switch or add chain

```dart theme={null}
await airService.sendEthereumRpcRequest(
  EthereumRpcRequest(
    method: 'wallet_switchEthereumChain',
    params: [
      {'chainId': '0x1'},
    ],
  ),
);
```

## web3dart

You can implement a thin adapter that forwards `JsonRpc` calls to `sendEthereumRpcRequest`. Keep the adapter in your app repo and test against your SDK version.

## Next steps

* [Wallet operations](/get-started/sdks/flutter/wallet-operations)
* [Supported chains](/products/money/supported-chains)


# UI components
Source: https://docs.air3.com/get-started/sdks/flutter/ui-components

Use built-in AIR Kit UI components on Flutter — native login screen plus hosted UI for token swap, fiat on-ramp, and multi-factor authentication.

AIR Kit exposes **native Flutter UI** for login and several **hosted UI flows** through `AirService`. APIs below match the [Reference](/api-reference/sdk-reference) Flutter tab.

## Prerequisites

* [Initialization](/get-started/sdks/flutter/installation#initialize) with a valid `GlobalKey<NavigatorState>` on `MaterialApp`
* For **Swap**, **On-ramp**, and **MFA** below: an authenticated session after `login`
* Optional: `preloadWallet()` before opening wallet UIs for smoother first open

## Login

`login` presents **native Flutter UI** for the configured login methods. After `initialize()`, call `login` with your **Partner JWT** (`authToken`) as described in [Login](/get-started/authentication/login) (Flutter tab).

## Swap UI

```dart theme={null}
await airService.showSwapUi();
```

## On-ramp UI

```dart theme={null}
await airService.showOnRampUi(
  displayCurrencyCode: 'USD',
  targetCurrencyCode: 'ETH', // optional
);
```

## MFA setup

```dart theme={null}
await airService.setupOrUpdateMfa();
```

Check status via `getUserInfo()` → `user.isMFASetup` (see Reference models).

## Theming, locale, and currency

Web SDK uses `sessionConfig` / `updateSessionConfig` on `init`. For Flutter, confirm behavior in your SDK version and [Release notes](/api-reference/release-notes). Dashboard and partner configuration also affect login and widget appearance — see [Theming](/get-started/customization/theming) and [Language support](/get-started/customization/language) and [Other options](/get-started/customization/other-options) for product-level options.

## Web-first built-in UI

Some Account Services UIs documented under [Built-in UI](/products/money/builtin-ui) are Web-first; Flutter parity varies by release. Confirm APIs and behavior in the [Reference](/api-reference/sdk-reference) Flutter tab and [Release notes](/api-reference/release-notes).

## Next steps

* [Wallet operations](/get-started/sdks/flutter/wallet-operations)
* [Login](/get-started/authentication/login)


# Wallet operations
Source: https://docs.air3.com/get-started/sdks/flutter/wallet-operations

Use AirService on Flutter to fetch accounts, balances, sign messages, and call smart contract methods from the embedded AIR Kit wallet.

After [initialization](/get-started/sdks/flutter/installation#initialize) and login, use `AirService` for embedded wallet operations. Method names match the [Reference](/api-reference/sdk-reference) Flutter tab.

## Prerequisites

* `await airService.initialize(...)` completed
* User authenticated (see [Login](/get-started/authentication/login))
* Optional: `await airService.preloadWallet()` before first wallet UI or heavy RPC use

## Accounts and address

```dart theme={null}
final accounts = await airService.getAccounts();
final address = await airService.getAbstractAccountAddress();
```

## Balances

```dart theme={null}
final address = await airService.getAbstractAccountAddress();
if (address != null) {
  final balanceWei = await airService.getBalance(address);
  // Format for display (example: 18 decimals)
}
```

## Sign messages

```dart theme={null}
final signature = await airService.signMessage('Hello from AIR Kit');
```

## Contract reads (`call`)

```dart theme={null}
final result = await airService.call(
  '0xContractAddress',
  'balanceOf',
  [/* parameters */],
  erc20AbiJsonString,
);
```

## Transactions (`sendTransaction`)

Use `web3dart` `Transaction` / `Transaction.callContract` types as in your SDK version:

```dart theme={null}
import 'package:web3dart/web3dart.dart';

// Example shape — adjust gas, chain, and contract types to your app
final txHash = await airService.sendTransaction(transaction);
```

## Smart account deployment

```dart theme={null}
final deployed = await airService.isSmartAccountDeployed();
if (!deployed) {
  final txHash = await airService.deploySmartAccount();
}
```

## Built-in wallet UI

* Swap: `await airService.showSwapUi();`
* On-ramp: `await airService.showOnRampUi(displayCurrencyCode: 'USD');`

See [UI components](/get-started/sdks/flutter/ui-components).

## Error handling

Catch `AirKitException` and inspect `type` (`client`, `sdk`, `server`, `unknown`) for logging and user messaging.

## Next steps

* [Provider functions](/get-started/sdks/flutter/provider-functions) — raw JSON-RPC
* [Account Services](/products/money/smart-account) — product concepts (web-centric sections may still apply conceptually)
* [Paymaster](/products/money/paymaster) — gas sponsorship where supported


# Platform support
Source: https://docs.air3.com/get-started/sdks/platform-support

Supported platforms, browsers, frameworks, and module formats for the AIR Kit Web and Flutter SDKs, plus server languages for direct issuance.

## SDK Packages

| SDK | Package | Install |
| - | - | - |
| Web (JS / TS) | `@mocanetwork/airkit` | `npm i @mocanetwork/airkit` |
| Flutter | `airkit` (Dart) | OnePub hosted — see [Flutter installation](/get-started/sdks/flutter/installation) |

For the latest version numbers see [Release Notes](/api-reference/release-notes).

## Platform Support

| Platform | Web SDK | Flutter SDK |
| - | :-: | :-: |
| Web (Browser) | ✓ | — |
| iOS (native) | — | ✓ |
| Android (native) | — | ✓ |
| React Native | Partial — WebView only | — |
| Electron | ✓ | — |

## Browser Support (Web SDK)

| Browser | Minimum Version | Notes |
| - | :-: | - |
| Chrome / Chromium | 126+ | Full support (passkey required) |
| Firefox | 97+ | Full support (passkey required) |
| Safari | 16+ | Full support (passkey required) |
| Edge | 126+ | Full support (Chromium-based) |
| Opera | 112+ | Full support (Chromium-based) |
| Samsung Internet | 14+ | Full support |
| IE 11 | ✗ | Not supported |

## Framework Compatibility (Web SDK)

| Framework | Status | Notes |
| - | :-: | - |
| React 17+ | ✓ | Full support |
| React 16 | ✓ | Full support |
| Next.js 13+ (App Router) | ✓ | Add `'use client'` directive to the initializing component |
| Next.js 12 (Pages Router) | ✓ | Full support |
| Vue 3 | ✓ | Full support |
| Vue 2 | ✓ | Full support |
| Nuxt 3 | ✓ | Full support |
| SvelteKit | ✓ | Full support |
| Angular 14+ | ✓ | Full support |
| Vanilla JS | ✓ | UMD / ESM builds available |

## Module Formats (Web SDK)

| Format | Import | Best For |
| - | - | - |
| ESM (`dist/airkit.esm.js`) | `import { AirService } from '@mocanetwork/airkit'` | Vite, Webpack 5, modern bundlers |
| CommonJS (`dist/airkit.cjs.js`) | `const { AirService } = require('@mocanetwork/airkit')` | Node.js, older bundlers |
| UMD (`dist/airkit.umd.min.js`) | `<script>` CDN tag | No-bundler / script-tag setups |

Your bundler picks the right build. To force a format, import its file directly.

## Direct issuance: server language support

[Direct issuance](/products/identity/issuing-credentials#direct-issuance) is HTTP plus a signed JWT, so any backend language works. Common JWT libraries:

| Language | Library |
| - | - |
| Node.js | `jsonwebtoken` |
| Java | `com.auth0:java-jwt` |
| C# | `System.IdentityModel.Tokens.Jwt` |
| Go | `github.com/golang-jwt/jwt/v5` |
| Python | `PyJWT` |
| Ruby | `ruby-jwt` |
| PHP | `firebase/php-jwt` |

See full signing examples for Node.js, Java, C#, and Go in [SDK authentication](/get-started/authentication/sdk-auth#examples).


# Web SDK
Source: https://docs.air3.com/get-started/sdks/web

Install the AIR Kit Web SDK from npm, then create and initialize the AirService instance with your Partner ID and environment.

## Install

<Info>
  **Latest version:** `1.12.1` — install with `npm i @mocanetwork/airkit@1.12.1`, or omit the version tag to get the latest release from npm. See [Release notes](/api-reference/release-notes) for changes and migration guidance.
</Info>

```bash theme={null}
npm i @mocanetwork/airkit
```

The package ships ESM, CommonJS, and UMD builds, and your bundler picks the right one. See [Platform support](/get-started/sdks/platform-support#module-formats-web-sdk) for supported browsers, frameworks, and formats.

## Initialize

AIR Kit creates an iframe that loads the login flow and sets up communication streams between the iframe and the DApp's JavaScript context.

```js theme={null}
import { AirService, BUILD_ENV } from "@mocanetwork/airkit";

const airService = new AirService({
  partnerId: YOUR_PARTNER_ID // Replace with your actual Partner ID
});
await airService.init({
  buildEnv: BUILD_ENV.SANDBOX,
  enableLogging: true,
  preloadWallet: true, // Optional: Enable if wallet features will be used
  preloadCredential: true, // Optional: Enable if credential features will be used
  sessionConfig: {
    locale: "en", // Optional: Enforce a locale; omit for automatic language selection
    currency: "USD" // Optional: Display currency (e.g. "EUR", "USD", ...)
  }
});

// Without any parameters, this will trigger the default Air login dialog which provides different login methods for the user to choose from.
await airService.login();
```

Once `AirService` is initialized, you can use it to authenticate users. See [Login](/get-started/authentication/login).

AIR Kit bundles `en`, `ja`, `ko`, `tr`, and `vi`. To customize copy or add languages, use hosted JSON in partner configuration. See [Language support](/get-started/customization/language).

## Next steps

* Building a mobile app? See the [Flutter SDK](/get-started/sdks/flutter/overview).


# What is AIR Kit?
Source: https://docs.air3.com/get-started/what-is-airkit

AIR Kit is the SDK and set of APIs for adding AIR Account login, embedded smart accounts, and verifiable credentials to web and mobile apps.

AIR Kit is the SDK and set of APIs you use to add AIR to your app. With it, your users sign in with an AIR Account, hold assets in an embedded smart account, and carry verifiable credentials that other apps can check with their consent.

AIR stands for **Account, Identity, Reputation**. Each user has one AIR Account that works across every app that integrates AIR Kit, so a user who signed in to one partner app can sign in to yours with the same account.

## What you can build

| Capability | What it gives your app | Start here |
| - | - | - |
| **Login** | Google and passwordless email login, single sign-on across AIR apps, and session handling. You can also keep your own login and pass users in. | [Login quickstart](/get-started/quickstarts/login) |
| **Credentials** | Issue credentials from your own data, signed with your keys and encrypted to the user. Verify credentials from other issuers, receiving only the claims you request. | [Credentials overview](/products/identity/credentials-flow) |
| **Smart accounts** | A wallet tied to the user's AIR Account, with no seed phrase, sponsored gas, and EVM tooling support. | [AIR Money](/products/money/what-is-air-money) |
| **Agents** | Let an AI agent act for a user, with verifiable proof of who it represents and what it may do. | [AIR Agent](/products/agents/what-is-air-agents) |

Credentials, smart accounts, and agents all build on the user's AIR Account. You can use login on its own and add the rest later.

## How an integration fits together

An AIR Kit integration has up to four parts:

1. **Your app** loads the AIR Kit SDK ([Web](/get-started/sdks/web) or [Flutter](/get-started/sdks/flutter/overview)), which shows the AIR login, consent, and wallet screens.
2. **The Developer Dashboard** holds your Partner ID, allowed domains, and the schemas and programs that define what you issue and verify.
3. **Your backend** signs short-lived Partner JWTs that authenticate your app to AIR. If you issue credentials, it also runs an issuer service that signs them.
4. **AIR and Moca Chain** store encrypted credentials and run login, wallet, and verification services. AIR never sees the plaintext of a credential.

<img alt="Moca Network = AIR Kit + Moca Chain" />

## Where to start

<CardGroup>
  <Card title="Integrate login" icon="right-to-bracket" href="/get-started/quickstarts/login">
    Install the SDK and log a user in.
  </Card>

  <Card title="Issue a credential" icon="file-signature" href="/get-started/quickstarts/issue-credentials">
    Run an issuer service and issue your first credential.
  </Card>

  <Card title="Verify a credential" icon="circle-check" href="/get-started/quickstarts/verify-credentials">
    Request a credential and verify it on your backend.
  </Card>
</CardGroup>

Not sure AIR Kit fits your use case? See [When to use AIR Kit](/get-started/when-to-use-airkit).


# When to use AIR Kit
Source: https://docs.air3.com/get-started/when-to-use-airkit

Decide whether AIR Kit fits your use case — when AIR Account login and verifiable credentials are a good fit, and when another approach works better.

AIR Kit has two main parts you can adopt separately: **AIR Account** for login and wallets, and **AIR Credentials** for issuing and verifying claims about users. Use this page to check whether each one fits.

## AIR Account

**A good fit when you want to:**

* Let users sign in with Google or email and get a wallet, without installing anything or managing a seed phrase.
* Share one account with other apps in the AIR ecosystem, so returning users don't sign up again.
* Add a wallet to an app that already has its own login, by passing your users in with [Custom Auth](/get-started/authentication/custom-auth).

**Consider another approach when:**

* You need full control over the identity provider, account recovery, and user database, and don't want users to have a shared account across apps.
* Your users must sign in only with their own external wallet. Wallet login is available as an add-on, not by default. See [EOA wallet authentication](/get-started/authentication/login#eoa-wallet-authentication-optional-add-on).

## AIR Credentials

**A good fit when you want to:**

* Let users prove something about themselves, such as a KYC result, membership tier, or age, without sending you the underlying documents.
* Reuse a check another issuer has already done, so users don't repeat KYC or onboarding for every app.
* Issue claims from your own data that users can present to partners, with no direct API integration between you and each partner.
* Receive only the fields you need, so you store less personal data.

**Consider another approach when:**

* The data changes faster than you can reissue credentials, such as a live account balance. Query it directly from the source instead.
* You need predicate checks, such as "older than 18" without revealing the birth date, or on-chain verification. These need [Iden3 credentials](/products/identity/iden3-credentials), which the AIR team enables on request.
* The check depends on a person reviewing documents or images. Do that review in your own flow, then issue a credential with the result.

## Next steps

* [What is AIR Kit?](/get-started/what-is-airkit)
* [Credential formats](/products/identity/credential-formats) to compare SD-JWT and Iden3 credentials
* [Login quickstart](/get-started/quickstarts/login)


# Common Issues
Source: https://docs.air3.com/help/common-issues

Troubleshoot the most frequent AIR Kit integration issues — Partner JWT signing and JWKS retrieval, CORS, and rate limiting.

These are the issues most AIR Kit integrations run into first. To look up a specific HTTP status or SDK error name see [Error codes](/help/error-codes). For platform-specific problems, see [Web](/help/sdk-web) and [Flutter](/help/sdk-flutter). For issuance, verification, and schema problems, see [Identity & Credential](/help/identity-credential).

## JWT and JWKS errors

### "Invalid signature" or "JWT verification failed"

* Confirm the `kid` in your JWT header matches a key ID in your JWKS endpoint.
* Verify the algorithm (`RS256` or `ES256`) matches the key type in your JWKS.
* Check that you are signing with the correct private key.

### "Token expired"

* The `exp` claim has passed. Generate a new JWT with a fresh `exp` (recommended: 5 minutes from now).
* Verify your server clock is synchronized (NTP).

### "JWKS endpoint unreachable"

* Your JWKS URL must be publicly accessible over HTTPS — AIR servers cannot reach `localhost`. Use an HTTPS tunnel (ngrok, cloudflared) or deploy.
* Test the **exact URL registered in the Developer Dashboard**, not a guess. For example:

```bash theme={null}
curl https://your-domain/api/.well-known/jwks
```

* `air-examples` ships `/api/.well-known/jwks`; the plug-and-play template ships `/jwks.json`. Register whichever your app actually serves.
* Ensure no firewall or IP allowlist blocks AIR servers.
* Full setup procedure: [JWKS endpoint setup](/get-started/authentication/jwks-endpoint).

### "kid not found"

* The `kid` in your JWT header does not match any key in the JWKS response.
* If you recently rotated keys, publish the new key to your JWKS endpoint before using it in JWTs.

### "Missing typ header"

* For server-side issuance, the JWT header must include `typ: "JWT"`. Add it to your JWT signing options:

```js theme={null}
jwt.sign(payload, privateKey, {
  algorithm: "RS256",
  header: { kid: "your-key-id", typ: "JWT" },
});
```

## CORS errors

If you see CORS errors when initializing the SDK in a browser:

* AIR Kit uses an iframe for login. Ensure your `Content-Security-Policy` allows `frame-src` from `*.air3.com`.
* If you are proxying requests, ensure the `Origin` header is forwarded correctly.

## Rate limiting

API endpoints may return `429 Too Many Requests` if you exceed rate limits. Back off and retry with exponential delays. Avoid tight polling loops on the status endpoint — start with 1-second intervals and double each attempt.


# Error Codes
Source: https://docs.air3.com/help/error-codes

AIR Kit error reference — REST API HTTP status codes and SDK error names for client, authentication, passwordless, and account linking failures.

Use this page as a lookup when the AIR Kit REST API returns a specific HTTP status, or when the SDK throws an `AirError` with a known `name`. For higher-level JWT / JWKS / CORS / rate-limit guidance, see [Common issues](/help/common-issues).

## API error codes

These errors apply to the AIR Kit REST API (e.g. [Issuance API](/api-reference/issuance-api)).

| HTTP status | Likely cause | How to fix |
| - | - | - |
| 400 | Missing or invalid request fields | Verify `holderDid`, `schemaId`, `expiresAt`, `data`, `iv`, `authTag`, `encryptedKey`, and `externalId` are present and correctly typed, and that the credential data matches your schema. |
| 401 | Invalid or expired Partner JWT | Verify the JWT is not expired (`exp`), the signature matches your JWKS key, `kid` in the header maps to the correct key, and `typ: "JWT"` is set. |
| 403 | Feature not enabled or schema not allowed | Confirm credential issuance is enabled for your partner account in the Developer Dashboard. Check that your `issuerDid` owns the schema. |
| 404 | Unknown issuer DID or program ID | Double-check `issuerDid` and `credentialId` values against the Developer Dashboard. |
| 409 | User consent rejected or duplicate conflict | The user has denied consent for credentials issued on their behalf, or a duplicate credential already exists for this user + schema. Dedupe before reissuing. |
| 429 | Rate limited | Back off and retry — see [Rate limiting](/help/common-issues#rate-limiting). |
| 500 | Server-side failure | Retry with exponential backoff. If persistent, check the [Status page](/help/status) or contact support. |

## SDK error names

Errors thrown by the SDK are `AirError` instances carrying a stable, machine-readable `name`. Branch on `name` rather than matching on the message, which is not part of the API contract.

```js theme={null}
try {
  await airService.login();
} catch (err) {
  if (err.name === "USER_CANCELLED") return; // expected, not a failure
  console.error(err.name, err.message);
}
```

### Client and user errors

| Name | Meaning | How to handle |
| - | - | - |
| `USER_CANCELLED` | The user closed or dismissed an AIR Kit flow | Expected control flow — return quietly rather than surfacing an error |
| `USER_REJECTED` | The user declined a specific request, such as signing or consent | Leave the user where they were and let them retry |
| `CONFIG_ERROR` | Invalid AIR Kit configuration | Check your `partnerId`, `BUILD_ENV`, and `init()` options |
| `PERMISSION_NOT_ENABLED` | The feature is not enabled for your partner account | Enable it in the Developer Dashboard, or contact support |
| `ACCOUNT_DELETION_PENDING` | The account has a pending deletion request | Prompt the user to cancel deletion before continuing |
| `WINDOW_BLOCKED` | The browser blocked a popup AIR Kit needed | Trigger the call directly from a user gesture so the popup is not blocked |
| `WINDOW_CLOSED` | The user closed the AIR Kit popup before it finished | Treat like a cancellation |

### Authentication and token errors

| Name | Meaning | How to handle |
| - | - | - |
| `PARTNER_TOKEN_EXPIRED` | The Partner JWT you passed is past its `exp` | Mint a fresh JWT and retry. See [Partner authentication](/get-started/authentication/sdk-auth) |
| `PARTNER_ACCESS_TOKEN_INVALID` | The Partner JWT failed validation | Check signing key, `kid`, and payload — see [JWT and JWKS errors](/help/common-issues#jwt-and-jwks-errors) |
| `USER_MISMATCH` | The token identifies a different user than the active session | Log out before switching users |
| `TOKEN_EXPIRED` / `INVALID_TOKEN` / `UNAUTHORIZED` | The AIR session token is expired or rejected | Re-run `login()` |

### Passwordless and OTP errors

| Name | Meaning | How to handle |
| - | - | - |
| `PASSWORDLESS_INVALID_CODE` | Wrong one-time password entered | Let the user retype it |
| `PASSWORDLESS_CODE_EXPIRED` | The one-time password expired | Request a new code |
| `PASSWORDLESS_MAX_ATTEMPTS` | Too many incorrect attempts | Ask the user to request a new code |
| `PASSWORDLESS_HOURLY_LIMIT` / `PASSWORDLESS_LOCK_EXCEEDED` | Rate limit reached for this identifier | Ask the user to try again later |

### Linking errors

| Name | Meaning | How to handle |
| - | - | - |
| `LINK_WALLET_ALREADY_LINKED` | The wallet is already linked to this account | No action needed |
| `LINK_WALLET_LINKED_OTHER_ACCOUNT` | The wallet belongs to a different AIR account | Ask for a different wallet |
| `LINK_EMAIL_LINKED_OTHER_ACCOUNT` | The email belongs to a different AIR account | Ask for a different email |


# Frequently Asked Questions
Source: https://docs.air3.com/help/faq

Frequently asked questions about AIR Kit and Moca Chain — credential issuance and storage, costs, $MOCA, performance, decentralized storage, and developer support.

## AIR Kit and credentials

<Accordion title="How are credentials issued and stored?">
  The issuer signs the credential and encrypts it to the holder before storage. Raw source documents remain with the issuer. Encrypted credential payloads may be stored in DStorage, while users control decryption and disclosure.

  Read more about the credential issuance process <a href="/products/identity/credentials-flow#issuer-process">here</a>

  <br />

  Read more about the credential verification process <a href="/products/identity/credentials-flow#verifier-process">here</a>
</Accordion>

<Accordion title="Does it cost anything to issue and verify credentials?">
  Both credential issuance and verification can incur on-chain gas fees, hence the <a href="/get-started/dashboard/features">developer dashboard</a> provides a dedicated wallet that verifiers can pre-fund with \$MOCA.
</Accordion>

## Moca Chain

<Accordion title="What makes Moca different from generic L1 chains?">
  Moca Chain is an EVM-compatible L1 purpose-built for decentralized identity. Moca Chain is designed with identity at its core, making credentials portable across the apps that use AIR verification. It puts privacy first with ZKPs and zkTLS, ensures resilient decentralized storage for credentials, and stays developer-friendly through full EVM compatibility. With \~1s block times and instant finality, it delivers the speed and reliability needed for real-world identity use cases. Read more <a href="/technicals/mocachain/why-mocachain">here</a>.
</Accordion>

<Accordion title="What do Moca Chain's performance metrics look like?">
  Currently the Moca Chain offers 1-second block time with instant finality. Each block holds up to 800 transactions.
</Accordion>

<Accordion title="Can I store any data on Moca Chain?">
  Moca Chain supports object storage through DStorage. Storage providers hold payloads; the chain records object metadata, payments, and permissions. Storage operations require \$MOCA for gas and storage costs.
</Accordion>

## \$MOCA

<Accordion title="What is \$MOCA's role in Moca Chain?">
  `$MOCA` plays an important role as both the gas and governance token. It will also be used to drive incentive mechanics within the credential ecosystem as part of our tokenomics.
</Accordion>

<Accordion title="How do I get \$MOCA?">
  On Moca Chain mainnet, you can bridge your existing \$MOCA from Ethereum or Base using Stargate, or buy \$MOCA on supported exchanges. For Testnet, use the Testnet faucet. See <a href="/technicals/mocachain/how-to-get-moca">How to get \$MOCA</a> for details.
</Accordion>

## Support

<Accordion title="I need some help with a technical problem.">
  Start with [Troubleshooting](/help/error-codes) for HTTP status codes, SDK errors, and credential issues. For service health, see the [Status page](/help/status). For community support, visit our <a href="https://discord.gg/mocaversenft">Discord</a> dev-chat channel.
</Accordion>


# Identity & Credential
Source: https://docs.air3.com/help/identity-credential

Troubleshoot AIR Identity and AIR Credential flows — issuance, verification, and schema problems, and resolve program configuration errors.

Troubleshooting for AIR Identity and AIR Credential flows: issuance, verification, and schema configuration. For API status codes and SDK error names, see [Error codes](/help/error-codes).

## Issuance

### On-demand issuance credential not stored (no storagePath)

`POST /dstorage/vcs` stores an encrypted credential and returns a `storagePath`. Issuer-hosted `POST /issue-vc` performs this upload internally and returns an empty response body. Issuance typically completes in \~1–4 seconds.

* If `POST /dstorage/vcs` did not return a `storagePath`, retry with exponential backoff (start at 1 second, double each attempt, cap at 30 seconds).
* Check DStorage endpoint configuration and that your Partner JWT is valid.
* Do not rebuild and re-issue on every transient failure — retry the store step with the same encrypted payload fields.

### Issuance returns 400

* Verify `holderDid`, `schemaId`, `expiresAt`, `data`, `iv`, `authTag`, `encryptedKey`, and `externalId` are all present and correctly typed.
* Ensure the credential data matches the schema definition exactly. Extra fields or wrong types will be rejected.
* Check the response body for a specific error message.

### Issuance returns 409

This usually means:

* **User consent rejected:** The user has previously declined credentials from your partner account. Contact the user or wait for them to re-consent.
* **Duplicate credential:** A credential already exists for this user + schema combination. Dedupe by recipient email + program ID, and revoke the existing credential before reissuing if the data changed.

### Credential not visible to user after issuance

* For on-demand issuance, confirm `POST /dstorage/vcs` returned a `storagePath`. When your backend calls `POST /issue-vc`, confirm it succeeded and inspect the issuer's issuance record for its DStorage result.
* For on-demand issuance, newly created users see issued credentials when they first log in. They may be prompted to accept or reject credentials.
* Verify the `initialize-user` request body contains the intended recipient's email; on-demand issuance Partner JWTs do not carry the recipient email.

## Verification

### Verification returns "no matching credential"

* The user may not have a credential matching the verification program's schema. Check that:
  * The credential was issued using the correct issuance program.
  * The credential has not been revoked.
  * The verification program's schema matches the issuance program's schema.

### Verification fails with "proof invalid"

* The issuer signature doesn't match the key published in the issuer's `did:web` DID document. Check that the issuer hasn't removed the key it signed with.
* The key-binding JWT doesn't match your `nonce`. Create a fresh nonce for each verification and use it only once.
* The credential has expired or been revoked.
* If the credential was just issued, make sure the store step returned a `storagePath` before you verify.

For the full set of backend checks, see [Verify SD-JWT on your backend](/products/identity/verify-sd-jwt).

### User declines verification

* The SDK prompts users for consent before presenting a credential. If the user declines, the verification result will indicate failure.
* Your app should handle this gracefully — show a message explaining why the credential is needed and offer to retry.

## Schema issues

### "Schema not found" error

* Verify the schema exists in the Developer Dashboard (Issuer > Schemas).
* Ensure the `credentialId` (Issuance Program ID) references a published program, not a draft.

### Schema mismatch between issuance and verification

* If a verification program rejects credentials that were successfully issued, the issuance and verification programs may reference different schema versions.
* Check both programs in the Developer Dashboard and ensure they point to the same schema.


# Flutter SDK
Source: https://docs.air3.com/help/sdk-flutter

Resolve common AIR Kit Flutter integration issues — installation errors, platform configuration, login failures, WebView problems, and SDK initialization.

## Installation and OnePub

| Issue | What to try |
| - | - |
| `onepub` command not found | Add `$HOME/.pub-cache/bin` to PATH |
| Package resolve failures | `onepub login`, verify hosted URL and version in [Flutter installation](/get-started/sdks/flutter/installation) |

## Android

| Issue | What to try |
| - | - |
| Passkey / asset links | [Android setup](/get-started/sdks/flutter/android-setup): `strings.xml`, manifest `meta-data`, signing cert allowlisting |
| `minSdk` / manifest merge errors | Set `minSdk` 26+, `compileSdk` 34+ |

## iOS

| Issue | What to try |
| - | - |
| Associated Domains | [iOS setup](/get-started/sdks/flutter/ios-setup): capability, exact domain entries, physical device |
| CocoaPods | `cd ios && rm -rf Pods Podfile.lock && pod install` |

## Runtime

| Issue | What to try |
| - | - |
| Login UI does not appear | `navigatorKey` passed to `MaterialApp` and `initialize()` |
| `Service is not initialized` | Await `initialize()` before other calls |
| WebView blank | Platform network config, ATS (iOS), Associated Domains / asset links |

## Credentials on Flutter

Credential **issuance** and **verification** are available on Flutter. Use the [Issue credentials](/get-started/quickstarts/issue-credentials) and [Verify credentials](/get-started/quickstarts/verify-credentials) quickstarts, plus [Issuing credentials](/products/identity/issuing-credentials) and [Verify](/products/identity/verify).

If calls fail or payloads are rejected, see [Identity & Credential](/help/identity-credential). For Google OAuth client IDs and dashboard-side setup, see [Google Sign-In — Dashboard](/get-started/sdks/flutter/google-signin#dashboard).

## More help

* [Error codes](/help/error-codes) — HTTP status codes and SDK error names
* [Common issues](/help/common-issues) — JWT / JWKS, CORS, rate limiting
* [Web SDK](/help/sdk-web) — initialization, login, wagmi
* Support via your Moca / partner channel


# Web SDK
Source: https://docs.air3.com/help/sdk-web

Troubleshoot the AIR Kit Web SDK — initialization failures, login problems, session rehydration, and wagmi connector issues.

Troubleshooting for the AIR Kit **Web SDK** (`@mocanetwork/airkit`). For Flutter, see [Flutter SDK](/help/sdk-flutter). For HTTP status codes and SDK error names, see [Error codes](/help/error-codes).

## Initialization

### SDK does not initialize

* Verify you are calling `init()` with a valid `partnerId`:

```ts theme={null}
const airService = new AirService();
await airService.init({ partnerId: "your-partner-id" });
```

* Check the browser console for errors. A network failure to load the AIR Kit iframe will surface here.
* Ensure you are using a supported browser (Chrome, Firefox, Safari, Edge — latest versions).

### "Partner ID not found" error

* Confirm the Partner ID in the [Developer Dashboard](https://developers.sandbox.air3.com/dashboard) matches what you pass to `init()`.
* Check that you are using the correct environment. Sandbox and Production have different Partner IDs.

## Login

### Login dialog does not appear

* The SDK opens an iframe for login. If it doesn't appear:
  * Check that `Content-Security-Policy` headers allow `frame-src` from `*.air3.com`.
  * Check for CSS `z-index` conflicts — the iframe may be behind other elements.
  * Disable browser extensions that block iframes or popups.

### Login succeeds but user data is missing

* `login()` returns an `AirLoginResult` containing `token` and account information. If fields are missing, verify your Partner JWT includes the expected claims.
* If using Custom Auth (BYO), ensure `email` is included in the Partner JWT.

### "Session expired" after page refresh

* By default, AIR Kit auto-restores sessions for 30 days. If sessions expire immediately:
  * Check that `skipRehydration` is not set to `true` in your `init()` options.
  * Verify cookies and local storage are not being cleared by your app or browser settings.

### Session rehydration fails silently

* Call `isLoggedIn` after `init()` to check if rehydration succeeded.
* If the session cannot be restored (expired, corrupted), `isLoggedIn` returns `false`. Call `login()` to start a new session.

## wagmi connector

### Connector not appearing in wagmi

* Ensure `@mocanetwork/airkit-connector` is installed and the connector is added to your wagmi config:

```ts theme={null}
import { airConnector } from "@mocanetwork/airkit-connector";

const config = createConfig({
  connectors: [airConnector({ partnerId: "your-partner-id" })],
  // ...
});
```

### `isMocaNetwork` is undefined

* Cast the connector to the correct type:

```ts theme={null}
import type { AirConnectorProperties } from "@mocanetwork/airkit-connector";
const isAir = (connector as Connector & AirConnectorProperties)?.isMocaNetwork;
```

## What check next

* Check the [AIR Kit release notes](/api-reference/release-notes) for known issues in your SDK version.
* Join our [Discord](https://discord.gg/mocaversenft) for community support.


# Status Page
Source: https://docs.air3.com/help/status

Check Moca Chain mainnet and testnet service status, incident history, and maintenance updates.

## Moca Chain status

Visit [mocachain.statuspage.io](https://mocachain.statuspage.io) to check the operational status of Moca Chain services and view historical uptime data.

The status page covers:

* **Moca Network Mainnet** — mainnet chain service status.
* **Moca Network Testnet** — testnet chain service status.


# AIR Kit Developer Docs
Source: https://docs.air3.com/index

One integration for identity, agents, money and loyalty. Identity & payment infrastructure for businesses and AI agents.

<div>
  <div>
    <div>
      <section>
        <div>
          <h1><span>One integration</span><span>for identity, agents, money and loyalty</span></h1>

          <p>
            Identity & payment infrastructure for businesses and AI agents
          </p>

          <div>
            <a href="/get-started/quickstarts/login">Quickstart</a>
            <a href="/get-started/build-with-your-agent">Connect your agent</a>
          </div>
        </div>

        <div>
          <section aria-label="SDK quick start">
            <div>
              <div>
                <div aria-label="SDK language">
                  <div />

                  <button type="button">JavaScript</button>
                  <button type="button">Flutter</button>
                </div>
              </div>
            </div>

            <div>
              <div />

              <div />
            </div>
          </section>
        </div>
      </section>

      <section>
        <div>
          <h2>Get started</h2>
        </div>

        <div>
          <a href="/solutions/index">
            <span>
              <svg>
                <path />

                <path />

                <path />
              </svg>
            </span>

            <h3>I am a business partner</h3>
            <p>Explore AIR Kit by vertical: loyalty, fintech, gaming, telco, and more.</p>
          </a>

          <a href="/get-started/dashboard/account-setup">
            <span>
              <svg>
                <path />

                <path />

                <path />
              </svg>
            </span>

            <h3>I am a developer</h3>
            <p>Install the SDK, authenticate users, and issue your first credential.</p>
          </a>

          <a href="/technicals/mocachain">
            <span>
              <svg>
                <path />

                <path />
              </svg>
            </span>

            <h3>I am building on Moca Chain</h3>
            <p>Connect to the L1, deploy contracts, and explore EVM-compatible tooling.</p>
          </a>

          <a href="/technicals/architecture">
            <span>
              <svg>
                <path />

                <path />

                <path />
              </svg>
            </span>

            <h3>I want to understand the technicals</h3>
            <p>Learn the architecture, credential security, and data flow behind AIR.</p>
          </a>
        </div>
      </section>

      <section>
        <a href="https://air-bd-v2.netlify.app">
          <div>
            <h2>Explore AIR demos</h2>
            <p>See identity, agent, money and loyalty examples in action.</p>
          </div>

          <div>
            <span>View demo</span>
          </div>
        </a>

        <div>
          <h2>Start with your use case</h2>
        </div>

        <div>
          <a href="/solutions/kyc">
            <span>
              <svg>
                <path />

                <path />

                <path />

                <path />
              </svg>
            </span>

            <h3>On-chain IDV / KYC</h3>
            <p>Veriff powered by zkMe issues a reusable AIR Credential to the user's AIR Account: verify once, reuse across every partner without pairwise DPAs.</p>
          </a>

          <a href="/products/loyalty/what-is-air-loyalty">
            <span>
              <svg>
                <path />

                <path />

                <path />

                <path />

                <path />
              </svg>
            </span>

            <h3>Loyalty programs</h3>
            <p>Trigger verifiable loyalty credentials from your backend. Let users carry tier status across brands.</p>
          </a>

          <a href="/solutions/gaming">
            <span>
              <svg>
                <path />

                <path />

                <path />
              </svg>
            </span>

            <h3>Gaming</h3>
            <p>Issue achievement credentials and portable player identities. Cross-game SSO with a single AIR Account.</p>
          </a>

          <a href="/solutions/ticketing">
            <span>
              <svg>
                <path />

                <path />

                <path />

                <path />
              </svg>
            </span>

            <h3>Live events & ticketing</h3>
            <p>Issue attendance credentials at check-in. Gate VIP presales and loyalty tiers to verified fans.</p>
          </a>

          <a href="/api-reference/introduction">
            <span>
              <svg>
                <path />

                <path />

                <path />

                <path />

                <path />

                <path />

                <path />

                <path />
              </svg>
            </span>

            <h3>API Reference</h3>
            <p>Server-to-server REST API for credential issuance and partner operations.</p>
          </a>

          <a href="/technicals/architecture">
            <span>
              <svg>
                <path />

                <path />

                <path />

                <path />

                <path />
              </svg>
            </span>

            <h3>Architecture overview</h3>
            <p>Data flow, service independence, and technical reference for decision-makers.</p>
          </a>
        </div>
      </section>

      <section>
        <div>
          <h2>One tech stack, four modules</h2>
        </div>

        <div>
          <div>
            <div>
              <img alt="" />
            </div>

            <div>
              <p><strong>AIR Identity</strong></p>
              <p>Turn user data you already hold into verifiable credentials without exposing it</p>
            </div>
          </div>

          <div>
            <div>
              <img alt="Incoming store orders with AI agents listed as customers, surrounded by products they purchase." />
            </div>

            <div>
              <p><strong>AIR Agent</strong></p>
              <p>Know the user behind every AI agent. Turn unknown agents into loyal customers with verified identity.</p>
            </div>
          </div>

          <div>
            <div>
              <img alt="" />
            </div>

            <div>
              <p><strong>AIR Money</strong></p>
              <p>Embedded accounts, payments and cards for your users</p>
            </div>
          </div>

          <div>
            <div>
              <img alt="" />
            </div>

            <div>
              <p><strong>AIR Loyalty</strong></p>
              <p>Bring customers back, spending more with rewards they actually use.</p>
            </div>
          </div>
        </div>
      </section>

      <footer aria-label="External links">
        <a href="https://developers.sandbox.air3.com/dashboard">Dashboard ↗</a>
        <a href="/help/status">Status ↗</a>
        <a href="https://github.com/MocaNetwork">GitHub ↗</a>
        <a href="https://discord.gg/mocaversenft">Discord ↗</a>
        <a href="https://twitter.com/Moca_Network">X / Twitter ↗</a>
      </footer>
    </div>
  </div>
</div>


# Agent Gating
Source: https://docs.air3.com/products/agents/agent-gating

Use the agent-user relationship and verified eligibility to control access and reduce anonymous abuse.

Agent Gating lets an application make access decisions about agent requests using identity evidence. Instead of treating every bot as an anonymous visitor, the service can check which agent is requesting access, whom it represents, and whether the user's credentials satisfy its rules.

This can help a publisher, marketplace, or application distinguish authorized, eligible requests from requests that lack the required evidence. Identity supports the decision; your application still defines and enforces its abuse controls.

## What the service checks

| Check | Why it matters |
| - | - |
| **Agent identity** | Authenticate the agent making the request under the agreed integration. |
| **User relationship and consent** | Establish the AIR Account it represents and the identity access the user approved. |
| **Accepted user claims** | Verify the membership, account standing, or other eligibility your service requires, using issuers you trust. |
| **Access policy** | Decide which actions that evidence permits, and apply quotas, rate limits, and risk checks. |

A valid agent key establishes authenticated access; it does not prove that every request is benign. A membership credential proves membership, not that the agent will behave well. Choose claims relevant to the access decision and combine them with observed behavior.

## Example: protect member-only access

A publisher allows agents to retrieve content for eligible members. The user approves identity access for their assistant, which verifies membership under the publisher's accepted program. The publisher checks the supplied evidence and grants only the access its policy allows.

Requests without valid evidence can be declined, directed to a user approval flow, or given limited access. A missing credential and a verification-service failure are different outcomes; the service should handle them separately.

The same pattern can support account-based limits on reward claims, reservations, or other scarce actions. Use the agreed account or identity mapping to enforce those limits. A customer binding multiple agent keys does not entitle them to a new quota for each key.

## Reduce abuse without collecting a full profile

Ask for the facts needed for the gate, rather than a broad collection of personal data. Where supported by the credential and program, request a specific eligibility claim with selective disclosure.

Use the verified relationship to make requests accountable within your service: apply per-user and per-agent limits, monitor repeated failures, and withdraw access when your rules are violated. Revoking an agent binding and enforcing a service ban are separate controls, and the service owns its ban policy.

## Plan the integration

Define the agent operator, the consenting user, accepted issuers, and the recipient's verification method in [Plan your integration](/products/agents/integration-options). Then follow [Using Agentic Identity](/products/agents/partner-agent-api).

For a benefit applied after a successful check, see [Agentic Commerce](/products/agents/offers-for-agents).


# Connect with other modules
Source: https://docs.air3.com/products/agents/beyond-agents

Explore the credentials, loyalty status, and wallet flows relevant to an AIR Agent integration.

An agent's binding identifies the user it represents. Credentials supply evidence for eligibility and benefits; payment and transaction permissions remain separate decisions.

<CardGroup>
  <Card title="AIR Identity" icon="id-card" href="/products/identity/verify">
    Configure the claims and issuers your verification program accepts.
  </Card>

  <Card title="AIR Loyalty" icon="gift" href="/products/loyalty/use-cases">
    Explore membership pricing and benefits based on accepted loyalty credentials.
  </Card>

  <Card title="AIR Money" icon="wallet" href="/products/money/how-it-works">
    Explore the wallet and smart account flows for transactions in your app.
  </Card>
</CardGroup>


# Delegation and consent
Source: https://docs.air3.com/products/agents/delegation-and-consent

Control what an agent may present and do on a user's behalf, get the user's approval before binding, and withdraw access when they disconnect.

<Note>
  **Current scope:** The [Agent APIs](/products/agents/partner-agent-api) support agent identity binding, short-lived sessions, and credential lookup and verification. Wallet delegation for Web3 use cases is planned. Fine-grained delegation credentials and user-bound proof handoff are not yet released. Existing merchant checkout tokens provide an identity handoff, rather than wallet signing authority. Contact the AIR team to confirm environment access.
</Note>

An agent acts for a user only within the authority the user gives it. Today, that authority is the set of scopes on the agent's key. Delegation credentials, which are not yet released, would add finer-grained, per-task grants.

## What the Agent APIs enforce today

| Control | Behavior |
| - | - |
| Bound scopes | An agent key is bound with scopes such as `credentials.read`, `credentials.verify`, and `commerce.checkout`. It cannot act outside them. |
| Session scopes | Each agent session can request a subset of the bound scopes. |
| Session lifetime | Agent JWTs expire after 15 minutes and have no refresh token. |
| Rotation | Rotating a key issues a new API key and invalidates agent JWTs already issued for it. |
| Revocation | Revoking a key stops new sessions for that agent. |
| Checkout audience | A checkout token is valid only for its merchant. AIR and Credential APIs reject it. |

These controls limit what an agent can request from AIR. They don't express a per-merchant, per-claim, or per-action grant, and they don't replace the receiving application's own checks.

## Ask for consent before binding

The bind request has no user-facing approval step. Your application owns consent, so before you bind an agent:

1. Show the user which agent they are connecting, using the nickname you will bind it with.

2. Explain each scope in plain language:

   | Scope | Tell the user the agent can |
   | - | - |
   | `credentials.read` | See which credentials they hold, such as issuer and credential type. |
   | `credentials.verify` | Check their credentials against a verification program and share the result, including any claims the program discloses. |
   | `commerce.checkout` | Start a checkout with a supported merchant, which receives their AIR Account address. |

3. Bind only the scopes the user approved, and keep a record of the approval.

Ask again before adding scopes. A key's scopes are fixed at bind time, so bind a new key for the wider set and revoke the old one.

## Let users see and disconnect agents

Give users a place in your product to review and remove connected agents:

* List the agents your partner bound for the user with [List bound agents](/api-reference/agents/list-agent-keys).
* When the user disconnects an agent, call [Revoke an agent key](/api-reference/agents/revoke-agent-key).
* Revocation is documented as stopping new sessions. To also end sessions already issued, [rotate the key](/api-reference/agents/rotate-agent-key) before you revoke it.

AIR Kit also has agent key calls that run in the user's own session (`getAgentKeys`, `registerAgentKey`, `removeAgentKey`). See the [Web SDK reference](/api-reference/sdk-reference).

Removing access does not undo completed purchases or recall claims already disclosed.

## Disclosure and purchase authority

Permission to show a loyalty tier lets an agent get a member quote. Placing an order and paying need separate permission. With the Agent APIs, that means binding `commerce.checkout` only when the user wants the agent to start purchases.

For each integration, define the claims an agent may present, the applications that may receive them, and the actions it may take. When the task changes, get the additional approval. For example, an agent allowed to compare hotel prices should ask again before it books a non-refundable room.

## Proof, disclosure, and context

| Information type | Example | What it means for the interaction |
| - | - | - |
| Proof of eligibility | The user is over 18 ([see the demo](https://air-bd-v2.netlify.app/demo/agent-booking)) | The application can check a condition without the source document. The date of birth stays hidden. |
| Approved disclosure | The user's loyalty tier | The recipient receives the specific claim approved for sharing. |
| User context | A seat preference or product category | The agent can personalize its work, but a preference is not an issuer-verified fact. |

Request only what the task needs. Proving one attribute does not grant access to the user's whole profile.

## Delegation credentials

**Not yet released.** A delegation credential would record a user's authorization for a specific agent and task, linking the agent to the user's AIR Account. The receiving application would check it alongside the user's claims.

A grant could cover:

| Part of the grant | Example | Purpose |
| - | - | - |
| Granting user | The customer's AIR Account | Who authorizes the agent. |
| Delegate | The shopping agent | Who receives the authority. |
| Permitted claims | Membership and age eligibility | What the agent may present. |
| Receiving application | One merchant | Where the grant applies. |
| Duration | 24 hours | How long the authority lasts. |
| Permitted action | Request a member price | What the agent may do. |

These are illustrative terms, not API fields. Expiry would end a grant at a set time, and revocation would withdraw it earlier. How quickly revocation takes effect, and what happens to requests already in progress, will be defined with the release.

## Spending limits

A spending limit only works if the payment or wallet integration enforces it. The Agent APIs don't set spending caps. Decide whether a cap applies per purchase, per session, or over a period, and how concurrent requests count against it.

Enforce the cap wherever money moves. A limit in one payment path doesn't protect a different path the agent can reach.

## Match authority to the task

* **One task:** get the evidence for a single interaction, and let the authority end with it.
* **One session:** keep the approved scope across a multi-step shopping or booking flow.
* **An ongoing relationship:** define renewal, expiry, withdrawal, and approval for repeated actions.

An agent remembering a conversation or preference does not extend its authority. Scheduled purchases and standing spending mandates are not supported.

Portable user context, such as preferences carried in credentials, needs its own schema and access model for each integration. AIR does not provide a general-purpose memory-sharing service.


# Identity and agent binding
Source: https://docs.air3.com/products/agents/how-it-works

Follow a user from approving an agent to the agent presenting verified claims and the receiving application making a decision.

<Note>
  **Current scope:** The [Agent APIs](/products/agents/partner-agent-api) support agent identity binding, short-lived sessions, and credential lookup and verification. Wallet delegation for Web3 use cases is planned. Fine-grained delegation credentials and user-bound proof handoff are not yet released. Existing merchant checkout tokens provide an identity handoff, rather than wallet signing authority. Contact the AIR team to confirm environment access.
</Note>

An application deciding on an agent's request needs three things:

* Who the agent is?
* What the user has allowed it to do?
* Verified claims behind the request.

## The building blocks

| Element | What it establishes |
| - | - |
| AIR Account | The user's identity and the credentials they hold. |
| Agent identity | The agent performing the action. On its own, it does not show which user the agent represents. |
| Agent binding | The link between the user's AIR Account and the agent. With the Agent APIs, this is an agent key bound to the user with a set of scopes. |
| Delegation credential | **Not yet released.** A credential recording the authority the user grants the agent, with finer-grained scope and conditions. |
| User credential | An issuer-signed claim about the user, such as membership or eligibility. |
| Verification | Whether the user's credentials satisfy the receiving application's verification program. |

The binding shows whom the agent represents. Its scopes limit what the agent can do through AIR. A credential such as a membership supplies the evidence for a benefit decision.

## The interaction

<Steps>
  <Step title="The user approves the agent">
    The user approves identity access for a specific agent, normally through the AIR app. Its link is coming soon. For a partner-managed in-app journey, your application shows which agent is being connected and which scopes it requests. The bind request has no approval screen of its own. See [Plan your integration](/products/agents/integration-options#choose-the-delegation-journey).
  </Step>

  <Step title="Bind the agent">
    The approved connection links the agent identity to the user's AIR Account. In the partner-managed route, your backend binds it while the user has an AIR Kit session. Request only approved scopes, such as `credentials.read` and `credentials.verify`. See [Using Agentic Identity](/products/agents/partner-agent-api).
  </Step>

  <Step title="Request the required evidence">
    The receiving application decides which claims and issuers it accepts, and sets them in a verification program. For a member price, it might check a loyalty tier. For an eligibility check, it might check that a condition is met.
  </Step>

  <Step title="Verify">
    Your backend creates a 15-minute agent session and runs the program against the user's credentials. The result is `Compliant`, `Non-Compliant`, or `NotFound`, with a verifiable presentation when compliant.
  </Step>

  <Step title="Apply the result">
    The application returns the benefit or service the user qualifies for, asks for more approval, or declines the request. A purchase then follows its own checkout and payment steps. For a supported merchant, the agent can mint a checkout token scoped to that merchant.
  </Step>
</Steps>

**Not yet released:** with delegation credentials, the user would also grant per-task authority, such as a specific merchant, claim, and duration, and verification would check that authority alongside the user's claims.

## Verification through the Agent APIs

Agents reach credential verification through the Agent APIs, REST endpoints your backend calls. With an agent session, your backend lists the user's credentials and runs a verification program in a single call. See the [Using Agentic Identity](/products/agents/partner-agent-api).

If the user doesn't hold the required credential, the result is `NotFound`. Verification never issues the missing credential itself.

Issuing credentials is a separate integration owned by the issuer. See [Issuing credentials](/products/identity/issuing-credentials).

## What a verification result proves

Agent verification runs offchain, and `status` tells your backend the outcome. A `Compliant` result includes an SD-JWT presentation: the issuer-signed JWT plus the disclosures the program requested. If you send a `nonce` and the credential was issued with `cnf.jwk`, it also includes a key-binding JWT tied to your challenge.

A third party, such as a merchant, can check that presentation itself: the issuer signature, the disclosures, and the key-binding JWT when present. See [Verify SD-JWT on your backend](/products/identity/verify-sd-jwt). The `status` field is not signed, so a recipient that receives only the status has to trust your backend's report.

The checkout token identifies the user and their AIR Account address. To share a verification result with a merchant, agree the format and how the merchant checks it.

<Note>
  Programs that use [Iden3 credentials](/products/identity/iden3-credentials) (Advanced) return a different presentation. See the [endpoint reference](/api-reference/agents/verify-credential-by-agent).
</Note>

## What the receiving application checks

A verified claim does not authorize every action. A verified loyalty tier can support a price decision, but placing an order or spending money needs separate authority.

With the Agent APIs today, the application relies on:

* The result of the verification program it accepts.
* The agent key's scopes, which limit what the agent can request from AIR.
* For checkout, a token whose audience is the merchant, which the merchant must verify.

**Not yet released:** with delegation credentials, the application would also check that the requester is the delegated agent, that the grant covers this application and action, that it hasn't expired or been revoked, and that the evidence is bound to this interaction.

## What information is shared

The verification program sets which claims are requested and how. A program can return an eligibility result or approved claims; the result is not always a single yes-or-no value.

AIR Credentials are encrypted before storage, and issuers keep their source data. Anyone who receives disclosed claims must handle them appropriately. See [How AIR Credentials work](/products/identity/credentials-flow).


# Connect your agent
Source: https://docs.air3.com/products/agents/integrating-using-ai

Add the AIR docs MCP server to your agent, then start building.

## Connect via MCP

Choose your tool below and add the AIR documentation server:

```text theme={null}
https://docs.air3.com/mcp
```

<Tabs>
  <Tab title="Claude">
    <Steps>
      <Step title="Add the Moca Network MCP server to Claude">
        1. Navigate to the [Connectors](https://claude.ai/settings/connectors) page in the Claude settings.
        2. Select **Add custom connector**.
        3. Add the Moca Network MCP server:
           * Name: `MocaNetwork`
           * URL: `https://docs.air3.com/mcp`
        4. Select **Add**.
      </Step>

      <Step title="Access the MCP server in your chat">
        1. When using Claude, select the attachments button (the plus icon).
        2. Select the MocaNetwork MCP server.
        3. Ask Claude a question about Moca Network or AIR Kit.
      </Step>
    </Steps>

    See the [Model Context Protocol documentation](https://modelcontextprotocol.io/docs/tutorials/use-remote-mcp-server#connecting-to-a-remote-mcp-server) for more details.
  </Tab>

  <Tab title="Claude Code">
    <Steps>
      <Step title="Add the MCP server to Claude Code">
        Run the following command:

        ```bash theme={null}
        claude mcp add --transport http MocaNetwork https://docs.air3.com/mcp
        ```
      </Step>

      <Step title="Test the connection">
        Verify the connection by running:

        ```bash theme={null}
        claude mcp list
        ```
      </Step>
    </Steps>

    See the [Claude Code documentation](https://docs.anthropic.com/en/docs/claude-code/mcp#installing-mcp-servers) for more details.
  </Tab>

  <Tab title="Cursor">
    <Steps>
      <Step title="Open MCP settings">
        1. Use <kbd>Command</kbd> + <kbd>Shift</kbd> + <kbd>P</kbd> (<kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>P</kbd> on Windows) to open the command palette.
        2. Search for "Open MCP settings".
        3. Select **Add custom MCP**. This opens the `mcp.json` file.
      </Step>

      <Step title="Configure the Moca Network MCP server">
        In `mcp.json`, add:

        ```json theme={null}
        {
          "mcpServers": {
            "MocaNetwork": {
              "url": "https://docs.air3.com/mcp"
            }
          }
        }
        ```
      </Step>

      <Step title="Test the connection">
        In Cursor's chat, ask "What tools do you have available?" Cursor should show the MocaNetwork MCP server as an available tool.
      </Step>
    </Steps>

    See the [Cursor documentation](https://docs.cursor.com/en/context/mcp#installing-mcp-servers) for more details.
  </Tab>

  <Tab title="VS Code">
    <Steps>
      <Step title="Create MCP configuration">
        Create a `.vscode/mcp.json` file in your project root.
      </Step>

      <Step title="Configure the Moca Network MCP server">
        In `.vscode/mcp.json`, add:

        ```json theme={null}
        {
          "servers": {
            "MocaNetwork": {
              "type": "http",
              "url": "https://docs.air3.com/mcp"
            }
          }
        }
        ```
      </Step>
    </Steps>

    See the [VS Code documentation](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) for more details.
  </Tab>
</Tabs>

For another MCP-compatible tool, add the URL as a remote HTTP MCP server in its connection settings.

## Try your first prompt

Once connected, ask your agent to look up the docs and help with a specific task:

```text theme={null}
Use the AIR docs MCP server to help me add AIR Kit login to my app.
Check my framework and existing authentication, then explain the setup
and changes before implementing them.
```

You can also ask about credential issuance and verification, wallet transactions, or integration errors. Include your framework and what you have already built.

## Choose your setup

| Option | What it provides | When to use it |
| - | - | - |
| **Docs MCP** | Searchable AIR documentation, SDK guides, and API references. | Start here for current reference material. |
| **AIR skill** | Integration workflows and checks for setup, authentication, and common errors. | Add alongside MCP for guidance while building. |
| **Static docs** | Documentation files you attach or index in your tool. | Use when your tool cannot connect through MCP; refresh the files as docs change. |

Your agent uses these resources to plan, write, and review integration code. Live AIR operations run through your application's configured account, authentication, and programs.

## Add the AIR skill (optional)

For tools that support [Agent Skills](https://agentskills.io/home), run:

```bash theme={null}
npx skills add https://docs.air3.com
```

Select your agent in the CLI to install the skill.

<Accordion title="Before issuing or verifying credentials">
  Ask your agent to confirm these prerequisites before generating application code:

  * Your partner's public JWKS endpoint is reachable over HTTPS.
  * The exact JWKS URL is registered in the Developer Dashboard.
  * Your JWT signing key stays server-side, and its `kid` matches a published JWKS key.

  Follow [JWKS endpoint setup](/get-started/authentication/jwks-endpoint), then use the [issuance](/products/identity/issuing-credentials) or [verification](/products/identity/verify) guide for your flow.
</Accordion>

<Accordion title="Use static documentation files">
  ## Static docs files

  If your AI tool does not support MCP yet, you can use one of Moca Network's static documentation files instead.

  <Warning>
    Static files are snapshots and may not include the latest updates. Use MCP when possible for always-current docs.
  </Warning>

  ## Which file should I use?

  * **`llms.txt`** — A curated overview of Moca Network. Use it to route an agent to the right docs, understand product structure, and choose the right integration path.
  * **`llms-full.txt`** — A full static snapshot of the documentation. Use it when your tool needs more exhaustive reference material in one file.

  ## Setup with Cursor

  <Steps>
    <Step title="Open docs settings">
      Go to **Settings** → **Features** → **Docs**.
    </Step>

    <Step title="Add the overview file">
      Click **Add new doc** and paste: `https://docs.air3.com/llms.txt`
    </Step>

    <Step title="Optionally add the full snapshot">
      If your agent needs deeper static reference coverage, add: `https://docs.air3.com/llms-full.txt`
    </Step>

    <Step title="Reference in chat">
      Use **@docs** → **Moca** in your AI chat to reference the documentation.
    </Step>
  </Steps>

  ## Setup with Claude Desktop

  <Steps>
    <Step title="Download the overview file">
      Download the curated overview from: [https://docs.air3.com/llms.txt](https://docs.air3.com/llms.txt)
    </Step>

    <Step title="Optionally download the full snapshot">
      Download the full documentation snapshot from: [https://docs.air3.com/llms-full.txt](https://docs.air3.com/llms-full.txt)
    </Step>

    <Step title="Add to your project">
      Save one or both files in your project directory or another known location on your system.
    </Step>

    <Step title="Reference in chat">
      Drag and drop the file into your Claude Desktop chat, or use the attachment button to upload it. Claude will then have access to the uploaded Moca Network documentation context for that conversation.
    </Step>
  </Steps>
</Accordion>


# Plan your integration
Source: https://docs.air3.com/products/agents/integration-options

Identify the agent, its operator, the user it represents, and the consent and verification your journey needs.

Before choosing an API flow, define what the agent in your product actually is. Who operates it? Whose identity does it use? Who gives consent, and who needs to verify the evidence? Those answers determine how you delegate identity access and where verification belongs.

## Identify the agent and its owner

| Deployment | What to establish |
| - | - |
| **Personal assistant**, such as a Muse or Grokbot experience | Which user it represents, which service operates it, and where that user approves identity access. |
| **Agent embedded in another application**, such as a chatbot | Whether it acts for the app operator or an individual customer, who controls its backend, and how each customer's access remains separate. |
| **User-operated agent**, such as a self-hosted Hermes or OpenClaw deployment | Who controls the runtime and keys, which AIR Account gives consent, and where access can be reviewed or withdrawn. |

Classify the actual deployment rather than inferring ownership from its name. A personal assistant can run on a provider's servers; an embedded agent still needs each customer's approval before using their identity.

The agent's operator and the user it represents can be different people or organizations. Record both roles and identify the agent key or instance to which access is granted.

## Map consent and verification

Use one concrete journey to answer these questions:

| Decision | Questions to resolve |
| - | - |
| **User and task** | Who is represented, and what are they asking the agent to do? |
| **Consent** | Who approves identity access, which agent receives it, and how can that access be withdrawn? |
| **Receiving service** | Which application, merchant, or other service receives the request? |
| **Evidence** | Does it need membership, age eligibility, a completed identity check, or another defined claim? Which issuers does it trust? |
| **Data source** | Does an accepted credential already exist? Which issuer checks the source records and maintains its validity? |
| **Verification responsibility** | Does the agent's backend run the receiving service's program, or does the service check a presentation itself? How is the result passed and checked? |
| **Decision and failure** | What does successful verification permit? What happens if evidence is missing, expired, or insufficient? |

A user preference or a statement in chat is context, not automatically an issuer-verified fact. If the journey needs a credential the user does not hold, define an [issuance flow](/products/identity/issuing-credentials); verification does not create missing evidence.

## Choose the delegation journey

### User-managed delegation

The standard journey is for the user to approve the chosen agent through the AIR app. Your product should make clear which agent is being connected and why it needs identity access.

**AIR app link: coming soon.**

### Delegation within your application

For a more integrated experience, contact the AIR team about enabling delegation within your own app. Your application collects the user's explicit approval and uses the supported partner binding flow. The bind request itself does not display an approval screen.

Choose this route when your product can identify the user, explain the access clearly, and manage the connected agent on their behalf. See [Delegation and consent](/products/agents/delegation-and-consent#ask-for-consent-before-binding).

The current Agent APIs bind scopes such as `credentials.read` and `credentials.verify`. Your application must also enforce any narrower task rules it promises; those scopes do not encode a per-merchant or per-claim grant.

### Who holds the agent key?

For a partner-operated agent, the backend can hold the API key returned by the binding flow. For an agent that controls its own P-256 key pair, the supported API route can bind its public key and authenticate sessions using signed messages. Choose the key model that fits the operator identified above; neither model removes the user's consent requirement. See [Use a public key instead of an API key](/products/agents/partner-agent-api#use-a-public-key-instead-of-an-api-key).

## Choose the verification method

* **Agent API verification:** the agent's backend creates an authenticated session and runs the agreed verification program for the user's credentials. Follow [Using Agentic Identity](/products/agents/partner-agent-api).
* **Presentation verification by the receiving service:** agree the format and trust model, then have the recipient check issuer signatures and the required claims. For SD-JWT, use the existing [Verify with SD-JWT](/products/identity/verify-sd-jwt) guide.

Decide whether the recipient will trust an agreed backend result or independently verify the evidence. A `Compliant` status alone is not a signed proof for an unrelated third party. See [What a verification result proves](/products/agents/how-it-works#what-a-verification-result-proves).

Agree how the handoff authenticates the agent-user relationship and records consent. Checking a credential's issuer signature establishes that claim; the recipient still needs the agreed evidence of who is presenting it and under what authority.

## Example: a member discount

A user asks a personal assistant to find a product. The merchant wants to check a membership tier from an issuer it accepts. The user approves identity access for that assistant, its backend runs the agreed program, and the merchant checks the supplied evidence before returning a member price.

The identity flow establishes eligibility for the discount. Ordering and payment follow their own approvals.

## Not yet available

Wallet delegation for Web3 use cases is planned. The current identity binding does not grant `wallet.sign`, a spending mandate, or automatic access to the user's assets. Fine-grained delegation credentials and user-bound proof handoff are also not yet released.

Once the roles, evidence, and consent journey are clear, follow [Using Agentic Identity](/products/agents/partner-agent-api). [Talk to the AIR team](https://air3.com/partner-with-us) if you need help scoping the flow.


# Agentic Commerce
Source: https://docs.air3.com/products/agents/offers-for-agents

Let agents present user-approved identity to qualify for relevant prices, discounts, and membership benefits.

Agentic Commerce lets an agent bring the user's approved identity into a shopping or booking experience. A participating merchant can recognize the membership or eligibility behind a request and return the benefits that customer qualifies for.

The starting point is a clear offer: a member price, a tier benefit, or a discount with defined eligibility. AIR provides the identity and credential-verification flow. The merchant owns the offer rules, and purchase and payment authority are handled separately.

## Member discounts

A customer asks an agent to find a product. They already hold a loyalty credential from an issuer the merchant accepts.

<Steps>
  <Step title="The user approves identity access">
    The customer connects the chosen agent and approves access for the task. The integration identifies both the agent and the user it represents.
  </Step>

  <Step title="The agent verifies eligibility">
    The agent's backend runs the agreed program for membership or tier evidence. It passes the result and relevant presentation in the format the merchant accepts.
  </Step>

  <Step title="The merchant applies the benefit">
    The merchant checks the evidence and returns the eligible price or discount with its terms. The agent can compare that offer against the user's requirements.
  </Step>

  <Step title="The user proceeds under the purchase rules">
    Ordering and payment use their own approvals and supported checkout flow. Permission to verify membership alone does not authorize spending.
  </Step>
</Steps>

For example, an accepted Gold-tier credential could qualify a customer for a lower price. The merchant needs the eligibility evidence for that benefit, rather than the customer's full membership history. Configure disclosure for the actual claims required.

## Travel and other entitlements

The same pattern can let a booking agent request a member rate or an upgrade using accepted loyalty status. Preferences such as seat choice help the agent choose options, while credentials establish eligibility for the benefit.

See the [agent booking demo](https://air-bd-v2.netlify.app/demo/agent-booking) for an illustrative journey. A demonstration of checkout does not give an identity binding wallet signing authority; wallet delegation for Web3 use cases is planned separately.

## Relevant offers during discovery

A merchant could make an offer available while an agent is comparing products. Verified, user-approved claims can establish whether the customer qualifies, and the agent can evaluate the offer alongside price, quality, and the user's request.

For a first-purchase discount, agree how first-time eligibility is established and how one-time use is tracked. Do not assume that every required claim already exists as a credential.

Broader offer discovery and merchant-funded campaigns are a product direction. A general advertising marketplace, discovery API, and automated revenue-sharing model are not established by the identity integration described here. [Talk to the AIR team](https://air3.com/partner-with-us) to explore a specific journey.

## Design the identity handoff

Agree who gives consent, which issuers and claims the merchant accepts, and whether it trusts an agreed backend result or checks the presentation itself. Use [Plan your integration](/products/agents/integration-options) and [What a verification result proves](/products/agents/how-it-works#what-a-verification-result-proves), then follow [Using Agentic Identity](/products/agents/partner-agent-api).


# Using Agentic Identity
Source: https://docs.air3.com/products/agents/partner-agent-api

Delegate identity access to a specific agent, then verify the user's credentials for an approved task.

AIR delegates identity access to a specific agent identity bound to the user's AIR Account. That lets the agent authenticate its own requests and verify the user's credentials for an approved task, using the scopes granted to that identity.

The agent here is the runtime or backend holding the bound key, rather than the model name or a message in chat. Identify its operator and the user it represents first; see [Plan your integration](/products/agents/integration-options).

The flow has two stages: **delegation**, then **verification by the agent**. The receiving application decides which evidence it accepts and checks the result before granting access or a benefit. For endpoint fields and responses, use the [Agent APIs reference](/api-reference/agents/introduction).

<Note>
  This guide covers identity delegation. Wallet delegation for Web3 use cases is planned; an identity binding does not grant wallet signing or spending authority.
</Note>

## Before you start

For the partner-managed API route shown below, prepare:

* A Partner ID and a partner login key with a published JWKS endpoint. See [SDK authentication](/get-started/authentication/sdk-auth).
* AIR Kit installed in your frontend, with users signing in through [`login`](/get-started/authentication/login).
* A defined consent journey. For the in-app partner binding route below, your product shows the user the agent and its requested scopes before calling the API. See [Ask for consent before binding](/products/agents/delegation-and-consent#ask-for-consent-before-binding).
* Agent keys enabled for your partner account. Otherwise, AIR API calls return `403 AGENT_KEYS_DISABLED`. Contact the AIR team to enable them and confirm environment access.

The Agent APIs use two hosts. Use the pair for the same environment.

| Environment | `AIR_API` (keys, session, checkout) | `CREDENTIAL_API` (list, verify) |
| - | - | - |
| Sandbox | `https://air.api.sandbox.air3.com` | `https://credential-testnet.api.sandbox.air3.com` |
| Production | `https://air.api.air3.com` | `https://credential-mainnet.api.air3.com` |

## How the flow fits together

```mermaid theme={null}
sequenceDiagram
    participant User
    participant Backend as Agent backend
    participant AIR as AIR API
    participant Cred as Credential API
    participant Service as Receiving service
    Note over User,AIR: 1. Delegation (partner-managed route shown)
    User->>Backend: Approve agent and requested scopes
    Backend->>AIR: Bind agent with approved user session
    AIR-->>Backend: Bound agent key
    Note over Backend,Service: 2. Verification
    Backend->>AIR: Create scoped agent session
    AIR-->>Backend: Short-lived agent JWT
    Backend->>Cred: Run agreed verification program
    Cred-->>Backend: Result and presentation when compliant
    Backend->>Service: Supply agreed evidence
    Service->>Service: Check evidence and apply access or benefit rules
```

## 1. Delegate to the agent identity

### Through the AIR app

The standard user journey is to approve the agent through the AIR app. The user chooses the agent they want to connect and approves identity access. The agent integration then uses the resulting supported identity binding.

**AIR app link: coming soon.** Contact the AIR team for this connection flow.

### Within your application

For a more integrated user experience, you can request access to the partner-managed delegation route. Your application owns the approval screen and binds the agent only after the user consents. The following examples document that route.

<Steps>
  <Step title="Get the user's approval and AIR Kit session">
    After the user signs in and approves the agent on your consent screen, get their partner access token in the frontend. Send it to your backend over your authenticated channel, along with the scopes they approved.

    ```ts theme={null}
    const { token } = await airService.getAccessToken();
    await fetch("/api/agent/bind", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ partnerAccessToken: token }),
    });
    ```

    The token identifies the user. Everything else in this guide runs on your backend.
  </Step>

  <Step title="Bind the agent once">
    From your backend, call [Bind an agent](/api-reference/agents/bind-agent-key) with the user's session and a freshly signed partner JWT. Request only the scopes the user approved.

    <CodeGroup>
      ```bash cURL theme={null}
      curl -X POST "$AIR_API/v2/auth/agent/keys/partner" \
        -H "Content-Type: application/json" \
        -H "x-partner-id: $PARTNER_ID" \
        -H "x-partner-access-token: $PARTNER_ACCESS_TOKEN" \
        -H "x-partner-jwt: $PARTNER_JWT" \
        -d '{
          "scope": "credentials.read credentials.verify",
          "nickname": "Shopping agent"
        }'
      ```

      ```ts TypeScript theme={null}
      const res = await fetch(`${AIR_API}/v2/auth/agent/keys/partner`, {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          "x-partner-id": PARTNER_ID,
          "x-partner-access-token": partnerAccessToken,
          "x-partner-jwt": partnerJwt,
        },
        body: JSON.stringify({
          scope: "credentials.read credentials.verify",
          nickname: "Shopping agent",
        }),
      });
      const agent = await res.json();
      ```
    </CodeGroup>

    The response is `201` and includes `agentApiKey`. AIR adds `openid` to the scope.

    ```json theme={null}
    {
      "id": "3f1a9c8e-2b7d-4f60-a1c5-e9b8d7f6a4c2",
      "publicKey": null,
      "createdAt": "2026-08-19T12:00:00.000Z",
      "scope": "openid credentials.read credentials.verify",
      "nickname": "Shopping agent",
      "partnerId": "11111111-2222-4333-8444-555555555555",
      "agentApiKey": "air_ag_<secret>"
    }
    ```

    <Warning>
      `agentApiKey` is returned only once. Store it encrypted on your backend with the key `id`. If you lose it, [rotate the key](/api-reference/agents/rotate-agent-key) to get a new one.
    </Warning>

    Add `commerce.checkout` only if the user approved the agent starting merchant checkouts. Scopes are fixed at bind time; to add one later, get approval, bind a new key, and revoke the old one.
  </Step>
</Steps>

## 2. Verify the user's credentials

After delegation, the agent authenticates with its own bound key. Its backend creates a short-lived session and runs the verification program agreed with the receiving service. That program determines the accepted issuers, conditions, and disclosure.

Listing credentials is optional when you already know which program to run. It can help the agent discover which evidence is available; only the verification result establishes whether the selected program is satisfied.

<Steps>
  <Step title="Create a session for each operation">
    Exchange the API key for a short-lived agent JWT with [Create an agent session](/api-reference/agents/create-agent-session). Request a subset of the bound scopes, or omit `scope` to receive all of them.

    <CodeGroup>
      ```bash cURL theme={null}
      curl -X POST "$AIR_API/v2/auth/agent/session" \
        -H "Content-Type: application/json" \
        -H "x-partner-id: $PARTNER_ID" \
        -H "x-agent-api-key: $AGENT_API_KEY" \
        -d '{ "scope": "openid credentials.read credentials.verify" }'
      ```

      ```ts TypeScript theme={null}
      const res = await fetch(`${AIR_API}/v2/auth/agent/session`, {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          "x-partner-id": PARTNER_ID,
          "x-agent-api-key": agentApiKey,
        },
        body: JSON.stringify({ scope: "openid credentials.read credentials.verify" }),
      });
      const { accessToken, user } = await res.json();
      ```
    </CodeGroup>

    ```json theme={null}
    {
      "accessToken": "<jwt>",
      "user": {
        "id": "018f9a2b-7c3d-7e10-9a4b-2c1d5e6f7a8b",
        "abstractAccountAddress": "0x…"
      }
    }
    ```

    The JWT expires after 15 minutes and has no refresh token. Create a new session when it expires.
  </Step>

  <Step title="List the user's credentials">
    With `credentials.read`, call [List credentials](/api-reference/agents/list-credentials) on the Credential API. Filter by `schemaId`, `issuerDid`, or `vct` (each repeatable), and page with `limit` (1–100) and `cursor`.

    <CodeGroup>
      ```bash cURL theme={null}
      curl "$CREDENTIAL_API/v2/credentials?limit=20" \
        -H "Authorization: Bearer $AGENT_JWT"
      ```

      ```ts TypeScript theme={null}
      const res = await fetch(`${CREDENTIAL_API}/v2/credentials?limit=20`, {
        headers: { Authorization: `Bearer ${accessToken}` },
      });
      const { items, hasMore, nextCursor } = await res.json();
      ```
    </CodeGroup>

    ```json theme={null}
    {
      "items": [
        {
          "storagePath": "vc/3f1a9c8e2b7d4f60a1c5e9b8d7f6a4c2/018f9a2b-7c3d-7e10-9a4b-2c1d5e6f7a8b",
          "schemaId": "<schema-id>",
          "issuerDid": "did:web:issuer.example",
          "vct": "<schema-vct>",
          "createdAt": "2026-08-01T00:00:00.000Z"
        }
      ],
      "hasMore": false
    }
    ```

    When `hasMore` is `true`, pass `nextCursor` as `cursor` to get the next page.
  </Step>

  <Step title="Verify a credential">
    With `credentials.verify`, call [Verify a credential](/api-reference/agents/verify-credential-by-agent) with a verification program ID. This endpoint accepts agent JWTs only.

    <CodeGroup>
      ```bash cURL theme={null}
      curl -X POST "$CREDENTIAL_API/v2/credentials/verify-by-agent" \
        -H "Content-Type: application/json" \
        -H "Authorization: Bearer $AGENT_JWT" \
        -d '{
          "programId": "<verification-program-id>",
          "fieldsToDisclose": "*"
        }'
      ```

      ```ts TypeScript theme={null}
      const res = await fetch(`${CREDENTIAL_API}/v2/credentials/verify-by-agent`, {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          Authorization: `Bearer ${accessToken}`,
        },
        body: JSON.stringify({
          programId: "<verification-program-id>",
          fieldsToDisclose: "*",
        }),
      });
      const { verificationResult } = await res.json();
      ```
    </CodeGroup>

    ```json theme={null}
    {
      "verificationResult": {
        "status": "Compliant",
        "verifiablePresentation": {
          "@context": ["https://www.w3.org/2018/credentials/v1"],
          "type": ["VerifiablePresentation"],
          "holder": "did:…",
          "verifiableCredential": ["<issuer-jwt>~<disclosure>~<kb-jwt>"]
        }
      }
    }
    ```

    * `status` is `Compliant`, `Non-Compliant`, or `NotFound`. `verifiablePresentation` is present only when `Compliant`.
    * `fieldsToDisclose` can be omitted, `"*"`, or a list such as `["birthday", "documentType"]`. What each option returns depends on the credential format; see the [endpoint reference](/api-reference/agents/verify-credential-by-agent).
    * For SD-JWT programs, pass a `nonce` to bind the presentation to your challenge. It is required when the credential was issued with `cnf.jwk`.

    Verification runs offchain. Before you pass a result to a merchant, see [What a verification result proves](/products/agents/how-it-works#what-a-verification-result-proves).

    A `502 CREDENTIAL_STORAGE_UNAVAILABLE` means storage was unavailable, not that the user lacks the credential.
  </Step>
</Steps>

The receiving service checks the supplied evidence under its agreed trust model and applies its own access or benefit rules. A successful identity check does not authorize additional disclosure, a purchase, or a payment.

## Merchant checkout handoff

An existing [checkout session](/api-reference/agents/create-checkout-session) can carry the user's AIR Account identity to a supported merchant when the user has approved `commerce.checkout`. It is a merchant-scoped token, not wallet delegation. Checkout and payment follow their own integration and approvals.

## Manage bound agents

All key routes need `x-partner-id` and the user's `x-partner-access-token`. Routes that change a key's access also need `x-partner-jwt`.

| Task | Endpoint | Needs `x-partner-jwt` | Effect |
| - | - | - | - |
| List agents | [`GET /v2/auth/agent/keys/partner`](/api-reference/agents/list-agent-keys) | No | Returns the keys your partner bound for this user, without `agentApiKey`. |
| Rename | [`PATCH /v2/auth/agent/keys/partner/{id}`](/api-reference/agents/update-agent-key-nickname) | No | Sets or clears the nickname. |
| Rotate | [`POST /v2/auth/agent/keys/partner/{id}/rotate`](/api-reference/agents/rotate-agent-key) | Yes | Returns a new `agentApiKey` once and invalidates agent JWTs already issued. |
| Revoke | [`DELETE /v2/auth/agent/keys/partner/{id}`](/api-reference/agents/revoke-agent-key) | Yes | Removes the key. New sessions for it fail. |

Each user can have a limited number of agent keys. Binding past the limit returns `409 CONFLICT_REQUEST`.

## Use a public key instead of an API key

If the agent holds its own P-256 key pair, send `publicKey` (PEM or base64 DER) at bind. The agent can then create sessions with a `signedMessage` in the body instead of the `x-agent-api-key` header. Send exactly one of the two.

```json theme={null}
{
  "scope": "openid credentials.read",
  "signedMessage": {
    "message": "<agent_pubkey>:<userId>:<unixEpochSeconds>",
    "signature": "<base64 ECDSA P-256 signature over message>",
    "publicKey": "-----BEGIN PUBLIC KEY-----\n…\n-----END PUBLIC KEY-----"
  }
}
```

The signature can be DER or IEEE P1363 (ES256), in standard base64 or base64url. Checkout sessions accept the same `signedMessage`.

## Security checklist

* Keep `agentApiKey`, the partner login key, and `x-partner-jwt` on your backend.
* Request only the scopes the agent's task needs. Sessions can narrow them further.
* Create a session per operation, and don't cache agent JWTs beyond their 15-minute lifetime.
* Rotate a key if it may have leaked. When the user disconnects the agent, rotate and then revoke the key so sessions already issued end too.
* Send checkout JWTs only to the merchant named in their `aud`.

For consent, disconnect flows, and how scopes relate to delegation credentials, see [Delegation and consent](/products/agents/delegation-and-consent).


# Use cases
Source: https://docs.air3.com/products/agents/use-cases

Explore identity-based Agent Gating and Agentic Commerce for agents acting on behalf of users.

When an agent acts for a user, the receiving service needs to understand the relationship and the evidence behind the request. AIR's identity flow supports two starting points.

## Agent Gating

Use an authenticated agent-user relationship and accepted credentials to decide which requests can access your service. Apply your own access rules, quotas, and abuse controls to reduce anonymous misuse and protect member-only or limited benefits.

Read [Agent Gating](/products/agents/agent-gating) for the checks and an example.

## Agentic Commerce

Let an agent carry user-approved membership or eligibility into a merchant interaction. The merchant checks the evidence and applies the relevant price, discount, or entitlement.

### Membership pricing

An accepted loyalty credential can qualify a customer for a member benefit through their agent. The identity check establishes eligibility; ordering and payment require their own authority.

Read [Agentic Commerce](/products/agents/offers-for-agents) for member discounts, travel benefits, and relevant offers.

## Choose your next step

Identify the agent, its operator, the consenting user, and the receiving service in [Plan your integration](/products/agents/integration-options). Then follow the two stages in [Using Agentic Identity](/products/agents/partner-agent-api): delegation and verification.


# What is AIR Agent
Source: https://docs.air3.com/products/agents/what-is-air-agents

Give an agent a recognized identity, link it to the user it represents, and verify the evidence needed for a request.

AIR Agent provides the identity layer for agents acting on a user's behalf. It connects an agent identity to the user's AIR Account with their approval, so an application can understand who is behind a request and check the relevant credentials.

An agent might be a personal assistant, a chatbot embedded in an application, or software the user runs themselves. The integration starts by identifying that agent, its operator, and the user whose identity it will use.

## Three things to establish

| Question | What supplies the answer |
| - | - |
| **Which agent is making the request?** | The agent identity, represented in the current Agent APIs by a bound key and its authenticated session. |
| **Whom does it represent, and what may it access?** | The link to the user's AIR Account, their consent, and the bound scopes. |
| **Does the user qualify for this interaction?** | Credentials from accepted issuers, checked against the receiving application's verification rules. |

These are separate decisions. Authenticating an agent does not itself establish a user's eligibility, and a verified membership does not authorize a purchase.

## Delegation, then verification

The user first approves identity access for the chosen agent. The agent can then use that access to verify the user's credentials for the task. The receiving application decides what evidence it accepts and how to apply the result.

Your integration defines the source of the claims, the consent journey, and which participant checks the evidence. Start with [Plan your integration](/products/agents/integration-options), then follow [Using Agentic Identity](/products/agents/partner-agent-api).

<Note>
  AIR Agent currently focuses on identity delegation. Wallet delegation for Web3 use cases is planned. Identity access does not grant wallet signing or spending authority.
</Note>

## What you can build

* **[Agent Gating](/products/agents/agent-gating):** apply access rules using the agent-user relationship and accepted identity evidence.
* **[Agentic Commerce](/products/agents/offers-for-agents):** let an agent present user-approved membership or eligibility to obtain relevant benefits, such as a discount.


# Setting up your backend
Source: https://docs.air3.com/products/identity/backend-hosting

Deploy an AIR issuer backend with public HTTPS endpoints and add a database only when your implementation needs it.

Host an issuer backend so AIR can call its credential preview and issuance
endpoints. You can use a hosted service or expose a local service through an
HTTPS tunnel for sandbox development.

**A database is optional in sandbox.** Revocation, issuance history, and the
token status list need a database, so plan for one before production. Use any
database your backend supports; the reference issuer service uses PostgreSQL.
Encrypted credentials are stored in dStorage either way.

## What you are hosting

| Component | Purpose | Required? |
| - | - | - |
| Issuer backend | Authorizes issuance, loads claims, signs and encrypts credentials, uploads them to dStorage, and serves revocation status | Yes, for the on-demand backend integration |
| `did:web` document | Publishes the issuer DID and the keys verifiers use to check your credentials, at `/.well-known/did.json` | Yes; served by the issuer service |
| Public JWKS endpoint | Publishes the public keys AIR uses to validate Partner JWTs | Yes; it may share a host with your backend or web app |
| Database | Persists issuer history, revocation records, and the token status list. The reference issuer service uses PostgreSQL | Optional in sandbox; required for revocation |
| dStorage | Stores encrypted credential envelopes | Used by the issuance flow; independent of your application's database |

Credential claims can come from an existing service or API, an existing database,
or static test data. You do not need to create a new database simply to provide claims.

## Fork and review the backend implementation

Fork the SD-JWT branch of the [AIR issuer service](https://github.com/MocaNetwork/air-issuer-service/tree/main).
It issues `SD_JWT_VC` credentials under a `did:web` issuer DID.

* The service runs without `DATABASE_URL` for sandbox testing. For issuance history, revocation, and a token status list at scale across many users, you will need to persist the relevant data in your own database.
* Iden3 issuers use a separate branch. See [Iden3 credentials](/products/identity/iden3-credentials).

This guide follows the issuer service used in the
[issuance quickstart](/get-started/quickstarts/issue-credentials#step-1-generate-partner-secrets).

## Choose a hosting path

| Need | Options | Setup |
| - | - | - |
| Local sandbox | Local Node.js service with an HTTPS tunnel | Database only if your implementation or features require one |
| Hosted backend | Railway, Render, Koyeb, or your existing infrastructure | Public HTTPS, environment variables, and the service's build/start commands |
| Optional database | Any database your backend supports. For the reference issuer service: Railway PostgreSQL, Neon, Supabase, or your existing PostgreSQL service | For the reference issuer service, set `DATABASE_URL` and run migrations |

Check each provider's current plans and idle/sleep behavior before selecting a
sandbox host: [Railway](https://docs.railway.com/pricing/plans),
[Render](https://render.com/docs/free), [Koyeb](https://www.koyeb.com/docs/faqs/pricing),
[Neon](https://neon.com/docs/introduction/plans), and
[Supabase](https://supabase.com/docs/guides/platform/billing-on-supabase).
A sleeping service may delay the first credential request.

## Prerequisites

* Your issuer backend repository
* An [AIR Developer Dashboard](https://developers.sandbox.air3.com/dashboard) Partner ID
* Partner secrets configured using the [issuance quickstart](/get-started/quickstarts/issue-credentials#step-1-generate-partner-secrets)
* A public HTTPS domain or development tunnel

## Deploy the issuer service

The following steps use Railway as an example. Apply the same build commands,
environment configuration, and public endpoint requirements on another host.

<Steps>
  <Step title="Create a project and select your repository">
    Create a Railway project and add your fork of the AIR issuer service.
    Use the same revision you configured and tested locally.
  </Step>

  <Step title="Configure build and start commands">
    | Setting | Value |
    | - | - |
    | Build command | `npm i && npm run build` |
    | Start command | `npm run start:prod` |
    | Pre-deploy command | Leave empty unless you enabled database persistence |

    If you enable database persistence, set the pre-deploy command to
    `npx mikro-orm migration:up` after configuring `DATABASE_URL`.
  </Step>

  <Step title="Configure the public origin and environment">
    Generate a public HTTPS domain in the host's networking settings. Set
    `ISSUER_ORIGIN` to that origin without a trailing slash. Use a custom
    domain you control for production: the issuer DID is
    `did:web:<host of ISSUER_ORIGIN>`, so the host is your issuer identity.

    Add the environment values from
    [Configure and start the issuer backend](/get-started/quickstarts/issue-credentials#step-2-configure-and-start-the-issuer-backend),
    including Partner JWT key configuration, `PARTNER_JWKS`, and the issuer
    API keys. Keep secrets in the host's environment settings.

    For this sandbox example, use `NODE_ENV=sandbox` and sandbox API origins.
    Railway supplies `PORT`; the issuer service listens on it.
  </Step>

  <Step title="Optionally add a database">
    Skip this step if you are using a backend configuration without database
    persistence.

    The reference issuer service uses PostgreSQL. Add PostgreSQL to the project,
    or use an existing PostgreSQL service, and set `DATABASE_URL` on the issuer
    backend to its connection string. If you built your own backend, connect the
    database it uses instead.

    For a Railway database named `Postgres`, the reference variable is:

    ```text theme={null}
    DATABASE_URL=${{Postgres.DATABASE_URL}}
    ```

    Run migrations before starting the database-backed service. This enables the
    persistence used by issuance history, revocation records, and the token
    status list.
  </Step>

  <Step title="Deploy and check the service">
    Confirm the process starts successfully, then open
    `https://<your-host>/.well-known/did.json` and
    `https://<your-host>/.well-known/jwt-vc-issuer`. The DID document's `id` is
    the issuer DID you register with AIR. Verify that the public host routes
    requests to your issuer endpoints and that its TLS certificate is valid.

    When you use a database, also confirm connectivity and successful migrations.
    Use your implementation's health checks.
  </Step>
</Steps>

Keep `ISSUER_ORIGIN` stable once you issue credentials. It defines the issuer
DID, and revocation and status-list URLs in issued credentials refer to it.

## Optional database persistence

For the reference issuer service, apply its migrations when `DATABASE_URL` is configured:

```bash theme={null}
npx mikro-orm migration:up
```

Without database persistence, skip migrations and database readiness checks.
Do not use an empty database history as evidence that issuance failed, or rely
on persistent history and revocation records being available.

Connect a durable database and validate history and revocation behavior before
using the issuer with real users. dStorage keeps the encrypted credential; it
serves a different purpose from issuer application records. See
[Revoke credentials](/products/identity/revocation).

## After hosting: connect AIR

1. **Register the issuer.** Use **Issuer → Settings** in the sandbox or
   production Dashboard and enter the `did:web` issuer DID. Both environments
   are self-serve for SD-JWT issuers.
2. **Register the endpoint URLs.** Configure `availableVcApiUrl` and `issueVcApiUrl`
   to point to `POST /available-vc` and `POST /issue-vc` on your backend, and
   `revocationStatusApiUrl` to its `GET /revocation-status/:nonce` route.
3. **Match the issuer API key.** Register the backend's `API_KEY` with AIR.
   AIR sends it as `x-api-key`; keep it out of browser code.
4. **Register the public JWKS URL.** Its keys must match the Partner JWT signing
   key and `kid`. See [JWKS endpoint setup](/get-started/authentication/jwks-endpoint).
5. **Register the web app origin.** Add it under **Account → Domains**.
6. **Test issuance.** Confirm the holder sees the preview, approves issuance,
   and can use the resulting credential. See the
   [issuance quickstart](/get-started/quickstarts/issue-credentials#step-8-test-end-to-end).

The issuer endpoints and JWKS must be reachable by AIR over HTTPS. They may share
a domain; separate public origins for every component are not required.

If you enable CORS on the issuer or a reverse proxy in front of it, allow
`*.air3.com`. Restricting origins to your own domain breaks the holder claim flow.

## Go-live checklist

* [ ] `did:web` document served at `${ISSUER_ORIGIN}/.well-known/did.json` and its DID registered with AIR
* [ ] Partner JWT keys (`PARTNER_*`) match your JWKS, and `PARTNER_JWKS` holds the matching public keys
* [ ] Each Dashboard schema has a matching class in `src/issuer/sd-jwt-vc-schemas/`, exported from `index.ts`
* [ ] `generateCredentialData` returns schema-valid claims, and `disclosureFrame` and `expirySec` are set per schema
* [ ] The database is durable and its migrations are applied
* [ ] `ISSUER_ORIGIN` is public HTTPS on a domain you control, and the status endpoints are reachable
* [ ] `availableVcApiUrl`, `issueVcApiUrl`, `revocationStatusApiUrl`, and the API key are set in AIR
* [ ] If you use the [token status list](/products/identity/revocation#token-status-list), the partition size is final and a publish job is scheduled
* [ ] The claim flow passes end to end with a test holder

## Local development

Run the issuer locally and expose it through an HTTPS tunnel such as
[ngrok](https://ngrok.com) or
[cloudflared](https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/).
Follow the [HTTPS tunnel setup](/get-started/authentication/jwks-endpoint#local-development-https-tunnel).

Set `ISSUER_ORIGIN` and the registered issuer endpoint URLs to the tunnel address.
If the tunnel address changes, update both. Add a local or managed database
connection (PostgreSQL for the reference issuer service) only when your backend
configuration uses database persistence.

## Next steps

* [Credential issuance quickstart](/get-started/quickstarts/issue-credentials)
* [Revoke credentials](/products/identity/revocation)
* [JWKS endpoint setup](/get-started/authentication/jwks-endpoint)
* [Architecture and data flow](/technicals/architecture)


# Connect with other modules
Source: https://docs.air3.com/products/identity/beyond-identity

Explore how AIR Identity connects to loyalty credentials, user-bound agents, and AIR smart accounts.

AIR Identity provides the credential issuance and verification used by other AIR modules. Follow the relevant product guide for the experience you want to build.

<CardGroup>
  <Card title="AIR Loyalty" icon="gift" href="/products/loyalty/how-it-works">
    Issue loyalty status as a credential that customers can present to partner brands.
  </Card>

  <Card title="AIR Agent" icon="robot" href="/products/agents/how-it-works">
    Bind an agent to a user's AIR Account and verify the user's credentials through the Agent APIs.
  </Card>

  <Card title="AIR Money" icon="wallet" href="/products/money/how-it-works">
    Explore the smart accounts and transaction flows available to signed-in AIR users.
  </Card>
</CardGroup>


# Other ways to verify
Source: https://docs.air3.com/products/identity/credential-formats

AIR issues SD-JWT VC credentials by default. Iden3 BJJ credentials with zero-knowledge proofs are an advanced option the AIR team enables.

AIR supports two credential families. Every AIR credential is issuer-signed, encrypted to the holder, and presented with the holder's approval. The format decides what a verifier can learn and how it checks the result.

| Format | Proof type | Availability |
| - | - | - |
| **SD-JWT VC** (IETF SD-JWT-based Verifiable Credentials) | `SD_JWT_VC` | Default. Self-serve in sandbox and production. |
| **Iden3** (BJJ signature) | `BJJ_SIG_2021` | Advanced. Contact the AIR team to enable it. See [Iden3 credentials](/products/identity/iden3-credentials). |

## How they compare

Both formats support selective disclosure. The choice comes down to whether you need the simplicity of a JWT or the extra privacy of a zero-knowledge proof.

| | SD-JWT VC | Iden3 BJJ |
| - | - | - |
| **What the verifier learns** | The exact value of each claim the holder discloses, such as `age: 25`. Undisclosed claims stay hidden behind salted digests. | Exact values, or a condition such as `age > 18` proven without revealing the value. |
| **Linkability** | The issuer-signed token is the same in every presentation, so verifiers that compare notes can link them. | Proofs are randomized for each presentation and are unlinkable. |
| **Holder cost** | Near instant. The holder sends the selected disclosures. | Proof generation takes seconds of CPU on the holder's device. |
| **Verifier cost** | Sub-millisecond: check one signature and hash the disclosures. | Milliseconds, with a ZK verifier and verification keys. |
| **Verifier tooling** | Standard JWT libraries. | An Iden3-specific verifier with circuits and on-chain issuer state. |
| **Holder binding** | Optional `cnf` key in the credential, plus a key-binding JWT for each presentation. | Depends on the proof profile. |
| **Revocation** | Per-credential status endpoint, or an IETF Token Status List. | Non-membership proof against the issuer's revocation tree. |
| **On-chain verification** | Not used. Verification is off-chain. | Supported through the Universal Verifier and Groth16 verifier contracts. |

## Which should I use

Use **SD-JWT VC** unless you have a specific reason not to. It is the better fit for:

* Most partner integrations: membership, loyalty tier, KYC attributes, tickets.
* Verifiers on your own backend, using standard JWT libraries.
* Integrations with external parties that work with IETF and OpenID tooling.

Ask about **Iden3** when you need:

* Predicate proofs, such as "over 18" or "balance above a threshold", without revealing the underlying value.
* Presentations that verifiers cannot link to each other.
* Verification by a smart contract.

## Holder binding for SD-JWT

An SD-JWT VC can be bound to its holder, so a copy that leaks cannot be presented by someone else.

1. **At issuance**, the user's AIR Account provides a P-256 public key. The issuer writes it to the credential's `cnf.jwk` claim before signing.
2. **At verification**, your app passes a `nonce`. The holder signs a key-binding JWT (KB-JWT) with the matching private key. The KB-JWT covers your nonce, your `programId`, a timestamp, and a hash of the disclosed claims.
3. **Your backend** checks the KB-JWT against `cnf.jwk`. A replayed or altered presentation fails.

Without a nonce, or for a credential issued without `cnf`, the presentation is a bearer token. See [Verify SD-JWT on your backend](/products/identity/verify-sd-jwt) for the checks.

## Standards each format uses

| Standard | Used by | Notes |
| - | - | - |
| IETF SD-JWT-based Verifiable Credentials | SD-JWT VC | Selective disclosure and optional key binding. External acceptance depends on the verifier's algorithms, metadata, and trust policy. |
| `did:web` | SD-JWT VC issuers | The issuer DID resolves to a DID document on the issuer's own domain. |
| IETF Token Status List | SD-JWT VC | Optional, and configured per issuer. See [Revoke credentials](/products/identity/revocation#token-status-list). |
| W3C Verifiable Credentials Data Model v1.1 (JSON-LD) | Iden3 | Defines the credential structure. Verifiers must also implement the Iden3 proof profile; generic W3C VC support is not enough. |
| W3C Verifiable Presentation (VC Data Model v2.0) | Both | The envelope a successful verification returns. Each enclosed credential is checked in its own format. |

Supporting a standard does not on its own make a deployment compliant with a regulation. That depends on the issuer, the assurance model, and the rules of the jurisdiction.

## Related

* [Issuing credentials](/products/identity/issuing-credentials)
* [Verifying credentials](/products/identity/verify)
* [Selective disclosure](/products/identity/selective-disclosure)
* [Iden3 credentials](/products/identity/iden3-credentials)


# What are credentials
Source: https://docs.air3.com/products/identity/credentials-flow

How AIR Credentials work — the credential lifecycle, issuer, holder, and verifier roles, SD-JWT credentials, encrypted DStorage, and program-driven verification.

## What are AIR Credentials?

**AIR Credentials** are verifiable credentials that issuers sign with their own keys and that holders carry in their AIR Account to any app using AIR verification. Credential payloads are encrypted to the holder before storage, and AIR stores and routes only opaque ciphertext and metadata — it never sees the underlying data. Holders prove claims (such as age, qualifications, or affiliations) by disclosing only the fields a verifier requests. The result is privacy-preserving, issuer-sovereign identity.

## How it works at a glance

* **SD-JWT credentials.** Credentials use the `SD_JWT_VC` proof type by default: issuer-signed, selectively disclosable, and optionally bound to the holder's key. Verification checks a signature and hashes, so it is fast and runs off-chain. Iden3 credentials with zero-knowledge proofs are an [advanced option](/products/identity/credential-formats).
* **Issuer sovereignty.** Issuers control their own source data and signing keys through an Issuer Backend. The Issuer DID (`did:web:<your host>`) is published from the issuer's own domain and registered with AIR — AIR never holds issuer keys, signs on the issuer's behalf, or sees plaintext data.
* **Encrypted decentralized storage.** The issuer signs the credential, encrypts the payload to the holder's public key, and stores the encrypted envelope in DStorage, Moca Chain's decentralized storage layer. AIR acts as a blind facilitator — it stores and routes ciphertext and metadata, never plaintext.
* **Program-driven verification.** Verifiers configure a Verification Program that centrally controls the accepted format, requested claims, and selective disclosure. Successful verification returns a W3C Verifiable Presentation.
* **Fast.** Issuance and verification typically complete in \~1–4 seconds.

## The credential lifecycle

A credential goes through three phases:

1. **Issuance.** The issuer builds, signs, and encrypts the credential, then stores the encrypted envelope in DStorage.
2. **Storage.** AIR stores and routes the ciphertext and metadata. Only the holder can decrypt it.
3. **Verification.** The holder discloses only the fields a Verification Program requests, and the verifier receives a Verifiable Presentation to check.

```mermaid theme={null}
graph TD
    A[Issuer source data] --> B[Issuer signs credential]
    B --> C[Encrypt to holder public key]
    C --> D[Store encrypted envelope in DStorage]
    D --> E[Holder loads and decrypts credential]
    E --> F[Selective disclosure + key-binding JWT]
    F --> G[Program-driven verification]
    G --> H[Verifiable Presentation]
```

<Note>
  Every issuance and verification call is authenticated with a Partner JWT, which AIR checks against a JWKS endpoint you host and register in the Developer Dashboard. None of these phases can run until that endpoint is live. See [JWKS endpoint setup](/get-started/authentication/jwks-endpoint).
</Note>

## Who's who: issuer, holder, verifier

| | **Issuer** | **Holder** | **Verifier** |
| - | - | - | - |
| **Role** | The entity that creates and vouches for the verifiable credential. | The individual or entity that receives and stores the encrypted credential in their AIR Account. | The party that requests and checks for proof of specific claims or attributes. |
| **Key Actions** | Owns source data, signs and encrypts credentials | Receives, holds, and presents credentials | Configures verification programs and consumes proofs |
| **Details** | The issuer structures the data, signs it with issuer-controlled keys, encrypts it to the holder, and stores the encrypted envelope in DStorage. | The holder receives an encrypted payload only they can decrypt, and controls how their credentials are shared. | Instead of accessing the full credential, the verifier receives only the claims it requested, signed by the issuer and bound to the holder. |
| **Examples** | Universities, governments, protocols, DAOs, gaming platforms, community managers | Students, citizens, gamers, employees, community members | Employers, service providers, event organizers, online platforms, access-controlled communities |

## AIR as a blind facilitator

In the AIR model, the trust boundary sits with the issuer, not with AIR:

* Issuer user data remains with the issuer.
* The issuer signs credentials with issuer-controlled keys.
* Credential payloads are encrypted to the holder's public key before storage.
* AIR stores encrypted credential objects and metadata — not plaintext issuer data.
* Only the holder can decrypt the credential and generate proofs from it.

This keeps AIR out of the plaintext data path while still providing storage, routing, discovery, and program-driven verification.

## Choose your integration role

| Role | Primary integration | Notes |
| - | - | - |
| **Issuer** | Issuer Backend + AIR Dashboard setup | Best path for on-demand issuance, privacy, revocation, and issuer-controlled data. |
| **Verifier** | Verification Program + AIR Verifier SDK | Verifiers use program-driven verification behavior. |
| **Issuer site** | Self-hosted frontend + AIR Issuer SDK | Recommended when issuers want full UX/auth control. |
| **Verifier site** | Self-hosted frontend + AIR Verifier SDK | Recommended when verifiers want full UX/auth control. |
| **Bulk migration** | Operational bulk import | For large backfills; coordinate early because it may require manual operations. |

## Issuer process

1. Set up a Partner Account in the <a href="https://developers.sandbox.air3.com/dashboard">Developer Dashboard</a>.
2. Deploy your issuer service and register its `did:web` Issuer DID with AIR. Because the DID is published from your domain with your keys, you own it — AIR does not generate it for you. Registering your DID enables credential services on your account.
3. Configure the supported signature type (`SD_JWT_VC`) and JWKS / key information.
4. Create or search for a relevant Credential Schema.
5. Create an issuance program.
6. Integrate an Issuer Backend that AIR calls through `available-vc` and `issue-vc` when your frontend calls `air.issueCredential` — or use [direct issuance](/products/identity/issuing-credentials#direct-issuance) when a backend event should issue without a user session.
7. Issue encrypted credentials to your users.

See [Issuing Credentials](/products/identity/issuing-credentials) for both the SDK and on-demand issuance paths.

## Verifier process

1. Set up a Partner Account in the <a href="https://developers.sandbox.air3.com/dashboard">Developer Dashboard</a>.
2. Configure General Partner settings and obtain a Verifier DID.
3. Search for relevant Credential Schemas and Issuers.
4. Create a Verification Program and configure the accepted proof type, requested claims, and selective disclosure.
5. Integrate the AIR Verifier SDK and start verification with a `programId` and a `nonce`.
6. On success, [verify the returned presentation on your backend](/products/identity/verify-sd-jwt).

See [Verifying Credentials](/products/identity/verify) for the full verifier integration.


# Iden3 credentials
Source: https://docs.air3.com/products/identity/iden3-credentials

Issue and verify Iden3 BJJ credentials with zero-knowledge proofs and optional on-chain verification. Contact the AIR team to enable this option.

<Note>
  Iden3 credentials are an advanced option. **Contact the AIR team to enable them** for your partner account before you start: [Partner with us](https://air3.com/partner-with-us). New integrations should use [SD-JWT VC](/products/identity/credential-formats), which is self-serve.
</Note>

Iden3 credentials use a BJJ\_SIG\_2021 signature and the W3C Verifiable Credentials Data Model v1.1 in JSON-LD form. Holders prove claims with Groth16 zero-knowledge proofs.

## When to use Iden3

Choose Iden3 over SD-JWT when you need one of these:

* **Predicate proofs.** Prove a condition such as `age > 18` without revealing the value.
* **Unlinkable presentations.** Each proof is randomized, so verifiers cannot link a holder's presentations.
* **On-chain verification.** Check a proof through the Universal Verifier and Groth16 verifier contracts.

The cost is heavier proof generation on the holder's device and a verifier that implements the Iden3 proof profile. Generic W3C VC support is not enough. See [Credential formats](/products/identity/credential-formats) for the full comparison.

| Proof type | What it is |
| - | - |
| `BJJ_SIG_2021` | The issuer signs the credential with its BJJ key. Supports off-chain and on-chain verification. |

## Set up the issuer service

Iden3 issuers use the Iden3 branch of the [AIR issuer service](https://github.com/MocaNetwork/air-issuer-service/tree/main_iden3). It exposes the same `POST /available-vc` and `POST /issue-vc` contract as the SD-JWT service, with `proofType: "BJJ_SIG_2021"`.

```bash theme={null}
git clone -b main_iden3 https://github.com/MocaNetwork/air-issuer-service.git
cd air-issuer-service
npm i
```

### Generate the issuer seed

Your BJJ issuer DID is derived from a 32-byte seed:

```bash theme={null}
echo "SEED=0x$(openssl rand -hex 32)"
```

<Warning>
  `SEED` is your issuer identity. Store it in a secret manager and back it up. Losing it means you can no longer act as that issuer, and changing it creates a new issuer DID.
</Warning>

### Configure the environment

| Variable | Purpose |
| - | - |
| `NODE_ENV` | `sandbox` or your production value |
| `DATABASE_URL` | PostgreSQL connection URL |
| `ISSUER_ORIGIN` | Public HTTPS origin of the service, without a trailing slash. Used in credential status URLs |
| `SEED` | 32-byte hex seed for the BJJ issuer identity |
| `PARTNER_ID` | Your AIR Partner ID |
| `PARTNER_PRIVATE_KEY_KID`, `PARTNER_PRIVATE_KEY_ALG`, `PARTNER_PRIVATE_KEY_DER` | Partner JWT signing key, as in the [issuance quickstart](/get-started/quickstarts/issue-credentials#step-2-configure-and-start-the-issuer-backend) |
| `PARTNER_JWKS` | Public JWKS matching the partner key |
| `API_KEY` | Value AIR sends in `x-api-key` |
| `ADMIN_API_KEY` | Value your servers send in `x-admin-api-key` |

### Extract the issuer DID

Start the service. It logs the DID at startup as `Issuer DID: did:air:…`. You can also print it with the REPL:

```bash theme={null}
echo 'console.log(get(CredentialIssuingService).issuerDID.string());' | npm run repl -
```

Give this DID to the AIR team with your Partner ID, API key, and endpoint URLs so they can register and activate the issuer.

### Define a schema class

Create the schema in the Dashboard and record its schema ID, type, schema JSON URL, and JSON-LD context URL. Then add a class under `src/issuer/schemas/`:

```ts src/issuer/schemas/schema-<SCHEMA_ID>.ts theme={null}
import { BaseSchema } from "./base-schema";

export default class Schema extends BaseSchema {
  public readonly schemaId = "<SCHEMA_ID>";
  public readonly schemaType = "<TYPE>";
  public readonly schemaUrl = "https://.../schema";
  public readonly schemaContextUrl = "https://.../ctx";

  async generateCredentialData(userId: string) {
    return {
      credentialSubject: {
        // keys must match the schema; do not set `id`
        someField: "...",
      },
      expiration: Math.floor(Date.now() / 1000) + 30 * 24 * 60 * 60,
    };
  }
}
```

Register it in `src/issuer/schemas/index.ts`:

```ts src/issuer/schemas/index.ts theme={null}
import Schema1 from "./schema-<SCHEMA_ID>";

const schemas: BaseSchema[] = [new Schema1()];
export default schemas;
```

Claim keys and types must match the Dashboard schema exactly, or merklization and verification fail. The service sets `credentialSubject.id` to the holder DID.

### Issue in bulk without a user session

The Iden3 service includes a CSV runner. It resolves each email through AIR `initialize-user`, issues, encrypts, and uploads:

```csv theme={null}
email,expiration,credentialSubject.field1,credentialSubject.field2
member@example.com,2030-01-01T00:00:00+08:00,"""Hello World""",4
```

Every `credentialSubject.[field]` cell must be a JSON-stringified value, so strings carry quotes.

```bash theme={null}
npm run batch-issue-vc-csv -- \
  <SCHEMA_ID> \
  <SCHEMA_URL> \
  <SCHEMA_TYPE> \
  ./credentials-batch-1.csv
```

The runner writes a result log named `[unix_timestamp_ms].csv`.

### Revocation and status

| Method | Path | Called by | Purpose |
| - | - | - | - |
| `POST` | `/admin/revoke` | Your servers (`x-admin-api-key`) | Revoke by `revocationNonce` |
| `GET` | `/admin/issuance-history` | Your servers (`x-admin-api-key`) | Find issued credentials and their nonces |
| `GET` | `/revocation-status/:nonce` | Verifiers | `{ "isRevoked": boolean }` |
| `GET` | `/credential-status/:nonce` | Verifiers | Non-revocation Merkle proof and issuer tree state (`{ issuer }`) |

The Iden3 service embeds a `/credential-status` URL under `ISSUER_ORIGIN` in each credential, so keep the origin stable. It does not support the token status list.

### Issue both formats

A partner that issues SD-JWT and Iden3 credentials runs both services, each at its own `ISSUER_ORIGIN`. Set `IDEN3_ISSUER_DID` on the SD-JWT service to your BJJ issuer DID; it is then listed under `alsoKnownAs` in your `did:web` document.

## Verify Iden3 credentials

Verification programs for Iden3 credentials can require a zero-knowledge proof and choose where it is checked:

| Use case | Recommended mode |
| - | - |
| Fast eligibility check with no cryptographic proof requirement | Off-chain, no ZKP |
| Privacy-preserving claim proof | Off-chain Sig ZKP |
| Strongest auditability or settlement requirement | Sig ZKP + on-chain verification |

| Mode | Where verification runs | What the app receives |
| - | - | - |
| **Off-chain** | Outside a blockchain transaction, against the program's requirements. | Verification status and the presentation and proof material for the program. |
| **On-chain** | The proof is submitted to the Universal Verifier. Available for `BJJ_SIG_2021` credentials. | The verification outcome and the on-chain transaction information. |

For Iden3 programs, `verifiablePresentation.verifiableCredential` holds W3C Verifiable Credential objects whose `credentialSubject` contains the disclosed claims. `proof` is present only when the program requires a zero-knowledge proof. It carries the Groth16 `proofValue` and `publicSignals`, plus `transactionHash` for on-chain programs. Programs with several ZK queries return one entry per query. See `VerifiablePresentationProof` in the [SDK reference](/api-reference/sdk-reference).

<Warning>
  When an Iden3 program does **not** require a zero-knowledge proof, the presentation has no `proof` block. It is unsigned and carries no cryptographic guarantee; the verification session status is the only trust anchor.
</Warning>

Iden3 credentials and personal data stay off-chain. Depending on the profile, only proofs, verification results, issuer state roots, or revocation commitments are recorded on Moca Chain.

## Related

* [Credential formats](/products/identity/credential-formats)
* [Verifying credentials](/products/identity/verify)
* [Issuance API reference](/api-reference/issuance-api)


# Connect your agent
Source: https://docs.air3.com/products/identity/integrating-using-ai

Add the AIR docs MCP server to your agent, then start building.

## Connect via MCP

Choose your tool below and add the AIR documentation server:

```text theme={null}
https://docs.air3.com/mcp
```

<Tabs>
  <Tab title="Claude">
    <Steps>
      <Step title="Add the Moca Network MCP server to Claude">
        1. Navigate to the [Connectors](https://claude.ai/settings/connectors) page in the Claude settings.
        2. Select **Add custom connector**.
        3. Add the Moca Network MCP server:
           * Name: `MocaNetwork`
           * URL: `https://docs.air3.com/mcp`
        4. Select **Add**.
      </Step>

      <Step title="Access the MCP server in your chat">
        1. When using Claude, select the attachments button (the plus icon).
        2. Select the MocaNetwork MCP server.
        3. Ask Claude a question about Moca Network or AIR Kit.
      </Step>
    </Steps>

    See the [Model Context Protocol documentation](https://modelcontextprotocol.io/docs/tutorials/use-remote-mcp-server#connecting-to-a-remote-mcp-server) for more details.
  </Tab>

  <Tab title="Claude Code">
    <Steps>
      <Step title="Add the MCP server to Claude Code">
        Run the following command:

        ```bash theme={null}
        claude mcp add --transport http MocaNetwork https://docs.air3.com/mcp
        ```
      </Step>

      <Step title="Test the connection">
        Verify the connection by running:

        ```bash theme={null}
        claude mcp list
        ```
      </Step>
    </Steps>

    See the [Claude Code documentation](https://docs.anthropic.com/en/docs/claude-code/mcp#installing-mcp-servers) for more details.
  </Tab>

  <Tab title="Cursor">
    <Steps>
      <Step title="Open MCP settings">
        1. Use <kbd>Command</kbd> + <kbd>Shift</kbd> + <kbd>P</kbd> (<kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>P</kbd> on Windows) to open the command palette.
        2. Search for "Open MCP settings".
        3. Select **Add custom MCP**. This opens the `mcp.json` file.
      </Step>

      <Step title="Configure the Moca Network MCP server">
        In `mcp.json`, add:

        ```json theme={null}
        {
          "mcpServers": {
            "MocaNetwork": {
              "url": "https://docs.air3.com/mcp"
            }
          }
        }
        ```
      </Step>

      <Step title="Test the connection">
        In Cursor's chat, ask "What tools do you have available?" Cursor should show the MocaNetwork MCP server as an available tool.
      </Step>
    </Steps>

    See the [Cursor documentation](https://docs.cursor.com/en/context/mcp#installing-mcp-servers) for more details.
  </Tab>

  <Tab title="VS Code">
    <Steps>
      <Step title="Create MCP configuration">
        Create a `.vscode/mcp.json` file in your project root.
      </Step>

      <Step title="Configure the Moca Network MCP server">
        In `.vscode/mcp.json`, add:

        ```json theme={null}
        {
          "servers": {
            "MocaNetwork": {
              "type": "http",
              "url": "https://docs.air3.com/mcp"
            }
          }
        }
        ```
      </Step>
    </Steps>

    See the [VS Code documentation](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) for more details.
  </Tab>
</Tabs>

For another MCP-compatible tool, add the URL as a remote HTTP MCP server in its connection settings.

## Try your first prompt

Once connected, ask your agent to look up the docs and help with a specific task:

```text theme={null}
Use the AIR docs MCP server to help me add AIR Kit login to my app.
Check my framework and existing authentication, then explain the setup
and changes before implementing them.
```

You can also ask about credential issuance and verification, wallet transactions, or integration errors. Include your framework and what you have already built.

## Choose your setup

| Option | What it provides | When to use it |
| - | - | - |
| **Docs MCP** | Searchable AIR documentation, SDK guides, and API references. | Start here for current reference material. |
| **AIR skill** | Integration workflows and checks for setup, authentication, and common errors. | Add alongside MCP for guidance while building. |
| **Static docs** | Documentation files you attach or index in your tool. | Use when your tool cannot connect through MCP; refresh the files as docs change. |

Your agent uses these resources to plan, write, and review integration code. Live AIR operations run through your application's configured account, authentication, and programs.

## Add the AIR skill (optional)

For tools that support [Agent Skills](https://agentskills.io/home), run:

```bash theme={null}
npx skills add https://docs.air3.com
```

Select your agent in the CLI to install the skill.

<Accordion title="Before issuing or verifying credentials">
  Ask your agent to confirm these prerequisites before generating application code:

  * Your partner's public JWKS endpoint is reachable over HTTPS.
  * The exact JWKS URL is registered in the Developer Dashboard.
  * Your JWT signing key stays server-side, and its `kid` matches a published JWKS key.

  Follow [JWKS endpoint setup](/get-started/authentication/jwks-endpoint), then use the [issuance](/products/identity/issuing-credentials) or [verification](/products/identity/verify) guide for your flow.
</Accordion>

<Accordion title="Use static documentation files">
  ## Static docs files

  If your AI tool does not support MCP yet, you can use one of Moca Network's static documentation files instead.

  <Warning>
    Static files are snapshots and may not include the latest updates. Use MCP when possible for always-current docs.
  </Warning>

  ## Which file should I use?

  * **`llms.txt`** — A curated overview of Moca Network. Use it to route an agent to the right docs, understand product structure, and choose the right integration path.
  * **`llms-full.txt`** — A full static snapshot of the documentation. Use it when your tool needs more exhaustive reference material in one file.

  ## Setup with Cursor

  <Steps>
    <Step title="Open docs settings">
      Go to **Settings** → **Features** → **Docs**.
    </Step>

    <Step title="Add the overview file">
      Click **Add new doc** and paste: `https://docs.air3.com/llms.txt`
    </Step>

    <Step title="Optionally add the full snapshot">
      If your agent needs deeper static reference coverage, add: `https://docs.air3.com/llms-full.txt`
    </Step>

    <Step title="Reference in chat">
      Use **@docs** → **Moca** in your AI chat to reference the documentation.
    </Step>
  </Steps>

  ## Setup with Claude Desktop

  <Steps>
    <Step title="Download the overview file">
      Download the curated overview from: [https://docs.air3.com/llms.txt](https://docs.air3.com/llms.txt)
    </Step>

    <Step title="Optionally download the full snapshot">
      Download the full documentation snapshot from: [https://docs.air3.com/llms-full.txt](https://docs.air3.com/llms-full.txt)
    </Step>

    <Step title="Add to your project">
      Save one or both files in your project directory or another known location on your system.
    </Step>

    <Step title="Reference in chat">
      Drag and drop the file into your Claude Desktop chat, or use the attachment button to upload it. Claude will then have access to the uploaded Moca Network documentation context for that conversation.
    </Step>
  </Steps>
</Accordion>


# Issuing credentials
Source: https://docs.air3.com/products/identity/issuing-credentials

Issue verifiable credentials with a self-hosted Issuer Backend — the issuer owns source data and signing keys, encrypts to the holder, and stores in DStorage.

As an Issuer, you own your source data and signing keys. You build the credential, sign it with issuer-controlled keys, encrypt it to the holder's public key, and store the encrypted envelope in DStorage. AIR stores opaque ciphertext and metadata — it never handles your plaintext data.

You host a single **Issuer Backend**. The [AIR issuer service](https://github.com/MocaNetwork/air-issuer-service/tree/main) is the reference implementation. Whoever hosts it holds the issuer keys, the data source, and the API keys. There are two issuance paths on that backend:

* **SDK issuance** — the user is present. Your frontend calls `air.issueCredential`; AIR calls your backend's `available-vc` and `issue-vc` endpoints.
* **Direct issuance** — no user interaction with AIR. Your backend resolves the holder by email and issues the credential itself.

<Info>
  **Credential format**

  New issuance programs use the `SD_JWT_VC` signature type. SD-JWT issuance is self-serve in sandbox and production. Iden3 (`BJJ_SIG_2021`) credentials are an advanced option that the AIR team enables; see [Credential formats](/products/identity/credential-formats) and [Iden3 credentials](/products/identity/iden3-credentials).
</Info>

## Dashboard setup

Credential services are gated. When you first sign up, the **Issuer and Verifier menus (schemas, programs, and DID settings) stay hidden** until your Issuer DID is registered.

Sandbox and production use separate Dashboards, and both are self-serve for SD-JWT issuers:

* **Sandbox:** [developers.sandbox.air3.com](https://developers.sandbox.air3.com/dashboard)
* **Production:** [developers.air3.com](https://developers.air3.com/dashboard)

In the Dashboard for your target environment:

1. Deploy the SD-JWT branch of the [AIR issuer service](https://github.com/MocaNetwork/air-issuer-service/tree/main) at a stable public HTTPS origin. Your Issuer DID is `did:web:<host of ISSUER_ORIGIN>`; the service publishes it at `/.well-known/did.json`. See [Issuer backend hosting](/products/identity/backend-hosting).
2. Open **Issuer → Settings** and register the issuer:
   * Issuer DID (`did:web:…`) and the issuer **API key**
   * Supported signature type: `SD_JWT_VC`
   * JWKS URL for your partner keys
   * `availableVcApiUrl`, `issueVcApiUrl`, and `revocationStatusApiUrl`, pointing at `POST /available-vc`, `POST /issue-vc`, and `GET /revocation-status/:nonce` on your backend
3. Select or create a schema, then create an issuance program.

<Warning>
  Treat the issuer host as permanent once you issue your first credential. The host is part of the `did:web` Issuer DID, so changing it changes your issuer identity, and credentials issued under the old host no longer resolve to you.
</Warning>

> **Important**: Sandbox and production are separate environments. Configuration created in sandbox does not carry over. Register the issuer, schemas, and programs again in the production Dashboard.

To issue Iden3 credentials, contact the AIR team; see [Iden3 credentials](/products/identity/iden3-credentials).

## Technical integration

| Capability | Endpoint | Notes |
| - | - | - |
| Initialize / resolve user | `POST /auth/initialize-user` | Partner-authenticated call using the user identifier (typically email). Returns the user DID and public key, creating or resolving the AIR account as needed. Used for on-demand issuance when the user has no active session. |
| Store encrypted VC | `POST /dstorage/vcs` | Stores the issuer-signed, holder-encrypted VC envelope in DStorage. Returns a DStorage path / storage reference. Called by your backend as part of `issue-vc`. |
| Available credentials | `POST /available-vc` (issuer-hosted) | AIR calls it during SDK issuance. Your backend lists eligible credentials for the holder and returns encrypted previews. |
| Issue credential | `POST /issue-vc` (issuer-hosted) | AIR calls it after the holder confirms. Your backend builds, signs, encrypts, and stores the credential. |
| Direct issuance | `POST /admin/issue-vc` (issuer-hosted) | Your own servers call it to issue without a user session. Protected by `x-admin-api-key`. |
| Revoke | `POST /admin/revoke` (issuer-hosted) | Your own servers call it to revoke. See [Revoke credentials](/products/identity/revocation). |

The first two rows are AIR API endpoints. Every row marked issuer-hosted runs on your issuer service at `ISSUER_ORIGIN`.

See [Issuance API Reference](/api-reference/issuance-api) for request and response details.

## Configure the backend

Set up your issuer backend / environment with:

* A stable public `ISSUER_ORIGIN` (it defines your `did:web` Issuer DID) and partner signing keys
* Schema and program configuration
* API keys / partner auth
* DStorage endpoint configuration
* Issuer data source connection
* A generated **private API key** (`API_KEY`) that protects your issuer-hosted endpoints via the `x-api-key` header
* A separate **admin API key** (`ADMIN_API_KEY`) for the `/admin/*` routes your own servers call

### Expose `available-vc`

Your backend exposes `POST /available-vc` and accepts the holder identity:

```json theme={null}
{
  "holderDID": "did:air:...",
  "pubKey": "0x...",
  "userId": "<partner primary identifier>",
  "schemaId": "<optional schema filter>",
  "proofType": "SD_JWT_VC"
}
```

* Retrieves the user's eligible credential data from your data source.
* Returns `{ data: [...] }`, with each credential subject encrypted to the holder's `pubKey`.
* Accepts optional `schemaId` and `proofType` filters.

### Expose `issue-vc`

Your backend exposes `POST /issue-vc` with the same `holderDID`, `pubKey`, and `userId`, plus the required `schemaId`, optional `proofType`, and the holder's `signingKey`:

* Retrieves the final user data.
* Builds the SD-JWT VC and signs it with issuer-controlled keys. When AIR sends `signingKey.jwk`, it becomes the credential's `cnf` claim, binding the credential to the holder.
* Encrypts the VC to the user's public key.
* Stores the encrypted VC via DStorage.
* Returns an empty response body after successful issuance. The issuer backend stores the DStorage response in its issuance record.

Both endpoints require `x-api-key: <issuerBackendApiKey>`. Use `userId`—not `holderDID` alone—to retrieve partner-owned eligibility and claim data.

## SDK issuance

Use this path when the user is present in your app and should confirm issuance through AIR Kit.

1. Your frontend calls `air.issueCredential` with the Partner JWT, issuer DID, and program ID, passing `{}` as `credentialSubject`.
2. AIR logs the user in if needed and calls your backend's `POST /available-vc`. Your backend returns encrypted previews of the credentials the holder can claim.
3. The holder reviews the preview and confirms.
4. AIR calls your backend's `POST /issue-vc`. Your backend builds, signs, encrypts, and stores the credential, and stays authoritative over the claims.

```mermaid theme={null}
sequenceDiagram
    autonumber
    actor Holder
    participant App as Your frontend
    participant SDK as AIR Kit
    participant AIR as AIR API
    participant Backend as Your issuer backend
    Holder->>App: Start issuance
    App->>SDK: air.issueCredential({ credentialSubject: {} })
    SDK->>AIR: Request available credentials
    AIR->>Backend: POST /available-vc
    Backend-->>AIR: Encrypted previews
    AIR-->>SDK: Previews
    Holder->>SDK: Confirm issuance
    SDK->>AIR: Issue
    AIR->>Backend: POST /issue-vc
    Backend-->>AIR: 201
    SDK-->>App: Issuance complete
```

The user's raw data never leaves your control in plaintext. Previews are encrypted to the holder, and the browser never sees your issuer API key.

### Waiting for issuance to complete

By default, `issueCredential` resolves once the credential has been issued and stored, without waiting for its on-chain record (hashes and status metadata, not the credential itself) to be confirmed. Pass `waitForOnchainCompletion: true` when your next step depends on that record already being confirmed:

```jsx theme={null}
await airService.issueCredential({
  authToken,
  issuerDid,
  credentialId,
  credentialSubject,
  waitForOnchainCompletion: true,
});
```

| Value | Behavior |
| - | - |
| `false` (default) | Resolves as soon as issuance completes. The on-chain record may still be pending, so an immediate verification can fail. |
| `true` | Polls until the on-chain record is confirmed before resolving. Rejects if confirmation fails or times out. |

Use `true` when you verify right after issuing, or when you show the user a confirmed state. Keep the default when issuance is a background step and the user does not wait on it — confirmation adds latency proportional to block time.

<Note>
  `waitForOnchainCompletion` replaced the earlier `offchain` parameter. Whether a program writes on-chain at all is configured on the program in the Developer Dashboard, not on the call.
</Note>

## Direct issuance

Use this path when a **backend event** should issue a credential with no user interaction with AIR — the end user does not need to be in a session, open a wallet, or interact with any UI. Your backend does the full issuance job.

Typical triggers:

* Issuing a KYC credential the moment a user passes identity verification
* Issuing an attendance credential when a venue scan detects a fan's check-in
* Issuing a subscriber tier credential at the end of each billing cycle
* Issuing a loyalty credential triggered by a purchase event

### How it works

The SD-JWT issuer service exposes `POST /admin/issue-vc` for this path. It runs on your issuer service, not on the AIR API, and only your own servers should call it.

1. A backend event fires — KYC passed, purchase confirmed, check-in scanned — or your batch job begins.
2. Your server calls `POST {ISSUER_ORIGIN}/admin/issue-vc` with the `x-admin-api-key` header.
3. The issuer service calls AIR `POST /auth/initialize-user` with the recipient's email to resolve or create their AIR Account, receiving the holder DID and public key.
4. It signs the SD-JWT VC, encrypts it to the holder's public key, and stores it through `POST /dstorage/vcs`.
5. The user presents the credential later to any AIR verifier; no action needed at issuance time.

```bash theme={null}
curl -X POST "$ISSUER_ORIGIN/admin/issue-vc" \
  -H "x-admin-api-key: $ADMIN_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "userId": "member@example.com",
    "schemaId": "<SCHEMA_ID>",
    "vct": "<SCHEMA_ID>",
    "expiration": "2030-01-01T00:00:00Z",
    "credentialSubject": { "tier": "Gold" },
    "disclosureFrame": { "_sd": ["tier"] }
  }'
```

* `userId` must be the email AIR knows the user by.
* `expiration` is an ISO 8601 date in the future.
* `credentialSubject` must not contain reserved claims: `cnf`, `exp`, `iat`, `id`, `iss`, `nonce`, `status`, `sub`, `vct`, `vct#integrity`.
* `disclosureFrame` is optional. By default every top-level claim is selectively disclosable.
* No registered schema class is needed.

<Note>
  Directly issued credentials carry no `cnf` holder key, because the holder is not present to provide one. Their presentations cannot include a key-binding JWT, so verifiers receive bearer presentations. Use SDK issuance when you need holder binding. See [Verify SD-JWT on your backend](/products/identity/verify-sd-jwt).
</Note>

Issuance is recorded in `GET /admin/issuance-history` and revoked the same way as claimed credentials.

```mermaid theme={null}
sequenceDiagram
    autonumber
    participant Event as Backend event
    participant Backend as Your issuer service
    participant AIR as AIR API
    participant DS as DStorage
    Event->>Backend: POST /admin/issue-vc
    Backend->>AIR: POST /auth/initialize-user { email }
    AIR-->>Backend: { did, publicKey }
    Backend->>Backend: Build, sign, encrypt SD-JWT VC
    Backend->>DS: POST /dstorage/vcs
    DS-->>Backend: 201 { storagePath }
```

### Prerequisites

1. **Credential services enabled** — Register your `did:web` Issuer DID in **Issuer → Settings** to unlock issuer functionality.
2. **Partner ID and Issuer DID** — Partner ID from the Developer Dashboard (Accounts → General). Your Issuer DID comes from your issuer host; AIR does not generate it for you.
3. **Issuance program** — A published credential program in the dashboard (Issuer → Programs).
4. **JWKS endpoint** — A public URL serving your public key for JWT verification. See [SDK authentication](/get-started/authentication/sdk-auth).

## View issued credential records

You can review the records of every credential you have issued in the <a href="https://developers.sandbox.air3.com/dashboard">Developer Dashboard</a> by going to **Issuer -> Usage Records**.

<Frame>
  <img alt="Issued credential records on the Usage Records page" />
</Frame>

## Best practices for issuers (SDK)

* Only issue credentials after thorough validation of submitted evidence or claims.
* Keep source data and signing keys under issuer control; never expose plaintext user data to AIR.
* Minimize personally identifiable information — issue privacy-preserving credentials whenever possible.
* Adopt open, standardized schemas to maximize compatibility across apps.
* Implement robust expiry and [revocation](/products/identity/revocation) processes, and keep holders and verifiers informed of credential status.
* Treat bulk imports as an operational process for large backfills, not the default integration path.

## Next steps

* [Issuance API Reference](/api-reference/issuance-api)
* [Revoke credentials](/products/identity/revocation)
* [Verifying Credentials](/products/identity/verify)
* [Quickstart: Issue Credentials](/get-started/quickstarts/issue-credentials)


# Managing your credentials
Source: https://docs.air3.com/products/identity/revocation

Revoke SD-JWT credentials from your issuer service, serve per-credential revocation status, and optionally publish an IETF Token Status List.

<Info>
  Every route on this page runs on **your issuer service** at `{ISSUER_ORIGIN}`, not on the AIR API. The examples follow the SD-JWT branch of the [AIR issuer service](https://github.com/MocaNetwork/air-issuer-service/tree/main). Revocation needs a database (the reference issuer service uses PostgreSQL); see [Issuer backend hosting](/products/identity/backend-hosting).
</Info>

Revoking a credential is one-way. Once revoked, verifiers that check status reject it. Handle deletion of your own source records separately under your retention policy.

## Routes

| Method | Path | Called by | Auth |
| - | - | - | - |
| `GET` | `/admin/issuance-history` | Your servers | `x-admin-api-key` |
| `POST` | `/admin/revoke` | Your servers | `x-admin-api-key` |
| `POST` | `/admin/publish-token-status-list` | Your servers, when the status list is enabled | `x-admin-api-key` |
| `GET` | `/revocation-status/:nonce` | Verifiers and AIR | None |
| `GET` | `/statuslist/:partition` | Verifiers, when the status list is enabled | None |

Keep `ADMIN_API_KEY` on your servers. Never call admin routes from a browser.

## Revoke a credential

<Steps>
  <Step title="Find the revocation nonce">
    Each issued credential has a `revocationNonce`. Look it up in the issuance history, filtered by holder or schema:

    ```bash theme={null}
    curl -s \
      -H "x-admin-api-key: $ADMIN_API_KEY" \
      "$ISSUER_ORIGIN/admin/issuance-history?holderDid=did:air:...&schemaId=<SCHEMA_ID>" \
      | jq .
    ```
  </Step>

  <Step title="Revoke it">
    ```bash theme={null}
    curl -X POST "$ISSUER_ORIGIN/admin/revoke" \
      -H "x-admin-api-key: $ADMIN_API_KEY" \
      -H "content-type: application/json" \
      -d '{"nonce":"<revocationNonce>"}'
    ```

    The credential is marked revoked in your database immediately.
  </Step>

  <Step title="Confirm the status">
    ```bash theme={null}
    curl "$ISSUER_ORIGIN/revocation-status/<revocationNonce>"
    ```

    ```json theme={null}
    { "isRevoked": true }
    ```
  </Step>
</Steps>

`GET /revocation-status/:nonce` reflects a revocation as soon as you make it. Register this route with AIR as `revocationStatusApiUrl` so verification programs that enable issuer revocation checks can use it.

To change a credential, such as a tier upgrade, revoke the old one and issue a new one.

## Token status list

The token status list is optional and off by default. It publishes revocation as one compressed bit array per partition, following the [IETF Token Status List](https://datatracker.ietf.org/doc/draft-ietf-oauth-status-list/) draft. Verifiers download a whole partition, so the issuer never learns which credential they checked, and they can cache the list. Revocation works without it; the status list improves privacy and caching.

Each credential issued with the list enabled carries a pointer to its bit:

```json theme={null}
{
  "status": {
    "status_list": {
      "idx": 12345,
      "uri": "https://issuer.example.com/statuslist/0"
    }
  }
}
```

A verifier fetches `uri`, decompresses the list, and reads the bit at `idx`: `0` is valid, `1` is revoked. The partition is served as a JWT (`application/statuslist+jwt`) signed with your partner key, and verifiers resolve the key from `/.well-known/jwt-vc-issuer`.

### Enable it

1. Apply migrations so the status list table exists (`npx mikro-orm migration:up`).
2. Set `SD_JWT_TSL_PARTITION_SIZE` to the number of credentials each partition covers. Use a multiple of 8.
3. Make sure `ISSUER_ORIGIN` is your stable public origin. It is written into the `uri` of every credential issued from then on.

<Warning>
  The partition size cannot be changed once you start issuing. `idx` and `uri` are embedded in credentials already in holders' accounts, so changing the size points them at the wrong bits. Pick it with room to grow.
</Warning>

Credentials issued before you enable the list have no `status` claim and keep relying on `GET /revocation-status/:nonce`.

### Choose a partition size

* **Larger partitions** give better privacy, because the anonymity set is everyone in the partition. They also mean fewer URLs to publish and cache, and they compress well. Every verifier downloads the whole partition to check one credential.
* **Smaller partitions** keep each download small, but narrow the anonymity set and slow down publishing as the partition count grows.

Aim for a handful of partitions over the lifetime of your credentials, not hundreds. For reference, 80,000 bits is 10 KB uncompressed and typically a few hundred bytes compressed when few credentials are revoked. If your credentials are short-lived, a size that covers about one credential lifetime of issuance works well.

### Publish

Revoking a credential does not change the published list. Publish to rebuild every partition from your database:

```bash theme={null}
curl -X POST "$ISSUER_ORIGIN/admin/publish-token-status-list" \
  -H "x-admin-api-key: $ADMIN_API_KEY"
```

Batch revocations and publish on a schedule that matches how fast revocation must take effect:

| Situation | Suggested cadence |
| - | - |
| Urgent revocation (fraud, account compromise, access credentials) | Every few minutes, or right after a revocation batch |
| Routine revocation (membership lapses, tier changes) | Hourly or nightly |
| Short-lived credentials | Daily; expiry already does most of the work |

Tell your verifiers that revocation takes up to your publish interval plus their cache time to reach them.

### Serve the list

`GET /statuslist/:partition` needs no API key. It returns `501 Not Implemented` when the status list is disabled, and `404` for a partition that has never been published. Responses are signed per request, so put the route behind a CDN or reverse-proxy cache, with a TTL no longer than your publish interval.

### Limitations

* Only valid and revoked are represented. Suspension is not supported.
* Publishing rebuilds all partitions and must not run concurrently with itself. Run it from a single scheduler.
* The status list JWT has no `exp` or `ttl` claim, so verifiers apply their own cache policy.
* There is no way to un-revoke a credential.

## Iden3 credentials

The Iden3 issuer service has `/admin/revoke` and `/revocation-status/:nonce` too, plus `/credential-status/:nonce` for non-revocation proofs. It has no token status list. See [Iden3 credentials](/products/identity/iden3-credentials).

## Related

* [Verify SD-JWT on your backend](/products/identity/verify-sd-jwt#revocation)
* [Issuance API reference](/api-reference/issuance-api)
* [Issuer backend hosting](/products/identity/backend-hosting)


# Creating your first schema
Source: https://docs.air3.com/products/identity/schema-creation

Create and publish AIR Kit credential schemas using the Schema Builder — define fields, types, and validation rules without code.

Credential schemas are the foundation of your credential issuance system. This guide will help you understand, create, and manage schemas effectively for your AIR Kit applications.

## Creating schemas with the Schema Builder

The AIR Kit Schema Builder provides an intuitive interface for creating credential schemas without requiring technical knowledge of JSON schema structures.

### Step 1: Access the Schema Builder

1. Go to the [Developer Dashboard](https://developers.sandbox.air3.com/dashboard/issuer/schemas)
2. Navigate to the **Schemas** section under **Issuer**
   <img alt="Create Schema" />

### Step 2: Create a new schema

1. Click **"Create New Schema"**
2. Fill in the basic schema information:
   * **Title**: Choose a descriptive name for your schema
   * **Type**: Select or enter a category for your credential type
   * **Description**: Provide a clear explanation of what this schema represents

### Step 3: Define attributes

1. Click **"+"** to add attributes
2. For each attribute, specify:
   * **Name**: Field identifier (use camelCase)
   * **Type**: Choose from String, Number, Boolean, or Date
   * **Description**: Explain what this field represents
   * **Required**: Mark if the field is mandatory

### Step 4: Publish your schema

1. Review your schema structure
2. Click **"Publish"** to make it available for credential creation
3. Note the schema ID for use in your applications

<div>
  <img alt="Create schema" />
</div>

## Schema Builder best practices

### 1. Choose descriptive names

* Use clear, descriptive names for your schema title and attributes
* Avoid abbreviations that might be unclear to other developers
* Example: `"memberId"` instead of `"mem_id"`

### 2. Provide clear descriptions

* Write detailed descriptions for each attribute
* Explain the purpose and expected format of each field
* Include any validation rules or constraints

### 3. Use appropriate data types

* **String**: For text data, IDs, names, descriptions
* **Number**: For numeric values, ages, quantities, scores
* **Boolean**: For true/false values, flags, status indicators
* **Date**: For timestamps, expiry dates, event dates

### 4. Consider privacy requirements

* Only include fields that are necessary for your use case
* Remember that users can selectively disclose fields
* Avoid collecting sensitive data unless absolutely required

### 5. Plan for future updates

* Consider how your schema might evolve over time
* Use versioning to manage schema changes
* Design attributes to be extensible


# Managing your schemas
Source: https://docs.air3.com/products/identity/schema-management

Evolve AIR Credential schemas safely with backward-compatible versioning — strategies for adding fields, deprecation, and migrating existing credentials.

As your application evolves, you may need to update your credential schemas. Understanding how to manage schema changes is crucial for maintaining compatibility and ensuring smooth operations.

### Schema versioning strategy

When you need to modify a schema, consider these approaches:

#### Backward-compatible changes

These changes don't break existing credentials:

* Adding new optional attributes
* Updating descriptions or metadata
* Adding new schema versions

#### Breaking changes

These changes require careful planning:

* Removing attributes
* Changing attribute data types
* Making optional attributes required
* Renaming attributes

### Best practices for schema evolution

#### 1. Plan for growth

**JSON-LD Context v1.0:**

```json theme={null}
{
  "@context": [
    {
      "@version": 1.1,
      "@protected": true,
      "id": "@id",
      "type": "@type",
      "UserProfileCredential": {
        "@id": "https://your-domain.com/schemas/user-profile-v1.0.json-ld#UserProfileCredential",
        "@context": {
          "@version": 1.1,
          "@protected": true,
          "id": "@id",
          "type": "@type",
          "vocab": "https://your-domain.com/vocab/user-profile/v1.0#",
          "xsd": "http://www.w3.org/2001/XMLSchema#",
          "firstName": {
            "@id": "vocab:firstName",
            "@type": "xsd:string"
          },
          "lastName": {
            "@id": "vocab:lastName",
            "@type": "xsd:string"
          },
          "email": {
            "@id": "vocab:email",
            "@type": "xsd:string"
          }
        }
      }
    }
  ]
}
```

#### 2. Add new fields gradually

**JSON-LD Context v1.1:**

```json theme={null}
{
  "@context": [
    {
      "@version": 1.1,
      "@protected": true,
      "id": "@id",
      "type": "@type",
      "UserProfileCredential": {
        "@id": "https://your-domain.com/schemas/user-profile-v1.1.json-ld#UserProfileCredential",
        "@context": {
          "@version": 1.1,
          "@protected": true,
          "id": "@id",
          "type": "@type",
          "vocab": "https://your-domain.com/vocab/user-profile/v1.1#",
          "xsd": "http://www.w3.org/2001/XMLSchema#",
          "firstName": {
            "@id": "vocab:firstName",
            "@type": "xsd:string"
          },
          "lastName": {
            "@id": "vocab:lastName",
            "@type": "xsd:string"
          },
          "email": {
            "@id": "vocab:email",
            "@type": "xsd:string"
          },
          "phoneNumber": {
            "@id": "vocab:phoneNumber",
            "@type": "xsd:string"
          }
        }
      }
    }
  ]
}
```

#### 3. Deprecate fields carefully

**JSON-LD Context v2.0:**

```json theme={null}
{
  "@context": [
    {
      "@version": 1.1,
      "@protected": true,
      "id": "@id",
      "type": "@type",
      "UserProfileCredential": {
        "@id": "https://your-domain.com/schemas/user-profile-v2.0.json-ld#UserProfileCredential",
        "@context": {
          "@version": 1.1,
          "@protected": true,
          "id": "@id",
          "type": "@type",
          "vocab": "https://your-domain.com/vocab/user-profile/v2.0#",
          "xsd": "http://www.w3.org/2001/XMLSchema#",
          "firstName": {
            "@id": "vocab:firstName",
            "@type": "xsd:string"
          },
          "lastName": {
            "@id": "vocab:lastName",
            "@type": "xsd:string"
          },
          "email": {
            "@id": "vocab:email",
            "@type": "xsd:string"
          },
          "phoneNumber": {
            "@id": "vocab:phoneNumber",
            "@type": "xsd:string"
          },
          "fullName": {
            "@id": "vocab:fullName",
            "@type": "xsd:string"
          }
        }
      }
    }
  ]
}
```

### Managing schema updates in production

#### 1. Gradual migration strategy

* Keep old schemas active during transition periods
* Issue new credentials with updated schemas
* Gradually phase out old schema versions
* Monitor credential usage patterns

#### 2. Communication with users

* Notify users about schema changes
* Provide migration guides for credential holders
* Maintain backward compatibility for verification

#### 3. Testing schema changes

* Test new schemas in development environment
* Validate credential issuance with new schemas
* Ensure verification still works with old credentials
* Test selective disclosure with updated schemas

## Schema registry and discovery

The AIR Kit provides a schema registry where you can:

* **Browse Available Schemas**: Discover schemas created by other developers
* **Reuse Existing Schemas**: Use well-established schemas for common use cases
* **Contribute Schemas**: Share your schemas with the community

## Next steps

Now that you understand schema creation and JSON-LD implementation, you can:

* **Issue Credentials** - Use your schemas to issue credentials in the [Credential Issuance Quickstart](/get-started/quickstarts/issue-credentials)
* **Verify Credentials** - Learn how to verify credentials in the [Credential Verification Quickstart](/get-started/quickstarts/verify-credentials)
* **Explore Schema Registry** - Browse and reuse existing schemas in the [Developer Dashboard](https://developers.sandbox.air3.com/dashboard/issuer/schemas)
* **Advanced Schema Design** - Learn about complex schema patterns and advanced use cases


# What are schemas
Source: https://docs.air3.com/products/identity/schema-overview

How AIR Credential schemas work — JSON Schema structure, JSON-LD context, field types, and validation rules that define a credential template.

A **credential schema** is a blueprint that defines the structure, data types, and validation rules for the credentials you want to issue. Think of it as a template that ensures all credentials of a particular type have consistent fields and data formats.

Schemas serve several critical purposes:

* **Data Consistency**: Ensures all credentials of the same type have identical field structures
* **Validation**: Defines data types and constraints for each field
* **Interoperability**: Allows different systems to understand and process your credentials
* **Privacy**: Enables selective disclosure of specific fields within a credential

<Note>
  **SD-JWT and Iden3 use schemas differently.** For SD-JWT VC credentials, the default format, the schema defines the claim names and types, and the schema ID becomes the credential type (`vct`) unless your issuer sets its own. Which claims are selectively disclosable is set by the issuer's `disclosureFrame`. The JSON-LD context and `$metadata` described below apply to [Iden3 credentials](/products/identity/iden3-credentials).
</Note>

## Schema components

A Schema Type encodes the structure of a particular Verifiable Credential (VC) by defining the type, the fields that must be included inside the VC, and a description for these fields.

Schemas let different services interpret the same credential consistently. A verifier that knows the schema can read the credential's claims without contacting the issuer.

A schema type is made of **two separate documents**:

### 1. JSON-LD context

The JSON-LD Context contains a description of the type and its fields, providing semantic meaning to your credential data by linking it to standardized vocabularies and ontologies.

#### Understanding JSON-LD context

JSON-LD context defines the vocabulary and data types used in your credentials. It maps local field names to globally unique identifiers (URIs) that have well-defined meanings.

Here's an example of a JSON-LD Context for a `MembershipPointsCredential`:

```json theme={null}
{
  "@context": [
    {
      "@version": 1.1,
      "@protected": true,
      "id": "@id",
      "type": "@type",
      "MembershipPointsCredential": {
        "@id": "https://your-domain.com/schemas/membership-points.json-ld#MembershipPointsCredential",
        "@context": {
          "@version": 1.1,
          "@protected": true,
          "id": "@id",
          "type": "@type",
          "vocab": "https://your-domain.com/vocab/membership-points#",
          "xsd": "http://www.w3.org/2001/XMLSchema#",
          "memberId": {
            "@id": "vocab:memberId",
            "@type": "xsd:string"
          },
          "totalPoints": {
            "@id": "vocab:totalPoints",
            "@type": "xsd:integer"
          },
          "tier": {
            "@id": "vocab:tier",
            "@type": "xsd:string"
          },
          "lastUpdated": {
            "@id": "vocab:lastUpdated",
            "@type": "xsd:dateTime"
          }
        }
      }
    }
  ]
}
```

#### Key JSON-LD context elements

* **@version**: Specifies the JSON-LD version (typically 1.1)
* **@protected**: Ensures that terms cannot be overridden
* **@id**: Maps to globally unique identifiers
* **@type**: Specifies the data type using XML Schema types
* **vocab**: Custom vocabulary namespace for your specific fields
* **xsd**: XML Schema Definition namespace for standard data types

### 2. JSON Schema

The JSON Schema contains the validation rules for the Issuer Node, defining the structure and constraints for the credential data.

Here's an example of a JSON Schema for the `MembershipPointsCredential`:

```json theme={null}
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "$metadata": {
    "uris": {
      "jsonLdContext": "https://your-domain.com/schemas/membership-points.json-ld",
      "jsonSchema": "https://your-domain.com/schemas/membership-points.json"
    }
  },
  "required": [
    "@context",
    "id",
    "type",
    "issuanceDate",
    "credentialSubject",
    "credentialSchema",
    "credentialStatus",
    "issuer"
  ],
  "properties": {
    "@context": {
      "type": ["string", "array", "object"]
    },
    "id": {
      "type": "string"
    },
    "type": {
      "type": ["string", "array"],
      "items": {
        "type": "string"
      }
    },
    "issuer": {
      "type": ["string", "object"],
      "format": "uri",
      "required": ["id"],
      "properties": {
        "id": {
          "type": "string",
          "format": "uri"
        }
      }
    },
    "issuanceDate": {
      "type": "string",
      "format": "date-time"
    },
    "expirationDate": {
      "type": "string",
      "format": "date-time"
    },
    "credentialSchema": {
      "type": "object",
      "required": ["id", "type"],
      "properties": {
        "id": {
          "type": "string",
          "format": "uri"
        },
        "type": {
          "type": "string"
        }
      }
    },
    "credentialSubject": {
      "type": "object",
      "required": ["id", "memberId", "totalPoints", "tier"],
      "properties": {
        "id": {
          "title": "Credential Subject ID",
          "type": "string",
          "format": "uri"
        },
        "memberId": {
          "title": "Member ID",
          "type": "string",
          "description": "Unique member identifier"
        },
        "totalPoints": {
          "title": "Total Points",
          "type": "integer",
          "description": "Total accumulated membership points",
          "minimum": 0
        },
        "tier": {
          "title": "Membership Tier",
          "type": "string",
          "description": "Current membership tier based on points",
          "enum": ["bronze", "silver", "gold", "platinum"]
        },
        "lastUpdated": {
          "title": "Last Updated",
          "type": "string",
          "format": "date-time",
          "description": "When points were last updated"
        }
      }
    }
  }
}
```

#### Key JSON Schema elements

* **\$metadata**: Contains URIs linking to both the JSON-LD context and JSON schema
* **required**: Lists all mandatory fields for the credential
* **properties**: Defines the structure and validation rules for each field
* **credentialSubject**: Contains the actual credential data fields
* **format**: Specifies validation formats (uri, date-time, etc.)

#### Benefits of this two-document approach

1. **Separation of Concerns**: JSON-LD handles semantics, JSON Schema handles validation
2. **Interoperability**: Different systems can understand credentials using standard vocabularies
3. **Validation**: Issuer nodes can validate credential structure before issuance
4. **Flexibility**: Allows for complex validation rules while maintaining semantic clarity


# Schema Use Cases
Source: https://docs.air3.com/products/identity/schema-use-cases

Reference examples of AIR Credential schemas for membership points, KYC, loyalty tiers, event tickets, and other common vertical use cases.

Here are some popular schema types you might create:

### Membership points schema

A comprehensive example showing how to create a schema for tracking membership points and tiers.

#### JSON-LD context

```json theme={null}
{
  "@context": [
    {
      "@version": 1.1,
      "@protected": true,
      "id": "@id",
      "type": "@type",
      "MembershipPointsCredential": {
        "@id": "https://your-domain.com/schemas/membership-points.json-ld#MembershipPointsCredential",
        "@context": {
          "@version": 1.1,
          "@protected": true,
          "id": "@id",
          "type": "@type",
          "vocab": "https://your-domain.com/vocab/membership-points#",
          "xsd": "http://www.w3.org/2001/XMLSchema#",
          "memberId": {
            "@id": "vocab:memberId",
            "@type": "xsd:string"
          },
          "totalPoints": {
            "@id": "vocab:totalPoints",
            "@type": "xsd:integer"
          },
          "tier": {
            "@id": "vocab:tier",
            "@type": "xsd:string"
          },
          "lastUpdated": {
            "@id": "vocab:lastUpdated",
            "@type": "xsd:dateTime"
          }
        }
      }
    }
  ]
}
```

#### JSON Schema

```json theme={null}
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "$metadata": {
    "uris": {
      "jsonLdContext": "https://your-domain.com/schemas/membership-points.json-ld",
      "jsonSchema": "https://your-domain.com/schemas/membership-points.json"
    }
  },
  "required": [
    "@context",
    "id",
    "type",
    "issuanceDate",
    "credentialSubject",
    "credentialSchema",
    "credentialStatus",
    "issuer"
  ],
  "properties": {
    "@context": {
      "type": ["string", "array", "object"]
    },
    "id": {
      "type": "string"
    },
    "type": {
      "type": ["string", "array"],
      "items": {
        "type": "string"
      }
    },
    "issuer": {
      "type": ["string", "object"],
      "format": "uri",
      "required": ["id"],
      "properties": {
        "id": {
          "type": "string",
          "format": "uri"
        }
      }
    },
    "issuanceDate": {
      "type": "string",
      "format": "date-time"
    },
    "expirationDate": {
      "type": "string",
      "format": "date-time"
    },
    "credentialSchema": {
      "type": "object",
      "required": ["id", "type"],
      "properties": {
        "id": {
          "type": "string",
          "format": "uri"
        },
        "type": {
          "type": "string"
        }
      }
    },
    "credentialSubject": {
      "type": "object",
      "required": ["id", "memberId", "totalPoints", "tier"],
      "properties": {
        "id": {
          "title": "Credential Subject ID",
          "type": "string",
          "format": "uri"
        },
        "memberId": {
          "title": "Member ID",
          "type": "string",
          "description": "Unique member identifier"
        },
        "totalPoints": {
          "title": "Total Points",
          "type": "integer",
          "description": "Total accumulated membership points",
          "minimum": 0
        },
        "tier": {
          "title": "Membership Tier",
          "type": "string",
          "description": "Current membership tier based on points",
          "enum": ["bronze", "silver", "gold", "platinum"]
        },
        "lastUpdated": {
          "title": "Last Updated",
          "type": "string",
          "format": "date-time",
          "description": "When points were last updated"
        }
      }
    }
  }
}
```

### Age verification schema

#### JSON-LD context

```json theme={null}
{
  "@context": [
    {
      "@version": 1.1,
      "@protected": true,
      "id": "@id",
      "type": "@type",
      "AgeVerificationCredential": {
        "@id": "https://your-domain.com/schemas/age-verification.json-ld#AgeVerificationCredential",
        "@context": {
          "@version": 1.1,
          "@protected": true,
          "id": "@id",
          "type": "@type",
          "vocab": "https://your-domain.com/vocab/age-verification#",
          "xsd": "http://www.w3.org/2001/XMLSchema#",
          "age": {
            "@id": "vocab:age",
            "@type": "xsd:integer"
          },
          "dateOfBirth": {
            "@id": "vocab:dateOfBirth",
            "@type": "xsd:date"
          },
          "jurisdiction": {
            "@id": "vocab:jurisdiction",
            "@type": "xsd:string"
          }
        }
      }
    }
  ]
}
```

#### JSON Schema

```json theme={null}
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "$metadata": {
    "uris": {
      "jsonLdContext": "https://your-domain.com/schemas/age-verification.json-ld",
      "jsonSchema": "https://your-domain.com/schemas/age-verification.json"
    }
  },
  "required": [
    "@context",
    "id",
    "type",
    "issuanceDate",
    "credentialSubject",
    "credentialSchema",
    "credentialStatus",
    "issuer"
  ],
  "properties": {
    "@context": {
      "type": ["string", "array", "object"]
    },
    "id": {
      "type": "string"
    },
    "type": {
      "type": ["string", "array"],
      "items": {
        "type": "string"
      }
    },
    "issuer": {
      "type": ["string", "object"],
      "format": "uri",
      "required": ["id"],
      "properties": {
        "id": {
          "type": "string",
          "format": "uri"
        }
      }
    },
    "issuanceDate": {
      "type": "string",
      "format": "date-time"
    },
    "expirationDate": {
      "type": "string",
      "format": "date-time"
    },
    "credentialSchema": {
      "type": "object",
      "required": ["id", "type"],
      "properties": {
        "id": {
          "type": "string",
          "format": "uri"
        },
        "type": {
          "type": "string"
        }
      }
    },
    "credentialSubject": {
      "type": "object",
      "required": ["id", "age", "dateOfBirth", "jurisdiction"],
      "properties": {
        "id": {
          "title": "Credential Subject ID",
          "type": "string",
          "format": "uri"
        },
        "age": {
          "title": "Age",
          "type": "integer",
          "description": "User's age in years",
          "minimum": 0,
          "maximum": 150
        },
        "dateOfBirth": {
          "title": "Date of Birth",
          "type": "string",
          "format": "date",
          "description": "User's date of birth"
        },
        "jurisdiction": {
          "title": "Jurisdiction",
          "type": "string",
          "description": "Legal jurisdiction for age verification"
        }
      }
    }
  }
}
```

### Event pass schema

#### JSON-LD context

```json theme={null}
{
  "@context": [
    {
      "@version": 1.1,
      "@protected": true,
      "id": "@id",
      "type": "@type",
      "EventPassCredential": {
        "@id": "https://your-domain.com/schemas/event-pass.json-ld#EventPassCredential",
        "@context": {
          "@version": 1.1,
          "@protected": true,
          "id": "@id",
          "type": "@type",
          "vocab": "https://your-domain.com/vocab/event-pass#",
          "xsd": "http://www.w3.org/2001/XMLSchema#",
          "eventName": {
            "@id": "vocab:eventName",
            "@type": "xsd:string"
          },
          "eventDate": {
            "@id": "vocab:eventDate",
            "@type": "xsd:dateTime"
          },
          "ticketType": {
            "@id": "vocab:ticketType",
            "@type": "xsd:string"
          },
          "seatNumber": {
            "@id": "vocab:seatNumber",
            "@type": "xsd:string"
          }
        }
      }
    }
  ]
}
```

#### JSON Schema

```json theme={null}
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "$metadata": {
    "uris": {
      "jsonLdContext": "https://your-domain.com/schemas/event-pass.json-ld",
      "jsonSchema": "https://your-domain.com/schemas/event-pass.json"
    }
  },
  "required": [
    "@context",
    "id",
    "type",
    "issuanceDate",
    "credentialSubject",
    "credentialSchema",
    "credentialStatus",
    "issuer"
  ],
  "properties": {
    "@context": {
      "type": ["string", "array", "object"]
    },
    "id": {
      "type": "string"
    },
    "type": {
      "type": ["string", "array"],
      "items": {
        "type": "string"
      }
    },
    "issuer": {
      "type": ["string", "object"],
      "format": "uri",
      "required": ["id"],
      "properties": {
        "id": {
          "type": "string",
          "format": "uri"
        }
      }
    },
    "issuanceDate": {
      "type": "string",
      "format": "date-time"
    },
    "expirationDate": {
      "type": "string",
      "format": "date-time"
    },
    "credentialSchema": {
      "type": "object",
      "required": ["id", "type"],
      "properties": {
        "id": {
          "type": "string",
          "format": "uri"
        },
        "type": {
          "type": "string"
        }
      }
    },
    "credentialSubject": {
      "type": "object",
      "required": ["id", "eventName", "eventDate", "ticketType"],
      "properties": {
        "id": {
          "title": "Credential Subject ID",
          "type": "string",
          "format": "uri"
        },
        "eventName": {
          "title": "Event Name",
          "type": "string",
          "description": "Name of the event"
        },
        "eventDate": {
          "title": "Event Date",
          "type": "string",
          "format": "date-time",
          "description": "Date and time of the event"
        },
        "ticketType": {
          "title": "Ticket Type",
          "type": "string",
          "description": "Type of ticket",
          "enum": ["general", "vip", "backstage", "premium"]
        },
        "seatNumber": {
          "title": "Seat Number",
          "type": "string",
          "description": "Seat or section number"
        }
      }
    }
  }
}
```

### Professional credential schema

#### JSON-LD context

```json theme={null}
{
  "@context": [
    {
      "@version": 1.1,
      "@protected": true,
      "id": "@id",
      "type": "@type",
      "ProfessionalCredential": {
        "@id": "https://your-domain.com/schemas/professional-credential.json-ld#ProfessionalCredential",
        "@context": {
          "@version": 1.1,
          "@protected": true,
          "id": "@id",
          "type": "@type",
          "vocab": "https://your-domain.com/vocab/professional-credential#",
          "xsd": "http://www.w3.org/2001/XMLSchema#",
          "certificationName": {
            "@id": "vocab:certificationName",
            "@type": "xsd:string"
          },
          "issuingOrganization": {
            "@id": "vocab:issuingOrganization",
            "@type": "xsd:string"
          },
          "certificationNumber": {
            "@id": "vocab:certificationNumber",
            "@type": "xsd:string"
          },
          "issueDate": {
            "@id": "vocab:issueDate",
            "@type": "xsd:date"
          },
          "expiryDate": {
            "@id": "vocab:expiryDate",
            "@type": "xsd:date"
          },
          "credentialLevel": {
            "@id": "vocab:credentialLevel",
            "@type": "xsd:string"
          }
        }
      }
    }
  ]
}
```

#### JSON Schema

```json theme={null}
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "$metadata": {
    "uris": {
      "jsonLdContext": "https://your-domain.com/schemas/professional-credential.json-ld",
      "jsonSchema": "https://your-domain.com/schemas/professional-credential.json"
    }
  },
  "required": [
    "@context",
    "id",
    "type",
    "issuanceDate",
    "credentialSubject",
    "credentialSchema",
    "credentialStatus",
    "issuer"
  ],
  "properties": {
    "@context": {
      "type": ["string", "array", "object"]
    },
    "id": {
      "type": "string"
    },
    "type": {
      "type": ["string", "array"],
      "items": {
        "type": "string"
      }
    },
    "issuer": {
      "type": ["string", "object"],
      "format": "uri",
      "required": ["id"],
      "properties": {
        "id": {
          "type": "string",
          "format": "uri"
        }
      }
    },
    "issuanceDate": {
      "type": "string",
      "format": "date-time"
    },
    "expirationDate": {
      "type": "string",
      "format": "date-time"
    },
    "credentialSchema": {
      "type": "object",
      "required": ["id", "type"],
      "properties": {
        "id": {
          "type": "string",
          "format": "uri"
        },
        "type": {
          "type": "string"
        }
      }
    },
    "credentialSubject": {
      "type": "object",
      "required": [
        "id",
        "certificationName",
        "issuingOrganization",
        "certificationNumber",
        "issueDate"
      ],
      "properties": {
        "id": {
          "title": "Credential Subject ID",
          "type": "string",
          "format": "uri"
        },
        "certificationName": {
          "title": "Certification Name",
          "type": "string",
          "description": "Name of the certification"
        },
        "issuingOrganization": {
          "title": "Issuing Organization",
          "type": "string",
          "description": "Organization that issued the certification"
        },
        "certificationNumber": {
          "title": "Certification Number",
          "type": "string",
          "description": "Unique certification identifier"
        },
        "issueDate": {
          "title": "Issue Date",
          "type": "string",
          "format": "date",
          "description": "Date the certification was issued"
        },
        "expiryDate": {
          "title": "Expiry Date",
          "type": "string",
          "format": "date",
          "description": "Date the certification expires"
        },
        "credentialLevel": {
          "title": "Credential Level",
          "type": "string",
          "description": "Level of certification",
          "enum": ["associate", "professional", "expert", "master"]
        }
      }
    }
  }
}
```


# Selective Disclosure
Source: https://docs.air3.com/products/identity/selective-disclosure

Selective disclosure lets verifiers read only the credential fields they request, with the holder's approval. It is built into SD-JWT VC credentials.

Selective disclosure lets a verifier request specific fields from a credential, and the holder share only those, with their approval. It is built into SD-JWT VC credentials, the default format.

**How it works for SD-JWT.** At issuance, each selectively disclosable claim is replaced in the signed credential by a salted digest. The issuer chooses these claims with the `disclosureFrame` in its schema class. At verification, the holder sends the disclosures for the fields you request. You can check each one against its digest, and the rest stay hidden. Claims outside the `disclosureFrame` are always visible.

Iden3 programs can instead prove a condition, such as `membershipTier > bronze`, with a zero-knowledge proof. See [Iden3 credentials](/products/identity/iden3-credentials).

## When to use it

Selective Disclosure is useful when the Verifier needs a specific value, but not the whole credential, to choose the right reward, access level, or next step.

A common example is a **membership rewards flow**:

* A user proves they hold a valid membership credential.
* The Verifier requests only `membershipTier`, not the member's name, ID, or points balance.
* The holder approves, and the Verifier confirms the value is `gold` and grants the Gold reward.

In this flow, Selective Disclosure gives the Verifier the one field it needs to apply the correct business logic, and nothing else.

Other typical scenarios:

* A loyalty program that discloses `rewardPoints` only after the credential is verified.
* A KYC Verifier that needs `countryCode` and `kycLevel` to route the user through the correct compliance flow.
* A ticketing partner that needs `seatTier` to issue a physical wristband at the venue.
* A fintech onboarding step where an analyst reviews disclosed `verifiedAt` timestamps.

## Prerequisites

Before using Selective Disclosure you need:

1. **Latest AIR Kit SDK** — Install or upgrade to the latest version of `@mocanetwork/airkit`. Nested field paths need 1.12.1 or later.
2. **SD-JWT credential with disclosable claims** — The Issuer lists the claims in `disclosureFrame._sd` and has **Allow data disclosure** turned on for the issuance program.
3. **Active verification program** — A published verification program in the Developer Dashboard (Verifier → Programs).
4. **Partner JWT with `scope=verify`** — See [SDK authentication](/get-started/authentication/sdk-auth).

## Step 1: Enable disclosure on the issuance program

Selective Disclosure must be enabled by the **Issuer**. As a Verifier, you cannot request disclosed data unless the Issuer has opted in.

In the issuer service, list each disclosable claim in the schema class's `disclosureFrame`:

```ts theme={null}
public readonly disclosureFrame: DisclosureFrame<Claim> = {
  _sd: ["membershipTier", "rewardPoints"],
};
```

Then enable disclosure on the issuance program in the Dashboard:

<Steps>
  <Step title="Open the Developer Dashboard">
    Sign in to the <a href="https://developers.sandbox.air3.com/dashboard">Developer Dashboard</a> with your Issuer account.
  </Step>

  <Step title="Create or edit an issuance program">
    Navigate to **Issuer → Programs** and either create a new program (Issue Pricing) or open an existing one to edit.
  </Step>

  <Step title="Expand Advanced set up">
    In the credential form, expand the **Advanced set up** section.
  </Step>

  <Step title="Enable Allow data disclosure">
    Toggle **Allow data disclosure** on, then save the program.
  </Step>
</Steps>

Any credential issued from this program will now support Selective Disclosure during verification.

## Step 2: Request disclosure during verification

On the Verifier side, pass `fieldsToDisclose` to `airService.verifyCredential`, along with a `nonce` from your backend. `fieldsToDisclose` is required for `SD_JWT_VC` programs. There are two supported shapes.

### Disclose the entire credential subject

Pass `'*'` to receive every field in the credential subject.

<Tabs>
  <Tab title="Web">
    ```ts theme={null}
    const result = await airService!.verifyCredential({
      authToken,
      programId,
      fieldsToDisclose: '*',
      nonce,
    });
    ```
  </Tab>
</Tabs>

### Disclose specific fields

Pass an array of field names from the credential subject. Only the listed fields are returned. Use dotted paths for nested fields, such as `address.city`.

```ts theme={null}
const result = await airService!.verifyCredential({
  authToken,
  programId,
  fieldsToDisclose: ['membershipTier', 'address.city'],
  nonce,
});
```

<Note>
  Field names in `fieldsToDisclose` must match keys defined in the credential schema. Fields the Issuer has not enabled for disclosure are silently omitted.
</Note>

## Response shape

When the verification result is `Compliant`, the disclosed fields are inside the W3C Verifiable Presentation on `verifiablePresentation`.

For `SD_JWT_VC` programs, `verifiableCredential[0]` is an `EnvelopedVerifiableCredential`. Its `id` is `data:application/dc+sd-jwt,` followed by the compact SD-JWT, which carries one disclosure per requested field:

```text theme={null}
<Issuer-JWT>~<Disclosure: membershipTier>~<Disclosure: address.city>~<KB-JWT>
```

Do not read the disclosed values in the browser and trust them. Send the presentation to your backend, verify it, and read the claims from the verified result. See [Verify SD-JWT on your backend](/products/identity/verify-sd-jwt): its reference implementation returns the verified claims, with nested fields as nested objects (`claims.address.city`).

For Iden3 programs, `verifiableCredential` holds W3C Verifiable Credential objects whose `credentialSubject` contains the requested fields.

<Note>
  **Deprecated as of 1.11.** Disclosure used to be returned on a top-level `disclosedData` object alongside `zkProofs` and `transactionHash`. Those fields are no longer populated — read `verifiablePresentation` instead. See the [1.11.1 release notes](/api-reference/release-notes).
</Note>

## Behavior and limits

* Disclosed fields are only returned when `status === "Compliant"`. Non-compliant verifications never expose credential data.
* If the Issuer has not enabled **Allow data disclosure** on the program, `fieldsToDisclose` is ignored and no disclosed claims appear in the presentation.
* Requesting fields that do not exist on the schema or were not enabled for disclosure does not fail the verification — those fields are simply absent.
* `fieldsToDisclose` is **required** for `SD_JWT_VC` programs — an empty array or an omitted value is rejected.
* Disclosure is additive, not a replacement for verification. The issuer signature, expiry, and key binding are checked regardless of which fields you disclose.
* SD-JWT disclosures reveal exact values. To prove a condition without revealing the value, use an [Iden3 program](/products/identity/iden3-credentials).

<Tip>
  Treat the disclosed `credentialSubject` as user data: store it only as long as you need it for the downstream action (redemption, compliance review, fulfillment), and apply the same retention rules as any PII you receive directly from the user.
</Tip>

## Related

<Card title="Verifying Credentials" icon="arrow-right" href="/products/identity/verify">
  The base verification flow that Selective Disclosure builds on.
</Card>

<Card title="Partner Authentication" icon="key" href="/get-started/authentication/sdk-auth">
  Generate the `scope=verify` Partner JWT used as `authToken`.
</Card>


# Use cases
Source: https://docs.air3.com/products/identity/use-cases

Turn records in your database or results from an existing identity verification provider into credentials users can present to other applications.

AIR Identity lets you turn a fact your business already knows into a signed credential that a user can present elsewhere. Your system remains the source of truth; a receiving application decides which issuers and claims it accepts.

## Issue from your existing database

Use this pattern for membership tiers, enrollment, subscriptions, or eligibility already recorded in your system.

**Example:** Your database records that a customer is a current Gold member. You issue a credential containing the membership facts a partner needs to grant a benefit, without including the customer's purchase history.

1. Choose the minimum claims with [What data do you need?](/products/identity/what-data), then [create your first schema](/products/identity/schema-creation).
2. Connect your issuer backend to the records it needs. Keep source data and issuer signing keys on your servers; see [Setting up your backend](/products/identity/backend-hosting).
3. Choose the trigger: a tier change, account creation, or another confirmed backend event. Use direct issuance when the user does not need to be present, or SDK issuance when the user should review and claim the credential.
4. Resolve the intended recipient using the identifier your issuance flow expects. For the documented direct issuance flow, that is the recipient's email, not a shared service account.
5. Record the issuance and deduplicate repeated events. When the signed status changes, revoke the old credential and issue a replacement as appropriate.

Follow [Issuing credentials](/products/identity/issuing-credentials) for both issuance paths and [Managing your credentials](/products/identity/revocation) for updates and revocation. A database edit alone does not update an already issued credential.

## Issue a credential from an existing KYC result

Use this pattern when you already verify users with a provider such as Persona or Sumsub and want to make an approved result presentable through AIR.

**Example:** Your business attests that a customer passed a defined verification level on a given date. A receiving app checks that statement against its own issuer, assurance, and freshness requirements.

1. Agree which claims your business can attest to, such as verification level and check date. Keep raw identity documents out of the credential unless the use case specifically requires them.
2. Receive and validate the provider's result in your backend using the provider's documented process. Match it to the correct customer record before issuing.
3. Apply your own eligibility rules, then use your issuer backend to sign and encrypt the credential to the intended AIR Account.
4. Set an appropriate validity period. Handle a later withdrawal or change in status through your revocation and reissuance process.
5. The receiving app accepts only trusted issuers and checks that the disclosed result meets its own requirements before acting on it.

This is an integration pattern for your existing provider, not a preconfigured Persona or Sumsub connector. AIR carries your issuer-signed statement; the original identity check remains with your provider.

For an AIR KYC solution rather than an existing-provider pattern, see [Veriff powered by zkMe](/solutions/kyc).

## Choose the issuance path

Direct issuance suits backend events, but the documented direct flow issues credentials without a holder binding key. Presentations from those credentials are bearer presentations. Choose SDK issuance when you need holder binding, and follow the [SD-JWT verification guide](/products/identity/verify-sd-jwt) for the checks each path requires.

Try the concepts in the [AIR demos](https://air-bd-v2.netlify.app), then use the linked guides for your integration.


# Verifying credentials
Source: https://docs.air3.com/products/identity/verify

Verify AIR Credentials with program-driven verification: the program sets the credential format, requested claims, and selective disclosure; your app passes a programId.

As a Verifier, your role is to verify the authenticity of user credentials and ensure they meet your requirements. Verification is **program-driven**: a Verification Program configured in the Developer Dashboard centrally controls the accepted credential format, the requested claims, and selective disclosure. Your integration passes a `programId`, the fields to disclose, and a `nonce`; the SDK handles credential discovery, consent, and result handling.

Most programs accept SD-JWT VC credentials, the default format. Iden3 programs add zero-knowledge proofs and on-chain verification; see [Iden3 credentials](/products/identity/iden3-credentials).

## Verification flow

1. **Start verification** — the verifier starts a session with a `programId`. The program defines what to check and how.
2. **Consent + discovery** — the SDK requests the holder's consent and loads the matching encrypted credential from DStorage.
3. **Presentation** — the holder decrypts the credential and discloses only the requested claims. For SD-JWT credentials with a holder key, the holder also signs a key-binding JWT over your `nonce`. Iden3 programs generate a zero-knowledge proof instead where required.
4. **Verification** — the presentation is checked against the program's settings off-chain. Iden3 programs can also record the proof on-chain.
5. **Result** — on success the SDK returns a W3C **Verifiable Presentation** containing the disclosed credential. Verify it again on your backend before you act on it.

```mermaid theme={null}
sequenceDiagram
    autonumber
    participant Verifier
    participant SDK as AIR Verifier SDK
    participant User as Holder
    participant DS as Encrypted DStorage
    Verifier->>SDK: Start verification (programId)
    SDK->>User: Request consent + requested claims
    SDK->>DS: Load matching encrypted credential
    DS-->>SDK: Encrypted credential
    User->>User: Decrypt credential
    User->>User: Disclose requested claims (+ key-binding JWT)
    SDK->>SDK: Check presentation against program settings
    SDK-->>Verifier: Verifiable Presentation (on success)
```

Every verification attempt is recorded as a **verification session** — a server-side record of the result, mode, holder context, and usage data — giving you consistent reporting across integrations.

## Verifier integration checklist

1. Create or select a **Verification Program** in the <a href="https://developers.sandbox.air3.com/dashboard">Developer Dashboard</a> (Verifier → Program).
2. Configure the program:
   * Accepted proof type: `SD_JWT_VC` (default), or `BJJ_SIG_2021` for [Iden3 programs](/products/identity/iden3-credentials)
   * Requested claims and whether selective disclosure is required
   * Whether to check issuer revocation status
   * The Issuer's DID to constrain trusted issuers (optional)
   * For Iden3 programs only: whether a ZKP is required, and off-chain vs on-chain verification
3. Publish the program and take note of the `programId`.
4. Integrate the AIR Verifier SDK.
5. Start verification with the `programId`.
6. Handle outcomes: Compliant, Non-compliant, No matching credential, User declined consent, or proof/verification failure.
7. On success, send the returned Verifiable Presentation to your backend and [verify it there](/products/identity/verify-sd-jwt) before granting access or rewards.

<Note>
  The dashboard link above uses Sandbox for development. For production launches, use the [production Developer Dashboard](https://developers.air3.com/dashboard). Moca Chain mainnet is live, and SD-JWT verification programs are self-serve in production. See [Production mainnet access](/get-started/environments/about#production-mainnet-access).
</Note>

## Start verification

Generate a [Partner JWT](/get-started/authentication/sdk-auth) with `scope=verify` and a fresh `nonce` on your backend, then start verification with the SDK. The credential format and requested claims come from the program configuration, so your call stays minimal.

<Tabs>
  <Tab title="Web">
    ```jsx theme={null}
    public async verifyCredential({
        authToken,
        programId,
        redirectUrl,
        fieldsToDisclose,
        nonce,
      }: {
        authToken: string;
        programId: string;
        redirectUrl?: string;
        fieldsToDisclose?: "*" | string[];
        nonce?: string;
      }): Promise<CredentialVerificationResult>
    ```

    ### Input parameters

    | Name | Type | Required | Description |
    | - | - | - | - |
    | `authToken` | string | Yes | Your signed Partner JWT, with `scope=verify`. |
    | `programId` | string | Yes | Identifier for the verification program. Drives the accepted format and requested claims. It is also the `aud` of the key-binding JWT. |
    | `redirectUrl` | string | No | Optional URL to redirect the user if they have not yet been issued the relevant credential. |
    | `fieldsToDisclose` | `"*"` \| `string[]` | Required for `SD_JWT_VC` | Credential fields to disclose. `"*"` discloses every field. Use dotted paths for nested fields, such as `address.city`. See [Selective Disclosure](/products/identity/selective-disclosure). |
    | `nonce` | string | No | A random value from your backend, at least 128 bits. For SD-JWT credentials with a holder key (`cnf.jwk`), the holder signs a key-binding JWT over it, so the presentation cannot be replayed. Without it the presentation is a bearer token. Ignored for Iden3 programs. |

    ### Response

    The function returns a `Promise<CredentialVerificationResult>`, a discriminated union on `status`.

    **For non-compliant statuses** (`"Non-Compliant"`, `"Pending"`, `"Revoking"`, `"Revoked"`, `"Expired"`, `"NotFound"`):

    | Field | Type | Description |
    | - | - | - |
    | `status` | string | The result of the credential verification. |

    **For compliant status** (`"Compliant"`):

    ```ts theme={null}
    type CredentialVerificationResult = {
      status: "Compliant";
      verifiablePresentation?: {
        "@context": string[];
        type: string[];
        holder: string;
        verifiableCredential: Array<PresentationVerifiableCredential | string>;
        proof?: VerifiablePresentationProof | VerifiablePresentationProof[];
      };
    };
    ```

    | Field | Type | Description |
    | - | - | - |
    | `status` | `"Compliant"` | The credential is valid and meets all verification requirements. |
    | `verifiablePresentation` | `object` | W3C [Verifiable Presentation](https://www.w3.org/TR/vc-data-model-2.0/#verifiable-presentations) carrying the disclosed credential. |

    Inside the presentation:

    | Field | Description |
    | - | - |
    | `holder` | The holder's DID. Not signed; do not trust it on its own. |
    | `verifiableCredential` | The disclosed credential. For `SD_JWT_VC` programs this is an `EnvelopedVerifiableCredential` whose `id` is `data:application/dc+sd-jwt,` followed by the compact SD-JWT (older results use `data:application/vc+sd-jwt,`). For Iden3 programs these are W3C Verifiable Credential objects; see [Iden3 credentials](/products/identity/iden3-credentials#verify-iden3-credentials). Type-check each entry before reading it. |
    | `proof` | Iden3 programs only, when a zero-knowledge proof is required. |

    For an `SD_JWT_VC` program, the presentation looks like this:

    ```json theme={null}
    {
      "status": "Compliant",
      "verifiablePresentation": {
        "@context": ["https://www.w3.org/ns/credentials/v2"],
        "type": ["VerifiablePresentation"],
        "holder": "did:air:…",
        "verifiableCredential": [
          {
            "@context": ["https://www.w3.org/ns/credentials/v2"],
            "type": ["EnvelopedVerifiableCredential"],
            "id": "data:application/dc+sd-jwt,<Issuer-JWT>~<Disclosure-1>~…~<KB-JWT>"
          }
        ]
      }
    }
    ```

    <Warning>
      The presentation wrapper, including `holder`, is **not signed**. Only the compact SD-JWT inside `id` is. AIR checks it in the user's browser, so verify the SD-JWT on your backend before you rely on the result. See [Verify SD-JWT on your backend](/products/identity/verify-sd-jwt).
    </Warning>

    See [Selective Disclosure](/products/identity/selective-disclosure) for how requested fields populate the presentation.
  </Tab>

  <Tab title="Flutter">
    ```dart theme={null}
    Future<CredentialVerificationResult> verifyCredential({
      required String authToken,
      required String programId,
      String? redirectUrl,
    });
    ```

    | Name | Type | Required | Description |
    | - | - | - | - |
    | `authToken` | `String` | Yes | Your signed Partner JWT, with `scope=verify`. |
    | `programId` | `String` | Yes | Identifier for the verification program. |
    | `redirectUrl` | `String?` | No | Optional URL to redirect the user if they have not yet been issued the relevant credential. |

    See [Reference](/api-reference/sdk-reference) (Flutter tab) for response models.
  </Tab>
</Tabs>

Under the hood, the SDK loads the holder's matching encrypted credential from DStorage, decrypts it locally, and obtains consent for disclosure. AIR handles ciphertext and metadata; the verifier receives the user-approved disclosures. A successful result returns the compliant payload above.

## Next steps

* [Verify SD-JWT on your backend](/products/identity/verify-sd-jwt)
* [Selective disclosure](/products/identity/selective-disclosure)
* [Iden3 verification modes](/products/identity/iden3-credentials#verify-iden3-credentials)


# Verify with SD-JWT
Source: https://docs.air3.com/products/identity/verify-sd-jwt

Verify the SD-JWT presentation returned by verifyCredential on your own server: issuer signature, disclosures, expiry, key binding, nonce, audience, and revocation.

Use this guide when you call `airService.verifyCredential(...)` against an `SD_JWT_VC` verification program and the result drives anything on your side, such as account upgrades, access, or payouts.

AIR checks the presentation before it returns `Compliant`, but that check runs in the user's browser. Send the presentation to your backend and verify it there.

## What you receive

A `Compliant` result carries a W3C Verifiable Presentation. For `SD_JWT_VC` programs it wraps one compact SD-JWT inside an `EnvelopedVerifiableCredential`:

```json theme={null}
{
  "status": "Compliant",
  "verifiablePresentation": {
    "@context": ["https://www.w3.org/ns/credentials/v2"],
    "type": ["VerifiablePresentation"],
    "holder": "did:air:…",
    "verifiableCredential": [
      {
        "@context": ["https://www.w3.org/ns/credentials/v2"],
        "type": ["EnvelopedVerifiableCredential"],
        "id": "data:application/dc+sd-jwt,<Issuer-JWT>~<Disclosure-1>~…~<Disclosure-N>~<KB-JWT>"
      }
    ]
  }
}
```

<Warning>
  The presentation wrapper, including `holder`, is **not signed**. Only the compact SD-JWT inside `id` is. Everything you trust must come from that token.
</Warning>

Other statuses (i.e. `Non-Compliant`, `NotFound`) carry no presentation.

## Holder key binding

Holder binding stops a leaked credential from being presented by someone else.

* **At issuance**, the user's AIR Account provides a P-256 public key, and the issuer writes it to the credential's `cnf.jwk` claim. In SDK issuance AIR sends the key to the issuer as `signingKey.jwk`, and the credential carries `cnf` whenever it does; [direct issuance](/products/identity/issuing-credentials#direct-issuance) has no holder present, so those credentials do not.
* **At verification**, the holder signs a key-binding JWT (KB-JWT) with the matching private key. It covers your `nonce`, your `programId`, the signing time, and a hash of the disclosed claims, so it cannot be reused or edited.

AIR attaches a KB-JWT only when **both** of these are true:

1. You passed a `nonce` to `verifyCredential`.
2. The credential's issuer JWT contains a holder key in `cnf.jwk` (EC P-256).

The KB-JWT's `aud` is always the `programId` you passed.

| You sent `nonce` | Issuer JWT has `cnf.jwk` | Token ends with | What it proves |
| - | - | - | - |
| No | Either | `~` | The issuer issued these claims. Anyone holding the token can replay it. |
| Yes | No | `~` | Same as above. The credential has no holder key, so it cannot be holder-bound. |
| Yes | Yes | `~<KB-JWT>` | The holder's key signed this exact presentation, for your nonce and your `programId`. |

Without a KB-JWT the token is a **bearer** presentation: if it leaks through logs, proxies, or a malicious script on the page, someone else can submit it as their own. If that matters for your use case, always send a nonce and require holder binding.

## Recommended flow

<Steps>
  <Step title="Create a nonce on your backend">
    Generate at least 128 bits of randomness, for example `crypto.randomBytes(16).toString("base64url")`, and store it against the user's session.
  </Step>

  <Step title="Pass it to verifyCredential">
    ```ts theme={null}
    const result = await airService.verifyCredential({
      authToken,
      programId,
      fieldsToDisclose: ["given_name", "address.city"], // required for SD_JWT_VC programs; "*" discloses all
      nonce, // from your backend
    });
    ```
  </Step>

  <Step title="Send the presentation to your backend">
    On `Compliant`, post `result.verifiablePresentation` to your backend.
  </Step>

  <Step title="Verify, then consume the nonce">
    Run the checks below, then delete the nonce so it cannot be used again.
  </Step>
</Steps>

## Token anatomy

The compact token is `~`-separated:

```text theme={null}
<Issuer-JWT>~<Disclosure-1>~…~<Disclosure-N>~             no KB-JWT
<Issuer-JWT>~<Disclosure-1>~…~<Disclosure-N>~<KB-JWT>     with KB-JWT
```

To get it, take `verifiableCredential[0].id` and strip the `data:application/dc+sd-jwt,` prefix. Older results may use `data:application/vc+sd-jwt,`; accept both.

**Issuer JWT.** Signed by the credential issuer. The payload carries the always-visible claims, plus `_sd` digests for the selectively disclosable ones:

```json theme={null}
{
  "iss": "did:web:issuer.example",
  "vct": "<credential type>",
  "iat": 1790000000,
  "exp": 1821536000,
  "cnf": { "jwk": { "kty": "EC", "crv": "P-256", "x": "…", "y": "…" } },
  "status": { "status_list": { "idx": 42, "uri": "https://…" } },
  "_sd_alg": "sha-256",
  "_sd": ["<digest>", "<digest>"]
}
```

`cnf` is present only on holder-bound credentials, and `status` only when the issuer publishes a [token status list](/products/identity/revocation#token-status-list).

**Disclosures.** Each is base64url-encoded JSON such as `["<salt>", "given_name", "Ada"]`. A disclosure is valid only if its SHA-256 digest appears in an `_sd` array of the signed payload. The token contains only the disclosures for the fields you requested; the others stay hidden behind their digests.

**KB-JWT.** Signed by the holder's key from `cnf.jwk`:

```json theme={null}
// header
{ "typ": "kb+jwt", "alg": "ES256" }
// payload
{ "nonce": "<your nonce>", "aud": "<your programId>", "iat": 1790000000, "sd_hash": "<base64url SHA-256>" }
```

`sd_hash` is the base64url SHA-256 of everything before the KB-JWT, including the trailing `~`. It locks the set of disclosures, so nobody can add or remove one after the holder signed.

## Checks

### Always

1. **Issuer is trusted.** `iss` is on your allowlist. Choose the issuer's key source from your own configuration, never from a URL taken from the token.
2. **Issuer signature is valid**, using the issuer's keys:
   * `did:web` issuer: fetch the DID document. `did:web:issuer.example` resolves to `https://issuer.example/.well-known/did.json`, and `did:web:issuer.example:path` to `https://issuer.example/path/did.json`. Use the `publicKeyJwk` of its `assertionMethod` entries. The JWT header `kid` is the full DID URL (`did:web:issuer.example#key-1`); older credentials carry only the fragment (`key-1`).
   * HTTPS issuer: use the issuer's JWKS URL, the one registered with AIR for the issuing partner. If you are the issuer, that is your own JWKS URL.
3. **Disclosures are genuine.** `_sd_alg` is `sha-256`, and every disclosure's digest appears in the signed payload.
4. **Credential is in date.** `exp` has not passed, and `nbf` (if present) has.
5. **Credential type is right.** `vct` equals the type you expect.
6. **You got what you asked for.** Every field in your `fieldsToDisclose` is present among the verified claims.
7. **Optional: not revoked.** See [Revocation](#revocation).

### Additionally, when a KB-JWT is expected

Expect a KB-JWT whenever you sent a nonce and the issuer JWT has `cnf.jwk`.

1. **KB-JWT is present.** If it is missing, reject: someone stripped the binding.
2. **Header** is `typ: kb+jwt` with `alg: ES256`.
3. **Signature** verifies against the issuer JWT's `cnf.jwk`.
4. `nonce` equals the nonce you issued for this session. Consume it after one check.
5. `aud` equals your `programId`.
6. `iat` is recent: no older than your freshness window (for example 5 minutes), and not in the future beyond a small clock-skew allowance (for example 60 seconds).
7. `sd_hash` equals the base64url SHA-256 of the token up to and including the `~` before the KB-JWT.

### Decision table

| You sent `nonce` | `cnf.jwk` | KB-JWT present | Action |
| - | - | - | - |
| No | Either | No | Accept only if a bearer presentation is acceptable for your use case. |
| Yes | Yes | Yes | Run every check above. Accept if all pass. |
| Yes | Yes | No | **Reject.** AIR always attaches it in this case, so it was removed. |
| Yes | No | No | The credential cannot be holder-bound. Reject if you require binding, otherwise treat it as bearer. |
| No | Either | Yes | AIR does not produce this. The KB-JWT proves nothing without your nonce; treat it as bearer. |

A KB-JWT whose `nonce`, `aud`, signature, or `sd_hash` does not match is always a rejection.

## Reference implementation (TypeScript, Node.js)

Built on [`@sd-jwt/sd-jwt-vc`](https://github.com/openwallet-foundation/sd-jwt-js) and [`jose`](https://github.com/panva/jose), the libraries AIR itself uses. Tested with `@sd-jwt/sd-jwt-vc` 0.20 and `jose` 5 on Node.js 22, covering the valid cases and the rejections in the decision table: stripped KB-JWT, wrong `aud`, wrong nonce, stale KB-JWT, a disclosure removed after signing, and a forged issuer signature.

```bash theme={null}
npm i @sd-jwt/sd-jwt-vc@^0.20 jose@^5
```

The code works around two library behaviors:

* The library checks the KB-JWT's `typ`, signature, `nonce`, and `sd_hash`, but **not** `aud` or how old `iat` is. The function checks those itself.
* The library **ignores the KB-JWT entirely** unless you pass `keyBindingNonce`. The function passes it whenever a KB-JWT is expected, so a stripped KB-JWT fails with `Key Binding JWT not exist`.

```ts verify-air-sd-jwt.ts theme={null}
import { createHash } from "node:crypto";
import { SDJwtVcInstance } from "@sd-jwt/sd-jwt-vc";
import {
  compactVerify,
  createLocalJWKSet,
  createRemoteJWKSet,
  decodeJwt,
  importJWK,
  type JWK,
} from "jose";

/** An issuer you accept, and where its signing keys are published. */
export type TrustedIssuer =
  | { iss: `did:web:${string}` } // keys from the DID document's assertionMethod
  | { iss: string; jwksUrl: string }; // keys from the issuer's JWKS

export type VerifyAirSdJwtInput = {
  /** `verifiablePresentation` from a Compliant `verifyCredential` result. */
  verifiablePresentation: { verifiableCredential?: Array<{ id?: unknown }> };
  /** The `programId` you passed to `verifyCredential`. It is the KB-JWT `aud`. */
  programId: string;
  /** The `nonce` you passed to `verifyCredential`. Omit it if you passed none. */
  expectedNonce?: string;
  /** Reject presentations that are not holder-bound. */
  requireHolderBinding?: boolean;
  trustedIssuers: TrustedIssuer[];
  expectedVct: string;
  /** Claims that must be present, for example your `fieldsToDisclose`. */
  requiredClaims?: string[];
  /** Maximum KB-JWT age. Default 300. */
  maxKbAgeSeconds?: number;
  /** Tolerated clock difference with the holder's device. Default 60. */
  skewSeconds?: number;
  /** Check the issuer's Token Status List (revocation). Default false. */
  checkStatus?: boolean;
};

const ENVELOPE_PREFIXES = ["data:application/dc+sd-jwt,", "data:application/vc+sd-jwt,"];

export function extractCompactSdJwt(vp: VerifyAirSdJwtInput["verifiablePresentation"]): string {
  const id = vp.verifiableCredential?.[0]?.id;
  const prefix = ENVELOPE_PREFIXES.find((p) => typeof id === "string" && id.startsWith(p));
  if (typeof id !== "string" || !prefix) {
    throw new Error("The presentation does not contain an enveloped SD-JWT");
  }
  return id.slice(prefix.length);
}

const sha256 = (data: string | ArrayBuffer, alg: string): Uint8Array => {
  if (alg !== "sha-256") throw new Error(`Unsupported _sd_alg: ${alg}`);
  return createHash("sha256")
    .update(typeof data === "string" ? data : new Uint8Array(data))
    .digest();
};

type DidVerificationMethod = { id: string; publicKeyJwk?: JWK };
type DidDocument = {
  verificationMethod?: DidVerificationMethod[];
  assertionMethod?: Array<string | DidVerificationMethod>;
};

async function didWebKeySet(did: string) {
  const [host, ...path] = did.slice("did:web:".length).split(":");
  const origin = `https://${host.replace(/%3A/gi, ":")}`;
  const url = path.length
    ? `${origin}/${path.join("/")}/did.json`
    : `${origin}/.well-known/did.json`;
  const res = await fetch(url);
  if (!res.ok) throw new Error(`DID document fetch failed: HTTP ${res.status}`);
  const doc = (await res.json()) as DidDocument;

  const absolute = (id: string) => (id.startsWith("#") ? `${did}${id}` : id);
  const methods = new Map((doc.verificationMethod ?? []).map((vm) => [absolute(vm.id), vm]));
  const keys: JWK[] = [];
  for (const ref of doc.assertionMethod ?? []) {
    const vm = typeof ref === "string" ? methods.get(absolute(ref)) : ref;
    if (!vm?.publicKeyJwk) continue;
    const id = absolute(vm.id);
    // Current credentials use the full DID URL as `kid`; older ones use only the fragment.
    keys.push({ ...vm.publicKeyJwk, kid: id });
    const fragment = id.split("#")[1];
    if (fragment) keys.push({ ...vm.publicKeyJwk, kid: fragment });
  }
  return createLocalJWKSet({ keys });
}

export async function verifyAirSdJwt(input: VerifyAirSdJwtInput) {
  const {
    programId,
    expectedNonce,
    requireHolderBinding = false,
    maxKbAgeSeconds = 300,
    skewSeconds = 60,
    checkStatus = false,
  } = input;
  const compact = extractCompactSdJwt(input.verifiablePresentation);

  // Unverified read, used only to select keys. The signature check below covers these claims.
  const unverified = decodeJwt(compact.split("~")[0]);
  const issuer = input.trustedIssuers.find((t) => t.iss === unverified.iss);
  if (!issuer) throw new Error(`Untrusted issuer: ${String(unverified.iss)}`);
  const issuerKeys =
    "jwksUrl" in issuer
      ? createRemoteJWKSet(new URL(issuer.jwksUrl))
      : await didWebKeySet(issuer.iss);

  const cnf = unverified.cnf;
  const holderBindable = typeof cnf === "object" && cnf !== null && "jwk" in cnf;
  if (requireHolderBinding && !(expectedNonce && holderBindable)) {
    throw new Error(
      "Holder binding required: send a nonce and accept only credentials with cnf.jwk"
    );
  }
  // With a nonce and cnf.jwk, Air always attaches a KB-JWT, so a missing one means it was stripped.
  const keyBindingNonce = expectedNonce && holderBindable ? expectedNonce : undefined;

  const verifyIssuerSignature = async (data: string, sig: string) => {
    try {
      await compactVerify(`${data}.${sig}`, issuerKeys);
      return true;
    } catch {
      return false;
    }
  };

  const sdjwt = new SDJwtVcInstance({
    hasher: sha256,
    verifier: verifyIssuerSignature,
    statusVerifier: verifyIssuerSignature,
    kbVerifier: async (data, sig, payload) => {
      const jwk = payload.cnf?.jwk;
      if (jwk?.kty !== "EC") return false;
      try {
        const key = await importJWK({ kty: "EC", crv: jwk.crv, x: jwk.x, y: jwk.y }, "ES256");
        await compactVerify(`${data}.${sig}`, key, { algorithms: ["ES256"] });
        return true;
      } catch {
        return false;
      }
    },
  });

  // Checks the issuer signature, disclosure digests, exp/nbf, and, when keyBindingNonce is set,
  // the KB-JWT's typ, signature, nonce and sd_hash.
  const { payload, kb } = await sdjwt.verify(compact, {
    keyBindingNonce,
    requiredClaimKeys: input.requiredClaims,
    skewSeconds,
    disableStatusVerification: !checkStatus,
  });

  if (payload.vct !== input.expectedVct) throw new Error(`Unexpected vct: ${payload.vct}`);
  if (keyBindingNonce) {
    // The library does not check the KB-JWT audience or age.
    if (!kb) throw new Error("Missing KB-JWT");
    if (kb.payload.aud !== programId) throw new Error(`KB-JWT aud mismatch: ${kb.payload.aud}`);
    if (Math.floor(Date.now() / 1000) - kb.payload.iat > maxKbAgeSeconds) {
      throw new Error("KB-JWT is too old");
    }
  }

  return { claims: payload, holderBound: keyBindingNonce !== undefined };
}
```

Usage on your backend:

```ts theme={null}
const { claims, holderBound } = await verifyAirSdJwt({
  verifiablePresentation: body.verifiablePresentation,
  programId: "<your programId>",
  expectedNonce: await consumeNonce(session), // your store: return the session's nonce and delete it
  requireHolderBinding: true,
  trustedIssuers: [{ iss: "did:web:issuer.example" }],
  expectedVct: "<credential type>",
  requiredClaims: ["given_name", "address.city"],
});
```

`claims` holds every verified claim: the always-visible ones (`iss`, `vct`, `cnf`, and so on) plus the disclosed fields, with nested fields as nested objects (`claims.address.city`). Undisclosed fields are absent. `holderBound` tells you whether a KB-JWT was verified.

Any failure throws, so treat an exception as "not verified".

## Revocation

Credentials whose issuer publishes an [IETF Token Status List](https://datatracker.ietf.org/doc/draft-ietf-oauth-status-list/) carry `status.status_list.{uri, idx}` in the issuer JWT. To check it, pass `checkStatus: true`. The library then:

1. Fetches `uri` with `Accept: application/statuslist+jwt`. The response must use that content type.
2. Verifies the status-list JWT with the same issuer keys.
3. Rejects the credential if the entry at `idx` is not `0` (valid).

AIR performs this check during `verifyCredential` only when the verification program enables issuer revocation checks. If you store presentations and re-verify them later, check the status at that point. Issuers without a status list answer per credential at `GET /revocation-status/:nonce`; see [Revoke credentials](/products/identity/revocation).

## Troubleshooting

| Error | Likely cause |
| - | - |
| `The presentation does not contain an enveloped SD-JWT` | Not an `SD_JWT_VC` program, or not a `Compliant` result. |
| `Untrusted issuer: …` | `iss` is not in `trustedIssuers`. Compare it exactly, including the `did:web:` prefix. |
| `Verify Error: Invalid JWT Signature` | The issuer key set has no key matching the header `kid` (check the DID document or JWKS), the token was altered, or the KB-JWT was not signed by `cnf.jwk`. |
| `Key Binding JWT not exist` | You sent a nonce, the credential has `cnf.jwk`, but the token has no KB-JWT. Reject. |
| `Verify Error: Invalid Nonce` | KB-JWT `nonce` differs from the one you issued: a replay, or the wrong session's nonce. |
| `KB-JWT aud mismatch: …` | The presentation was made for a different `programId`. |
| `KB-JWT is too old` / `Verify Error: JWT is not yet valid` | KB-JWT `iat` is outside your window. Check your server clock, or adjust `maxKbAgeSeconds` / `skewSeconds`. |
| `Invalid sd_hash in Key Binding JWT` | Disclosures were added or removed after the holder signed. |
| `Missing required claim keys: …` | A field you required was not disclosed. Use dotted paths for nested fields (`address.city`). |
| `Unexpected vct: …` | The credential is a different type than you expected. |
| `Verify Error: JWT is expired` | The credential's `exp` has passed. |
| `Status is not valid` | The credential is revoked (only with `checkStatus: true`). |
| `Status List JWT verification failed: …` | The status list could not be fetched or its signature did not verify. |

## References

* [Selective Disclosure for JWTs (SD-JWT)](https://datatracker.ietf.org/doc/draft-ietf-oauth-selective-disclosure-jwt/): token format, disclosures, KB-JWT, `sd_hash`.
* [SD-JWT-based Verifiable Credentials (SD-JWT VC)](https://datatracker.ietf.org/doc/draft-ietf-oauth-sd-jwt-vc/): `vct`, `cnf`, `status`, `dc+sd-jwt` media type.
* [Token Status List](https://datatracker.ietf.org/doc/draft-ietf-oauth-status-list/): revocation.
* [VC Data Model 2.0: Enveloped Verifiable Credentials](https://www.w3.org/TR/vc-data-model-2.0/#enveloped-verifiable-credentials): the `data:` URL wrapper.
* [did:web method](https://w3c-ccg.github.io/did-method-web/): resolving `did:web` issuers.


# What data do you need?
Source: https://docs.air3.com/products/identity/what-data

Choose the smallest set of credential claims your verification decision needs, then align your schema, disclosure settings, and verification program.

Start with the decision your application needs to make. A credential should provide evidence for that decision, rather than become a copy of the issuer's customer record.

For example: “Grant a discount to a current Gold member” needs proof of membership tier and validity. It usually does not need the member's name, purchase history, or points balance.

## Choose the claims

Write down the decision, identify an issuer you trust to attest to it, and select the fields needed to evaluate it. These are illustrative schema choices, not built-in AIR fields:

| Decision | Claims to consider | Data to leave out unless needed |
| - | - | - |
| Grant a membership benefit | `tier`, `brandId`, credential expiry | Membership number, points history |
| Accept a recent KYC result | `kycLevel`, `verifiedAt`, trusted issuer | Document images, full address |
| Check adult eligibility | An issuer-attested `isOver18` boolean | Date of birth |

The issuer must have a reliable source for each claim. If a verifier needs `isOver18`, the issuer must calculate and sign that fact; requesting it does not make AIR derive it from a date of birth.

Use [What are schemas](/products/identity/schema-overview) to define field names, types, and validation. Keep issuer and verifier teams aligned on what each value means.

## Decide what to disclose

With SD-JWT, an issuer can make individual claims selectively disclosable. The holder approves the presentation, and the verifier requests the fields its decision needs.

Check the issuer's disclosure configuration as well as the verifier's request. Claims that are not selectively disclosable remain visible in the signed credential. Requesting fewer fields does not hide those claims or credential metadata.

An SD-JWT presentation reveals the value of a disclosed claim. For an age gate, a signed `isOver18` claim avoids revealing the date of birth; it is not a zero-knowledge calculation over a hidden birth date. See [Other ways to verify](/products/identity/credential-formats) if you need predicate proofs.

## Set validity rules

Decide how long the evidence should remain acceptable. A recent KYC check and a permanent course completion can have different freshness requirements.

* Set credential expiry where status is time-limited.
* Define how your application evaluates dates such as `verifiedAt`.
* Plan revocation when a signed fact becomes invalid, and enable the relevant status checks in verification.
* Treat revocation and data deletion as separate operations.

See [Managing your credentials](/products/identity/revocation) for revocation and replacement.

## Configure and verify

Configure your Verification Program with the credential format, accepted issuers, and required claims. In your SDK flow, request the intended disclosure fields and use the returned evidence to evaluate your application's rules.

Before granting access or a benefit, verify the returned presentation on your backend. Follow [Verifying credentials](/products/identity/verify) for the program setup and [Verify with SD-JWT](/products/identity/verify-sd-jwt) for the backend checks.


# What is AIR Identity
Source: https://docs.air3.com/products/identity/what-is-air-identity

Use and share verified identity data through credentials that users carry and present across applications.

AIR Identity provides infrastructure for using and sharing verified identity data. Businesses turn facts they have checked into credentials, and receiving applications verify the evidence they need. The user carries these credentials in their AIR Account and approves what is shared.

Identity data includes more than a name or a completed identity check. It can describe membership, qualifications, residency, purchase activity, or other attributes an issuer can attest to. Any workflow that needs to use or share those verified facts is a potential AIR Identity use case.

## How the participants work together

* **The issuer** checks the source data and signs a credential that attests to the relevant facts.
* **The holder** carries the credential and approves its use.
* **The verifier** decides which claims and issuers it accepts, checks the evidence, and applies its own eligibility rules.

One business can be an issuer, a verifier, or both. A signed credential lets a receiving application check an issuer's claim without connecting directly to that issuer's customer database. Whether the claim qualifies someone for a benefit remains the verifier's decision.

## Share the evidence a decision needs

Schemas define the claims a credential carries. Verification programs define what an application requests and accepts. With selective disclosure configured, a customer can share the relevant claims rather than the entire credential.

Issuers keep their source records and signing keys. Credential payloads are encrypted before storage; receiving applications handle the claims disclosed to them.

## What you can build

Use AIR Identity wherever verified identity data informs a decision or needs to move between participants:

* **Onboarding and reusable checks:** present evidence of a completed identity check to an application that accepts the issuer.
* **Access and eligibility:** establish membership, age eligibility, residency, or qualifications for a service.
* **Verified data sharing:** let a user present relevant attributes to another business without a direct connection to the issuer's source database.
* **Personalized experiences and benefits:** use accepted customer attributes to determine offers, prices, or entitlements.
* **Agent interactions:** let an authorized agent use approved identity evidence on the user's behalf. See [AIR Agent](/products/agents/what-is-air-agents).

The receiving application defines which claims and issuers it trusts. A credential provides evidence for that decision; actions such as spending money require their own authority.

Start with [What are credentials](/products/identity/credentials-flow) and [What are schemas](/products/identity/schema-overview), or explore [Use cases](/products/identity/use-cases).


# Connect with other modules
Source: https://docs.air3.com/products/loyalty/beyond-loyalty

Explore the identity, agent, and wallet guides that support experiences alongside AIR Loyalty.

AIR Loyalty combines credentials for portable customer status with points for funded rewards. AIR Identity provides the credential foundation; explore the other guides when your experience also involves agents or wallet transactions. Points redemption and settlement follow the loyalty program's agreed integration.

<CardGroup>
  <Card title="AIR Identity" icon="id-card" href="/products/identity/credentials-flow">
    Understand credential issuance, selective disclosure, and verification beneath loyalty tiers.
  </Card>

  <Card title="AIR Agent" icon="robot" href="/products/agents/use-cases">
    Explore agents presenting a customer's accepted membership or tier for a benefit.
  </Card>

  <Card title="AIR Money" icon="wallet" href="/products/money/how-it-works">
    Explore smart accounts and wallet transactions for your app's payment experience.
  </Card>
</CardGroup>


# Loyalty as a Business
Source: https://docs.air3.com/products/loyalty/business

Explore how a loyalty program can grow from a cost center into a business connecting customers, brands, and merchants.

A loyalty program can do more than fund discounts. With useful rewards and participating partners, it can become a business in its own right: connecting customers with offers, helping merchants reach an audience, and managing a reward economy.

AIR Loyalty brings together [credentials](/products/loyalty/how-it-works) that prove customer status and [points](/products/loyalty/loyalty-points) for funded rewards. These serve different parts of that business: credentials establish eligibility, while points connect earning to spending and settlement.

## From cost center to business

A program run as a cost center is measured mainly by the rewards it pays out and the retention those rewards generate. A loyalty business also asks who benefits from its audience, who funds the offers, and how the program earns revenue from the value it creates.

| Program focus | Business opportunity |
| - | - |
| Fund discounts from your own budget | Bring in partners that fund campaigns to reach relevant customers. |
| Recognize status only within your brand | Let participating brands offer benefits to verified members. |
| Give points a narrow redemption path | Build useful spending options across an approved merchant or reward network. |
| Run isolated promotions | Develop repeatable campaigns with clear funding, redemption, and settlement. |

Merchant-funded campaigns, campaign management fees, or agreed commercial arrangements can be ways to build the business. These are program design opportunities; the model and terms are agreed with the participating partners.

## Make membership valuable to partners

Loyalty credentials let a customer prove membership, tier, or achievement to a participating brand. The receiving partner chooses which issuers and status it accepts, then applies its own offer.

This creates an opportunity to build partnerships around a relevant audience. For example, a merchant could offer a benefit to verified Gold members or fund a points campaign for that group. Your program connects the audience to the offer without giving the merchant direct access to your loyalty database.

## Give rewards places to be spent

A reward economy needs useful redemption. Customers should understand what they can earn, where they can spend it, and when campaign rewards expire.

An [AIR Shop-style experience](/products/loyalty/use-cases#stable-loyalty-points-and-air-shop) can give rewards a clear destination. A partner could build a related experience around its own approved checkout or catalog. The program brings together earning rules, campaign funding, customer balances, and settlement for the merchant or partner.

Explore [AIR Shop](https://air3.shop), or read about [issuing](/products/loyalty/issuing-points) and [spending](/products/loyalty/spending-points) loyalty points.

## Reuse campaign funding through breakage

When expiring campaign rewards go unused, they produce **breakage**. Where the campaign supports recovery, eligible backing can return to its budget and fund future rewards.

That can make a campaign budget go further. It is separate from revenue earned through partner arrangements, and it does not make all unspent points profit. Keep outstanding reward commitments, redeemed value, expired rewards, and recovered funding distinct.

See [Breakage and budget recycling](/products/loyalty/loyalty-points#breakage-and-budget-recycling) for an example. Clear expiry and useful rewards remain central to the customer experience.

## Measure the program as a business

Look beyond points issued. Measure customer activity and redemption, partner-funded campaigns, commercial revenue, reward costs, and operating costs. Compare those results to the behavior you want to encourage, such as repeat purchases or visits to participating merchants.

A program becomes a sustainable business when the value it creates for customers and partners supports its costs. Stable points or breakage alone do not guarantee that outcome.

[Talk to the AIR team](https://air3.com/partner-with-us) to explore the reward model, partner network, and integration that fit your business.


# Issuing and verifying credentials
Source: https://docs.air3.com/products/loyalty/developers

Build portable loyalty tier credentials with AIR Kit: schema, on-demand issuance from your loyalty engine, and tier verification at the point of benefit.

Issue loyalty tier and milestone credentials from your loyalty engine, and let partner apps verify them without an API integration with you.

<Info>
  This guide issues and verifies loyalty **credentials**. A `totalPoints` claim records an issuer's statement about accumulated points; it does not create a spendable points balance. For rewards with funding and redemption, see [Issuing loyalty points](/products/loyalty/issuing-points) and [Spending loyalty points](/products/loyalty/spending-points).
</Info>

## What you can build

* **Tier credentials** — Issue a "Gold Member" or "VIP" badge that upgrades or revokes automatically as status changes
* **Milestone badges** — Issue a credential when a user reaches 1,000 points, 10 purchases, or any event-driven threshold
* **Cross-platform loyalty** — Allow partner apps to accept your loyalty credentials as proof of status, no API integration required
* **Zero-friction issuance** — Trigger credential issuance from your loyalty engine backend; the user doesn't need to open a wallet or take any action

## Architecture

```mermaid theme={null}
graph TD
    A["User Action\ne.g. purchase, referral, check-in"] --> B[Your Loyalty Engine]
    B -->|Milestone reached| C[On-demand issuance]
    C --> D[AIR Kit / Moca Chain]
    D --> E[Loyalty Credential in User's AIR Account]

    E --> F{User presents credential}
    F -->|At your app| G[Tier unlock / reward]
    F -->|At partner app| H[Cross-brand benefit]
    F -->|At any verifier| I[Gated access / discount]
```

## Recommended schema

Create this schema in the [AIR Kit Dashboard](https://developers.sandbox.air3.com/dashboard) under **Issuer → Schema Builder**.

```json theme={null}
{
  "title": "Loyalty Tier",
  "description": "Brand loyalty membership tier credential",
  "properties": {
    "tier": {
      "type": "string",
      "enum": ["Bronze", "Silver", "Gold", "Platinum"],
      "description": "Current loyalty tier"
    },
    "totalPoints": {
      "type": "number",
      "description": "Lifetime points accumulated"
    },
    "memberSince": {
      "type": "string",
      "format": "date",
      "description": "Date of first loyalty enrollment"
    },
    "brandId": {
      "type": "string",
      "description": "Issuing brand identifier"
    }
  },
  "required": ["tier", "totalPoints", "brandId"]
}
```

## Implementation

### Step 1 — Issue a loyalty credential on milestone

Use **On-demand issuance** to issue silently when a backend event fires. The user's session is not required.

```javascript theme={null}
// loyalty-engine.js
const { getPartnerJwt } = require('./lib/jwt'); // see Partner Authentication
// issuer-controlled helpers backed by your signing keys
const { buildVc, signVc, encryptToHolder } = require('./lib/credential');

const BASE_URL = 'https://api.sandbox.mocachain.org/v1'; // swap for prod URL on launch

async function issueLoyaltyCredential({ userEmail, tier, totalPoints, memberSince }) {
  const token = await getPartnerJwt(); // JWT must include scope: "issue"

  // Resolve the member's AIR Account
  const init = await fetch(`${BASE_URL}/auth/initialize-user`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', 'x-partner-auth': token },
    body: JSON.stringify({ email: userEmail }),
  }).then((r) => r.json());

  // Build, sign (SD-JWT VC), and encrypt the credential to the holder
  const schemaId = process.env.LOYALTY_CRED_ID; // Dashboard → Issuer → Programs
  const vc = buildVc({
    holderDid: init.did,
    schemaId,
    credentialSubject: { tier, totalPoints, memberSince, brandId: process.env.BRAND_ID },
  });
  const encrypted = encryptToHolder(signVc(vc), init.publicKey);

  // Store the encrypted envelope in DStorage
  const res = await fetch(`${BASE_URL}/dstorage/vcs`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', 'x-partner-auth': token },
    body: JSON.stringify({
      holderDid: init.did,
      schemaId,
      expiresAt: vc.expirationDate,
      data: encrypted.encryptedData,
      iv: encrypted.iv,
      authTag: encrypted.authTag,
      encryptedKey: encrypted.dataEncPublicKey,
      externalId: vc.id,
    }),
  });
  if (!res.ok) throw new Error(`Issuance failed: ${res.status}`);
  const { storagePath } = await res.json();
  return storagePath;
}

// Hook into your existing loyalty event pipeline
loyaltyEngine.on('tier:upgrade', async ({ userEmail, newTier, totalPoints }) => {
  const storagePath = await issueLoyaltyCredential({
    userEmail,
    tier: newTier,
    totalPoints,
    memberSince: new Date().toISOString().split('T')[0],
  });
  console.log(`Loyalty credential issued: ${storagePath}`);
});
```

### Step 2 — Verify loyalty tier at point of benefit

On your frontend, verify the user holds the required tier before granting access or rewards.

```javascript theme={null}
// loyalty-gate.js  (frontend)
import { AirService, BUILD_ENV } from "@mocanetwork/airkit";

const airService = new AirService({ partnerId: process.env.PARTNER_ID });
await airService.init({ buildEnv: BUILD_ENV.SANDBOX }); // or BUILD_ENV.PRODUCTION

async function checkLoyaltyTier() {
  const result = await airService.verifyCredential({
    programId: process.env.LOYALTY_VERIFY_PROGRAM_ID, // Dashboard → Verifier → Programs
  });
  // Your verifier program rule: tier === "Gold" (or higher)
  return result.status === 'COMPLIANT';
}

const hasGoldStatus = await checkLoyaltyTier();
if (hasGoldStatus) {
  unlockPremiumContent();
} else {
  showUpgradePrompt();
}
```

## Key patterns

| Pattern | Reissue behavior | When to Use |
| - | :-: | - |
| Tier upgrade | Revoke + reissue | Always revoke old credential and issue new one |
| One-time milestone badge | Skip if exists | Don't re-issue if credential already held |
| Time-boxed VIP | Set `expirationDate` in subject | Seasonal or campaign-based access |
| Retroactive bulk issuance | Loop `issueLoyaltyCredential` | Migrating existing loyalty members |

## Issuance result

Issuance completes in \~1–4 seconds and returns a `storagePath` once the encrypted credential is stored in DStorage. Use that result to confirm success to the user — no status polling required. The credential is immediately available for the member to present at any verifier.

## Examples

<CardGroup>
  <Card title="VIP Status Portability — live demo" icon="play" href="https://air-bd-v2.netlify.app/try-it-live/member-discount">
    Present airline Gold status at a partner café. The café never sees the membership number.
  </Card>

  <Card title="VIP Status Portability — Issuer" icon="github" href="https://github.com/MocaNetwork/air-examples/tree/main/vip-status-portability/issuer">
    Airline loyalty app: issues tier credential; user carries status to partner brands.
  </Card>

  <Card title="VIP Status Portability — Verifier" icon="github" href="https://github.com/MocaNetwork/air-examples/tree/main/vip-status-portability/verifier">
    Hotel chain app: verifies tier and grants equivalent perks (e.g. room upgrade, lounge).
  </Card>
</CardGroup>

## Next steps

<Columns>
  <Card title="On-demand Issuance — Concepts" icon="book" href="/products/identity/issuing-credentials#direct-issuance">
    Understand when and why to use On-demand issuance.
  </Card>

  <Card title="On-demand Issuance — API" icon="code" href="/api-reference/issuance-api">
    Full endpoint reference with error codes.
  </Card>

  <Card title="Schema Use Cases" icon="list" href="/products/identity/schema-use-cases">
    More schema examples including membership and event pass.
  </Card>

  <Card title="Verifying Credentials" icon="shield-check" href="/products/identity/verify">
    SDK verification flow reference.
  </Card>
</Columns>


# Loyalty credentials
Source: https://docs.air3.com/products/loyalty/how-it-works

Understand signed proof of membership, tier, and achievement, and how it differs from spendable loyalty points.

A loyalty credential is an issuer-signed statement about a customer's membership, tier, or achievement. The customer carries it in their AIR Account and presents it to a partner that accepts the issuer. Your loyalty engine determines eligibility; AIR provides credential issuance and verification.

A credential can attest that a customer reached Gold or earned a milestone. A field such as `totalPoints` can describe lifetime points earned, but it is a signed snapshot, not a live spendable balance. Use [Loyalty points](/products/loyalty/loyalty-points) for funded rewards, redemption, and settlement.

## From loyalty event to benefit

<Steps>
  <Step title="Your loyalty engine confirms a change">
    A purchase, visit, or milestone changes the customer's status. Your backend decides what the customer has earned using your existing rules. Define the facts partners need in a credential schema, such as tier and issuing brand.
  </Step>

  <Step title="Your issuer backend creates the credential">
    Your backend signs the credential with your issuer keys, encrypts it to the holder, and stores the encrypted envelope in DStorage. Direct issuance can run from your event pipeline without an active user session. Resolve the correct recipient and deduplicate repeated events; see [Issuing on a tier change](/products/loyalty/loyalty-points-issuance).
  </Step>

  <Step title="The customer presents their status">
    At a partner's checkout, check-in, or access screen, the customer signs in with AIR and approves the requested disclosure. The partner configures which issuers and loyalty claims its Verification Program accepts.
  </Step>

  <Step title="The partner verifies and applies its benefit rules">
    The partner checks the presented credential and its validity, then evaluates the tier or milestone against its own offer. Verify the returned presentation on the partner's backend before granting the benefit. Partners can check the credential without a direct integration to your loyalty database.
  </Step>
</Steps>

## Keep status current

A credential is a signed snapshot, not a live view of your loyalty database. When a tier changes, revoke the previous credential and issue a replacement. For seasonal status, set an expiry. Make sure partner verification includes the status and freshness checks the benefit requires.

A partner does not need a full points ledger for a tier benefit. Request only the necessary claims and configure selective disclosure accordingly. Credential metadata may still identify or link the interaction; selective disclosure is not anonymity.

<Info>
  The documented direct issuance flow does not bind credentials to a holder key, so their presentations are bearer presentations. Use SDK issuance when holder binding is required. See [Issuing credentials](/products/identity/issuing-credentials) and [Verify with SD-JWT](/products/identity/verify-sd-jwt).
</Info>

## Choose your next step

* [Use cases](/products/loyalty/use-cases) — explore points campaigns alongside tier and milestone benefits.
* [Issuing and verifying credentials](/products/loyalty/developers) — follow the existing schema and integration walkthrough.
* [Managing your credentials](/products/identity/revocation) — plan revocation and replacement.


# Connect your agent
Source: https://docs.air3.com/products/loyalty/integrating-using-ai

Add the AIR docs MCP server to your agent, then start building.

## Connect via MCP

Choose your tool below and add the AIR documentation server:

```text theme={null}
https://docs.air3.com/mcp
```

<Tabs>
  <Tab title="Claude">
    <Steps>
      <Step title="Add the Moca Network MCP server to Claude">
        1. Navigate to the [Connectors](https://claude.ai/settings/connectors) page in the Claude settings.
        2. Select **Add custom connector**.
        3. Add the Moca Network MCP server:
           * Name: `MocaNetwork`
           * URL: `https://docs.air3.com/mcp`
        4. Select **Add**.
      </Step>

      <Step title="Access the MCP server in your chat">
        1. When using Claude, select the attachments button (the plus icon).
        2. Select the MocaNetwork MCP server.
        3. Ask Claude a question about Moca Network or AIR Kit.
      </Step>
    </Steps>

    See the [Model Context Protocol documentation](https://modelcontextprotocol.io/docs/tutorials/use-remote-mcp-server#connecting-to-a-remote-mcp-server) for more details.
  </Tab>

  <Tab title="Claude Code">
    <Steps>
      <Step title="Add the MCP server to Claude Code">
        Run the following command:

        ```bash theme={null}
        claude mcp add --transport http MocaNetwork https://docs.air3.com/mcp
        ```
      </Step>

      <Step title="Test the connection">
        Verify the connection by running:

        ```bash theme={null}
        claude mcp list
        ```
      </Step>
    </Steps>

    See the [Claude Code documentation](https://docs.anthropic.com/en/docs/claude-code/mcp#installing-mcp-servers) for more details.
  </Tab>

  <Tab title="Cursor">
    <Steps>
      <Step title="Open MCP settings">
        1. Use <kbd>Command</kbd> + <kbd>Shift</kbd> + <kbd>P</kbd> (<kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>P</kbd> on Windows) to open the command palette.
        2. Search for "Open MCP settings".
        3. Select **Add custom MCP**. This opens the `mcp.json` file.
      </Step>

      <Step title="Configure the Moca Network MCP server">
        In `mcp.json`, add:

        ```json theme={null}
        {
          "mcpServers": {
            "MocaNetwork": {
              "url": "https://docs.air3.com/mcp"
            }
          }
        }
        ```
      </Step>

      <Step title="Test the connection">
        In Cursor's chat, ask "What tools do you have available?" Cursor should show the MocaNetwork MCP server as an available tool.
      </Step>
    </Steps>

    See the [Cursor documentation](https://docs.cursor.com/en/context/mcp#installing-mcp-servers) for more details.
  </Tab>

  <Tab title="VS Code">
    <Steps>
      <Step title="Create MCP configuration">
        Create a `.vscode/mcp.json` file in your project root.
      </Step>

      <Step title="Configure the Moca Network MCP server">
        In `.vscode/mcp.json`, add:

        ```json theme={null}
        {
          "servers": {
            "MocaNetwork": {
              "type": "http",
              "url": "https://docs.air3.com/mcp"
            }
          }
        }
        ```
      </Step>
    </Steps>

    See the [VS Code documentation](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) for more details.
  </Tab>
</Tabs>

For another MCP-compatible tool, add the URL as a remote HTTP MCP server in its connection settings.

## Try your first prompt

Once connected, ask your agent to look up the docs and help with a specific task:

```text theme={null}
Use the AIR docs MCP server to help me add AIR Kit login to my app.
Check my framework and existing authentication, then explain the setup
and changes before implementing them.
```

You can also ask about credential issuance and verification, wallet transactions, or integration errors. Include your framework and what you have already built.

## Choose your setup

| Option | What it provides | When to use it |
| - | - | - |
| **Docs MCP** | Searchable AIR documentation, SDK guides, and API references. | Start here for current reference material. |
| **AIR skill** | Integration workflows and checks for setup, authentication, and common errors. | Add alongside MCP for guidance while building. |
| **Static docs** | Documentation files you attach or index in your tool. | Use when your tool cannot connect through MCP; refresh the files as docs change. |

Your agent uses these resources to plan, write, and review integration code. Live AIR operations run through your application's configured account, authentication, and programs.

## Add the AIR skill (optional)

For tools that support [Agent Skills](https://agentskills.io/home), run:

```bash theme={null}
npx skills add https://docs.air3.com
```

Select your agent in the CLI to install the skill.

<Accordion title="Before issuing or verifying credentials">
  Ask your agent to confirm these prerequisites before generating application code:

  * Your partner's public JWKS endpoint is reachable over HTTPS.
  * The exact JWKS URL is registered in the Developer Dashboard.
  * Your JWT signing key stays server-side, and its `kid` matches a published JWKS key.

  Follow [JWKS endpoint setup](/get-started/authentication/jwks-endpoint), then use the [issuance](/products/identity/issuing-credentials) or [verification](/products/identity/verify) guide for your flow.
</Accordion>

<Accordion title="Use static documentation files">
  ## Static docs files

  If your AI tool does not support MCP yet, you can use one of Moca Network's static documentation files instead.

  <Warning>
    Static files are snapshots and may not include the latest updates. Use MCP when possible for always-current docs.
  </Warning>

  ## Which file should I use?

  * **`llms.txt`** — A curated overview of Moca Network. Use it to route an agent to the right docs, understand product structure, and choose the right integration path.
  * **`llms-full.txt`** — A full static snapshot of the documentation. Use it when your tool needs more exhaustive reference material in one file.

  ## Setup with Cursor

  <Steps>
    <Step title="Open docs settings">
      Go to **Settings** → **Features** → **Docs**.
    </Step>

    <Step title="Add the overview file">
      Click **Add new doc** and paste: `https://docs.air3.com/llms.txt`
    </Step>

    <Step title="Optionally add the full snapshot">
      If your agent needs deeper static reference coverage, add: `https://docs.air3.com/llms-full.txt`
    </Step>

    <Step title="Reference in chat">
      Use **@docs** → **Moca** in your AI chat to reference the documentation.
    </Step>
  </Steps>

  ## Setup with Claude Desktop

  <Steps>
    <Step title="Download the overview file">
      Download the curated overview from: [https://docs.air3.com/llms.txt](https://docs.air3.com/llms.txt)
    </Step>

    <Step title="Optionally download the full snapshot">
      Download the full documentation snapshot from: [https://docs.air3.com/llms-full.txt](https://docs.air3.com/llms-full.txt)
    </Step>

    <Step title="Add to your project">
      Save one or both files in your project directory or another known location on your system.
    </Step>

    <Step title="Reference in chat">
      Drag and drop the file into your Claude Desktop chat, or use the attachment button to upload it. Claude will then have access to the uploaded Moca Network documentation context for that conversation.
    </Step>
  </Steps>
</Accordion>


# Issuing loyalty points
Source: https://docs.air3.com/products/loyalty/issuing-points

Reward purchases and customer activity with points from a funded AIR loyalty campaign.

Issue loyalty points when a customer completes a qualifying action, such as a purchase, or distribute rewards to a selected audience. Your business decides what earns points; the campaign connects those rewards to a funded budget and clear spending rules.

## How issuing points works

<Steps>
  <Step title="Set up a funded campaign">
    Define the audience, campaign budget, and where the rewards can be spent. Choose the earning rules and expiry for campaign rewards.
  </Step>

  <Step title="Reward eligible activity">
    Use confirmed purchases, milestones, or other qualifying events to allocate points. A campaign can also distribute rewards to a selected group of customers.
  </Step>

  <Step title="Show customers what they earned">
    Make the balance, eligible redemption options, and expiry visible so customers know how to use their rewards.
  </Step>

  <Step title="Manage the campaign budget">
    Track issued, redeemed, outstanding, and expired rewards. Where the campaign supports it, recover eligible backing from expired rewards and reuse it for future distributions.
  </Step>
</Steps>

## Points and credentials work together

A loyalty credential can prove that a customer qualifies for an offer, such as a Gold-member bonus. The points campaign then determines the reward they receive. Issuing or revoking a credential does not itself add or remove spendable points.

See [Loyalty credentials](/products/loyalty/how-it-works) for status and eligibility, and [Loyalty points](/products/loyalty/loyalty-points) for the reward model.

## Build your loyalty campaign

[Talk to the AIR team](https://air3.com/partner-with-us) to learn about setting up a campaign, funding, and the integration that fits your business.

Next, see [Spending loyalty points](/products/loyalty/spending-points) or explore the [use cases](/products/loyalty/use-cases).


# Loyalty points
Source: https://docs.air3.com/products/loyalty/loyalty-points

Understand stable loyalty points, campaign rewards, redemption, and how expired rewards can return value to a campaign budget.

Loyalty points represent reward value a customer can earn and spend under a program's rules. A points program needs funding, a balance, redemption rules, and settlement. A [loyalty credential](/products/loyalty/how-it-works) instead proves membership, tier, or achievement; it does not maintain a spendable balance.

## Stable points and campaign rewards

AIR's points design uses Spree infrastructure. It separates the underlying stable-value points from the rewards allocated to a particular campaign.

| Concept | Role in a loyalty program |
| - | - |
| **Stable Points (SP)** | The underlying stable-value points. The documented design describes SP as backed 1:1 by USD8. |
| **AIR SP** | A shared AIR points rail intended for affiliate and campaign rewards. |
| **Branded SP** | A partner-specific points currency intended for a partner-owned reward ecosystem. |
| **Pending SP (pSP)** | Campaign rewards layered over SP, with expiry and rules defining where they can be redeemed. Spending eligible pSP settles the underlying SP. |
| **Campaign budget** | The funding and accounting behind reward allocation, redemption, expiry, and recycled value. |

The stable-value design concerns the backing of the points. It does not mean every campaign reward can be spent everywhere, lasts forever, or can be cashed out by a customer. The deployed backing, redemption value, and supported spend surfaces depend on the agreed implementation.

## From earning to spending

1. **Fund a campaign.** Establish its budget, eligible customers, earn rules, spend surfaces, and expiry.
2. **Issue rewards.** A qualifying purchase, activity, or batch distribution allocates points to a customer.
3. **Show usable value.** The customer sees their balance, where it is eligible, and when campaign rewards expire.
4. **Redeem.** The customer spends eligible rewards at an approved checkout or redemption surface.
5. **Settle and reconcile.** Record the redeemed value, merchant or partner settlement, outstanding rewards, and remaining budget.

See [Issuing loyalty points](/products/loyalty/issuing-points) and [Spending loyalty points](/products/loyalty/spending-points) for the partner workflow.

## Breakage and budget recycling

**Breakage** is reward value that is issued but never redeemed. In an expiring pSP campaign, unused rewards can expire under the campaign's rules, and eligible backing can return to the campaign budget for future rewards.

For example, a campaign allocates **200 reward units**. Customers redeem **120**, and the remaining **80** expire unused. If the campaign supports recovery, the backing eligible for those 80 units can be recycled into its budget. This is an illustrative accounting example; it does not set a currency conversion, fee, or commercial entitlement.

Expiry belongs to the campaign reward rules. The documented design describes Branded SP as permanent; do not apply pSP expiry automatically to underlying SP or Branded SP. Budget recovery also needs to be recorded separately from redemptions and merchant settlement.

Explain expiry and eligible spending clearly before a customer earns. Breakage can help reuse a campaign budget, but it does not guarantee profit, yield, or campaign performance.

## Explore a points program

Visit [AIR Shop](https://air3.shop) to explore an AIR-owned redemption surface, or see [Use cases](/products/loyalty/use-cases) for campaign examples.

[Talk to the AIR team](https://air3.com/partner-with-us) to learn about the points model, funding, supported redemption options, and integration for your business.


# Issuing on a tier change
Source: https://docs.air3.com/products/loyalty/loyalty-points-issuance

Issue tiered loyalty credentials from your backend when users cross spend or activity thresholds — portable Gold and Platinum tiers across partner platforms.

This recipe walks through issuing a portable loyalty credential that users carry across your partner ecosystem. When a user crosses a tier threshold (e.g. Gold, Platinum), your backend issues a new credential automatically.

<Info>
  This recipe creates a tier credential, not spendable loyalty points. For funded campaign rewards, see [Issuing loyalty points](/products/loyalty/issuing-points).
</Info>

## What you'll build

1. A credential schema that encodes loyalty tier, lifetime points, and membership date.
2. A backend function that issues (or upgrades) the credential when a user crosses a tier boundary.
3. Issuer-signed, holder-encrypted credentials stored in DStorage.

## Prerequisites

* A published issuance program with a loyalty schema
* [Partner JWT](/get-started/authentication/sdk-auth) signing configured
* Issuer signing keys available to your backend

## Step 1: Design the credential schema

Create a schema in the Developer Dashboard (Issuer > Schemas) with fields like:

| Field | Type | Description |
| - | - | - |
| `tier` | string | Loyalty tier name (e.g. `"Gold"`, `"Platinum"`) |
| `lifetimePoints` | integer | Total points accumulated |
| `memberSince` | string | ISO date when membership started |
| `upgradedAt` | string | ISO date of the most recent tier upgrade |

See [Schema Creation](/products/identity/schema-creation) for full setup instructions.

## Step 2: Issue on tier upgrade

When your loyalty engine determines a user has crossed a tier boundary, resolve the recipient, then build, sign, encrypt, and store a fresh tier credential. Dedupe by recipient email + program ID and revoke the previous tier credential before reissuing.

<Warning>
  The recipient's email (passed to `initialize-user`) is the routing key that determines which AIR Account the credential lands in. Resolve it from the triggering event, and never reuse a partner, service, admin, or static email across recipients — every credential issued against that email lands in the same account.
</Warning>

```js theme={null}
const jwt = require("jsonwebtoken");
const fs = require("fs");
// issuer-controlled helpers backed by your signing keys
const { buildVc, signVc, encryptToHolder } = require("./lib/credential");

const privateKey = fs.readFileSync("path/to/private.key");
const BASE_URL = process.env.API_BASE_URL || "https://api.sandbox.mocachain.org/v1";

function getPartnerJwt() {
  const now = Math.floor(Date.now() / 1000);
  return jwt.sign(
    // No email claim — the recipient is passed to initialize-user, not the JWT
    { partnerId: process.env.PARTNER_ID, scope: "issue", iat: now, exp: now + 300 },
    privateKey,
    { algorithm: "RS256", header: { kid: process.env.KEY_ID, typ: "JWT" } }
  );
}

async function issueLoyaltyCredential(recipientEmail, tierData) {
  const token = getPartnerJwt();

  // 1. Resolve or create the recipient's AIR Account
  const initRes = await fetch(`${BASE_URL}/auth/initialize-user`, {
    method: "POST",
    headers: { "Content-Type": "application/json", "x-partner-auth": token },
    body: JSON.stringify({ email: recipientEmail }),
  });
  if (!initRes.ok) throw new Error(`initialize-user failed: ${initRes.status}`);
  const { did, publicKey } = await initRes.json();

  // 2. Build, sign (SD-JWT VC), and encrypt the credential to the holder
  const schemaId = process.env.LOYALTY_CREDENTIAL_ID;
  const vc = buildVc({
    holderDid: did,
    schemaId,
    credentialSubject: {
      tier: tierData.tier,
      lifetimePoints: tierData.lifetimePoints,
      memberSince: tierData.memberSince,
      upgradedAt: new Date().toISOString(),
    },
  });
  const encrypted = encryptToHolder(signVc(vc), publicKey);

  // 3. Store the encrypted envelope in DStorage
  const storeRes = await fetch(`${BASE_URL}/dstorage/vcs`, {
    method: "POST",
    headers: { "Content-Type": "application/json", "x-partner-auth": token },
    body: JSON.stringify({
      holderDid: did,
      schemaId,
      expiresAt: vc.expirationDate,
      data: encrypted.encryptedData,
      iv: encrypted.iv,
      authTag: encrypted.authTag,
      encryptedKey: encrypted.dataEncPublicKey,
      externalId: vc.id,
    }),
  });
  if (!storeRes.ok) throw new Error(`dstorage/vcs failed: ${storeRes.status}`);
  return storeRes.json(); // { storagePath }
}
```

## Step 3: Trigger on purchase events

Wire the issuance into your purchase or activity pipeline:

```js theme={null}
async function onPurchaseComplete(userEmail, purchaseAmount) {
  const user = await getUserProfile(userEmail);
  const newPoints = user.lifetimePoints + calculatePoints(purchaseAmount);
  const newTier = resolveTier(newPoints);

  if (newTier !== user.currentTier) {
    const result = await issueLoyaltyCredential(userEmail, {
      tier: newTier,
      lifetimePoints: newPoints,
      memberSince: user.memberSince,
    });
    console.log(`Upgraded ${userEmail} to ${newTier}, storagePath: ${result.storagePath}`);
  }

  await updateUserProfile(userEmail, { lifetimePoints: newPoints, currentTier: newTier });
}
```

## Step 4: Let verifiers read the credential

Any partner in the ecosystem can verify the user's tier using [Credential Verification](/products/identity/verify). The user presents the credential (via AIR Kit SDK), and the verifier confirms tier status without accessing underlying purchase data.

## Duplicate handling

Dedupe by recipient email + program ID before issuing so an event replay can't fan out duplicate credentials. When a user upgrades tiers, revoke the previous tier credential before storing the new one. For one-time membership issuance, skip reissuance if a credential already exists for the user + schema.

## Next steps

* [Try it live](https://air-bd-v2.netlify.app/try-it-live/member-discount): present airline membership at a partner café

* [Loyalty for developers](/products/loyalty/developers) for a broader integration guide

* [Issuance API Reference](/api-reference/issuance-api) for endpoint details

* [Credential Verification](/products/identity/verify) to set up cross-partner verification


# Spending loyalty points
Source: https://docs.air3.com/products/loyalty/spending-points

Let customers redeem eligible loyalty points, with clear spending rules and settlement for the merchant or partner.

Customers spend loyalty points at a redemption surface approved for their program, such as AIR Shop or an agreed partner checkout. Campaign rules determine which rewards are eligible, what they can be used for, and when they expire.

## How spending points works

<Steps>
  <Step title="Find an eligible reward or checkout">
    Show customers where their points can be used. Eligibility depends on the points currency, campaign, participating merchant, and expiry rules.
  </Step>

  <Step title="Choose how to use the points">
    Show the points required and the reward or checkout discount they provide. Make any restrictions and remaining payment clear before confirmation.
  </Step>

  <Step title="Redeem and update the balance">
    After a successful redemption, apply the benefit and update the customer's available points. In the campaign pSP model, spending eligible rewards settles the underlying SP.
  </Step>

  <Step title="Settle with the merchant or partner">
    Record the redeemed value and settle according to the program's agreed arrangement. Merchant payout timing and terms are defined for the program.
  </Step>
</Steps>

## Unused rewards and breakage

Campaign rewards can expire if customers do not use them before the deadline. Where recovery is supported, eligible backing can return to the campaign budget for future rewards. This is separate from spending: expired points do not represent a sale or merchant redemption.

See [Breakage and budget recycling](/products/loyalty/loyalty-points#breakage-and-budget-recycling) for an example. Expiry applies to the campaign rewards; it does not mean all underlying points currencies expire.

## Explore a redemption experience

Visit [AIR Shop](https://air3.shop) to explore an AIR-owned redemption surface. Points must be eligible for the program and spend surface; testnet demo points cannot be spent there.

[Talk to the AIR team](https://air3.com/partner-with-us) to learn about supported redemption options and how a points program could work for your business.


# Use cases
Source: https://docs.air3.com/products/loyalty/use-cases

Explore stable loyalty points, AIR Shop-style rewards, campaign breakage, and portable membership benefits.

AIR Loyalty brings together two complementary ideas: points customers can spend and credentials that prove their status. Use points for funded rewards and redemption; use credentials for membership, tier, and milestone benefits.

## Stable loyalty points and AIR Shop

A stable-points program connects earning to a useful redemption experience. Customers earn rewards from eligible activity, see the value they can use, and spend at a participating surface under the program's rules.

[AIR Shop](https://air3.shop) is an AIR-owned redemption surface. An AIR Shop-style campaign gives customers a clear destination for their rewards. A partner could build a related experience around its own approved checkout or reward catalog, with earning and spending rules suited to its business.

The underlying SP design describes 1:1 USD8 backing. Campaign rewards can add restrictions and expiry on top of that infrastructure. Stable backing does not make every reward universally spendable; currency and campaign eligibility still apply.

## Campaign rewards with breakage

A partner could reward a qualifying purchase with campaign pSP that customers can spend before a stated expiry. The campaign sets the earn rule, eligible redemption options, and reward deadline.

As customers spend, redeemed value settles to the merchant or partner. Rewards that remain unused at expiry produce **breakage**. Where recovery is supported, eligible backing can return to the campaign budget and fund the next round of rewards.

For example, a campaign allocates **200 reward units**: **120 are redeemed**, while **80 expire unused**. The backing eligible for those 80 units may be recycled under the campaign's rules. This illustration does not promise a conversion rate, profit, or return.

Make the expiry visible when customers earn and when they check their balance. The goal is a useful reward experience; breakage is part of the campaign's accounting, not a guaranteed business outcome.

Read [Loyalty points](/products/loyalty/loyalty-points) for the concepts, then explore [issuing](/products/loyalty/issuing-points) and [spending](/products/loyalty/spending-points).

## Tier-based rewards

A loyalty credential can prove that a customer is a Gold member. A participating partner verifies the credential and grants its own perk or applies the tier to a campaign's earning rules.

The credential proves eligibility; the reward system determines the benefit and maintains any spendable balance. Each partner chooses which issuers and tiers it accepts.

The [member discount demo](https://air-bd-v2.netlify.app/try-it-live/member-discount) illustrates airline Gold status qualifying a customer for a café benefit. This is a credential example, separate from points redemption.

## Milestones and seasonal membership

Issue a credential for an achievement such as a tenth visit, or give seasonal membership a defined expiry. A partner can verify that evidence without connecting directly to your loyalty database.

Your loyalty engine remains the source of the qualifying event. Revoke and replace credentials when status changes, and track one-time benefit redemption separately from the credential itself.

See [Loyalty credentials](/products/loyalty/how-it-works) and [Issuing and verifying credentials](/products/loyalty/developers).

## Explore a program for your business

[Talk to the AIR team](https://air3.com/partner-with-us) about campaign design, funding, supported redemption surfaces, and integration options.


# What is AIR Loyalty
Source: https://docs.air3.com/products/loyalty/what-is-air-loyalty

Combine portable membership credentials with funded loyalty points for customer and partner rewards.

AIR Loyalty brings together customer status and rewards. It has two complementary parts: credentials that prove membership or achievement, and points that customers earn and spend under a program's rules.

## Loyalty credentials

A loyalty credential is an issuer-signed statement about membership, tier, or a milestone. Your loyalty engine determines the status and triggers issuance. A participating partner can verify that credential and apply its own benefit rules without a direct connection to your loyalty database.

A credential proves a claim. Even if it includes a points total, it does not maintain a live spendable balance.

## Loyalty points

Points represent reward value backed by a funded program. A campaign defines the earning rules, eligible spending options, and expiry for campaign rewards. Redemption connects customer spending to settlement for the merchant or partner.

AIR's points design uses stable-points infrastructure, with campaign rewards layered over it. Where a campaign supports recovery, unused rewards that expire can return eligible backing to the budget for future rewards.

## Build a loyalty experience

A credential can establish that a customer qualifies for a tier benefit; a points campaign can then determine what they earn or spend. Each flow has its own rules and responsibilities.

Start with [Loyalty credentials](/products/loyalty/how-it-works) and [Loyalty points](/products/loyalty/loyalty-points). Explore [Use cases](/products/loyalty/use-cases) and [Loyalty as a Business](/products/loyalty/business), or [talk to the AIR team](https://air3.com/partner-with-us) about your program.


# Advanced Functions (Beta)
Source: https://docs.air3.com/products/money/advanced-functions

Use AIR Kit's custom EIP-1193 RPC methods for advanced wallet operations — token swaps, DeFi actions, and smart account flows (Base chain, beta).

<Warning>
  Swap functionality, advanced DeFi operations are only supported on `Base` chain only.
</Warning>

### Swap operations (beta)

**air\_getSwapQuote**

```tsx theme={null}
const quote = await provider.request({
  method: "air_getSwapQuote",
  params: [
    {
      fromToken: string,
      toToken: string,
      fromAmount: string
    }
  ]
});
// Returns: swap quote data
```

**air\_sendSwapTransaction**

```tsx theme={null}
const txHash = await provider.request({
  method: "air_sendSwapTransaction",
  params: [
    {
      fromToken: string,
      toToken: string,
      fromAmount: string
    }
  ]
});
// Returns: string (transaction hash)
```

**air\_showSwapUI**

```tsx theme={null}
const txHash = await provider.request({
  method: "air_showSwapUI",
  params: []
});
// Returns: string (transaction hash)
```


# Connect with other modules
Source: https://docs.air3.com/products/money/beyond-money

Explore AIR Identity, Loyalty, and Agent guides alongside your AIR Money integration.

AIR Money provides smart accounts and wallet operations for signed-in AIR users. Explore the other modules when your app also needs verified claims, loyalty status, or agent interactions.

<CardGroup>
  <Card title="AIR Identity" icon="id-card" href="/products/identity/credentials-flow">
    Understand how users carry credentials and approve the claims they share.
  </Card>

  <Card title="AIR Loyalty" icon="gift" href="/products/loyalty/how-it-works">
    Explore portable loyalty status and verification at the point of benefit.
  </Card>

  <Card title="AIR Agent" icon="robot" href="/products/agents/how-it-works">
    Explore user-bound agents and merchant checkout. Checkout tokens and wallet transaction permissions are separate integration decisions.
  </Card>
</CardGroup>


# Built-in UI (Beta)
Source: https://docs.air3.com/products/money/builtin-ui

Open AIR Kit's hosted UI for token swap, send and receive flows, transaction history, and wallet management directly inside your dApp (beta).

## See it live

These partner demos show AIR wallet flows in a product:

* [Socials Money](https://socialhomedemo.vercel.app/): accounts, cards, and spend.
* [Creator Pay](https://creator-pay-air-wallet.vercel.app/): creator payouts, send, and cash-out.

## Swap interface

### showSwapUI()

Opens the AIR Kit swap interface, allowing users to exchange tokens directly within your application.

**Method Signature:**

```ts theme={null}
public async showSwapUI(options?: {
  initialFromToken?: TokenSymbol;
  fallbackFromToken?: TokenSymbol;
  initialToToken?: TokenSymbol;
  defaultSlippage?: number;
}): Promise<{
  txHash: `0x${string}`;
  from: Token & { amount: string };
  to: Token & { amount: string };
}>
```

Each token is identified by symbol and chain, not by a bare string:

```ts theme={null}
type TokenSymbol = { symbol: string; chainId: number };

type Token = TokenSymbol & { decimals: number; address: `0x${string}` };
```

| Option | Description |
| - | - |
| `initialFromToken` | Preferred token to swap from. Applied when the user holds a balance and the token is supported; otherwise the user's highest-value asset is selected. |
| `fallbackFromToken` | Token to show as the "from" side when the user holds no assets. |
| `initialToToken` | Preferred token to swap to. |
| `defaultSlippage` | Slippage tolerance in percent. Omitted or out-of-range values fall back to automatic slippage. |

**Returns:**

```ts theme={null}
{
  txHash: `0x${string}`;              // Transaction hash of the swap
  from: Token & { amount: string };   // Token sold, with the amount sold
  to: Token & { amount: string };     // Token bought, with the amount received
}
```

`from.amount` is what the user sold and `to.amount` is what they received.

<Warning>
  Both amounts are **base-unit integer strings** (smallest denomination), not human-readable decimals. Divide by `10 ** decimals` before displaying — printing `amount` directly shows `1000000` for 1 USDC.
</Warning>

**Usage:**

```ts theme={null}
import { formatUnits } from "viem";

try {
  const result = await airService.showSwapUI({
    initialFromToken: { symbol: "USDC", chainId: 8453 },
    defaultSlippage: 0.5,
  });

  const sold = formatUnits(BigInt(result.from.amount), result.from.decimals);
  const received = formatUnits(BigInt(result.to.amount), result.to.decimals);

  console.log("Swap completed! Transaction hash:", result.txHash);
  console.log(`Swapped ${sold} ${result.from.symbol}`);
  console.log(`Received ${received} ${result.to.symbol}`);
} catch (error) {
  console.error("Swap failed:", error);
}
```

**What happens during swap:**

1. Opens the swap interface
2. User selects token and amount to swap
3. User confirms the swap transaction
4. Returns the transaction hash upon successful completion

**Requirements:**

* User must be logged in

**Important Notes:**

* **Experimental feature**: This method is marked as experimental and may change in future versions
* **Chain support**: Currently only supported on Base network
* **User experience**: Opens a full swap interface with token selection, amount input, and slippage settings.
* **Advanced control**: For more control over the swap flow, use the RPC method `air_getSwapQuote` and `air_sendSwapTransaction` to specify exact token addresses, amounts, and slippage settings

## On-ramp interface

### showOnRampUI()

Opens the AIR Kit on-ramp interface, allowing users to purchase cryptocurrency with fiat currency.

**Method Signature:**

```ts theme={null}
public async showOnRampUI(options: {
  displayCurrencyCode: string;
  targetCurrencyCode?: string;
}): Promise<void>
```

**Parameters:**

```ts theme={null}
{
  displayCurrencyCode: string; // Fiat currency code (e.g., "USD", "EUR")
  targetCurrencyCode?: string; // Optional target cryptocurrency (e.g., "ETH", "USDC")
}
```

**Usage:**

```ts theme={null}
try {
  await airService.showOnRampUI({
    displayCurrencyCode: "USD",
    targetCurrencyCode: "USDC"
  });
  console.log("On-ramp interface opened");
} catch (error) {
  console.error("Failed to open on-ramp:", error);
}
```

**What happens during on-ramp:**

1. Opens the on-ramp interface
2. User selects payment method and amount
3. User completes the fiat-to-crypto purchase
4. Cryptocurrency is deposited to their wallet

**Requirements:**

* User must be logged in

**Important Notes:**

* **Experimental feature**: This method is marked as experimental and may change in future versions
* **No return value**: This method doesn't return a transaction hash as the purchase is handled by the on-ramp provider
* **Currency support**: Supported currencies depend on the on-ramp provider configuration


# How it works
Source: https://docs.air3.com/products/money/how-it-works

Understand how AIR login, chain-specific smart accounts, wallet transactions, and gas sponsorship fit together in your application.

AIR Money connects a user's AIR Account to smart account transactions in your app. Users sign in through AIR Kit, while your application chooses the transaction experience and the chains it supports.

## From sign-in to transaction

<Steps>
  <Step title="The user signs in">
    Initialize AIR Kit and let the user sign in to their AIR Account. Your app can then access the wallet provider for the signed-in user. Start with [AIR login](/get-started/quickstarts/login).
  </Step>

  <Step title="A smart account is available on the selected chain">
    AIR uses a smart account for blockchain interactions; its MPC wallet acts as the signer. Smart accounts are chain-specific. If the account is not deployed, AIR Kit can bundle deployment with the first transaction, or your app can deploy it explicitly and show progress. Deployment gas is sponsored by AIR Kit. See [Smart accounts](/products/money/smart-account).
  </Step>

  <Step title="Your app starts the wallet action">
    Use the EIP-1193 provider with your existing EVM tooling to read accounts, sign messages, and send transactions. You can build your own screens or use AIR Kit's [built-in wallet UI](/products/money/builtin-ui), currently marked beta, for supported send, receive, swap, and history flows.
  </Step>

  <Step title="Gas policy is checked and the transaction is submitted">
    Eligible operations can receive gas sponsorship under the partner's policy. Contract and function allowlists, budgets, and per-user limits determine eligibility. Operations outside the policy can require the user to pay gas. After submission, track confirmation before treating the action as complete.
  </Step>
</Steps>

## What your team controls

Your team chooses which wallet actions appear in the app, the enabled chains, and how to handle approval, submission, confirmation, and failures. Read [Supported chains](/products/money/supported-chains) before choosing a network.

A sponsored account deployment does not mean every later transaction is sponsored. For transaction subsidies, work with the AIR team to configure your paymaster policy; the current [Sponsoring gas](/products/money/paymaster) guide requires contacting the team to update settings.

For repeated actions, [session keys](/products/money/session-keys) provide scoped permissions that can reduce repeated approval prompts. They are an additional wallet flow, not permission for arbitrary transactions.

## Start building

* [Accounts and transactions](/products/money/provider-functions) — use the wallet provider and smart account methods.
* [React walkthrough](/products/money/wagmi-integration) — connect AIR Kit to a React app with wagmi.
* [Use cases](/products/money/use-cases) — explore the account and payment demos.


# Connect your agent
Source: https://docs.air3.com/products/money/integrating-using-ai

Add the AIR docs MCP server to your agent, then start building.

## Connect via MCP

Choose your tool below and add the AIR documentation server:

```text theme={null}
https://docs.air3.com/mcp
```

<Tabs>
  <Tab title="Claude">
    <Steps>
      <Step title="Add the Moca Network MCP server to Claude">
        1. Navigate to the [Connectors](https://claude.ai/settings/connectors) page in the Claude settings.
        2. Select **Add custom connector**.
        3. Add the Moca Network MCP server:
           * Name: `MocaNetwork`
           * URL: `https://docs.air3.com/mcp`
        4. Select **Add**.
      </Step>

      <Step title="Access the MCP server in your chat">
        1. When using Claude, select the attachments button (the plus icon).
        2. Select the MocaNetwork MCP server.
        3. Ask Claude a question about Moca Network or AIR Kit.
      </Step>
    </Steps>

    See the [Model Context Protocol documentation](https://modelcontextprotocol.io/docs/tutorials/use-remote-mcp-server#connecting-to-a-remote-mcp-server) for more details.
  </Tab>

  <Tab title="Claude Code">
    <Steps>
      <Step title="Add the MCP server to Claude Code">
        Run the following command:

        ```bash theme={null}
        claude mcp add --transport http MocaNetwork https://docs.air3.com/mcp
        ```
      </Step>

      <Step title="Test the connection">
        Verify the connection by running:

        ```bash theme={null}
        claude mcp list
        ```
      </Step>
    </Steps>

    See the [Claude Code documentation](https://docs.anthropic.com/en/docs/claude-code/mcp#installing-mcp-servers) for more details.
  </Tab>

  <Tab title="Cursor">
    <Steps>
      <Step title="Open MCP settings">
        1. Use <kbd>Command</kbd> + <kbd>Shift</kbd> + <kbd>P</kbd> (<kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>P</kbd> on Windows) to open the command palette.
        2. Search for "Open MCP settings".
        3. Select **Add custom MCP**. This opens the `mcp.json` file.
      </Step>

      <Step title="Configure the Moca Network MCP server">
        In `mcp.json`, add:

        ```json theme={null}
        {
          "mcpServers": {
            "MocaNetwork": {
              "url": "https://docs.air3.com/mcp"
            }
          }
        }
        ```
      </Step>

      <Step title="Test the connection">
        In Cursor's chat, ask "What tools do you have available?" Cursor should show the MocaNetwork MCP server as an available tool.
      </Step>
    </Steps>

    See the [Cursor documentation](https://docs.cursor.com/en/context/mcp#installing-mcp-servers) for more details.
  </Tab>

  <Tab title="VS Code">
    <Steps>
      <Step title="Create MCP configuration">
        Create a `.vscode/mcp.json` file in your project root.
      </Step>

      <Step title="Configure the Moca Network MCP server">
        In `.vscode/mcp.json`, add:

        ```json theme={null}
        {
          "servers": {
            "MocaNetwork": {
              "type": "http",
              "url": "https://docs.air3.com/mcp"
            }
          }
        }
        ```
      </Step>
    </Steps>

    See the [VS Code documentation](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) for more details.
  </Tab>
</Tabs>

For another MCP-compatible tool, add the URL as a remote HTTP MCP server in its connection settings.

## Try your first prompt

Once connected, ask your agent to look up the docs and help with a specific task:

```text theme={null}
Use the AIR docs MCP server to help me add AIR Kit login to my app.
Check my framework and existing authentication, then explain the setup
and changes before implementing them.
```

You can also ask about credential issuance and verification, wallet transactions, or integration errors. Include your framework and what you have already built.

## Choose your setup

| Option | What it provides | When to use it |
| - | - | - |
| **Docs MCP** | Searchable AIR documentation, SDK guides, and API references. | Start here for current reference material. |
| **AIR skill** | Integration workflows and checks for setup, authentication, and common errors. | Add alongside MCP for guidance while building. |
| **Static docs** | Documentation files you attach or index in your tool. | Use when your tool cannot connect through MCP; refresh the files as docs change. |

Your agent uses these resources to plan, write, and review integration code. Live AIR operations run through your application's configured account, authentication, and programs.

## Add the AIR skill (optional)

For tools that support [Agent Skills](https://agentskills.io/home), run:

```bash theme={null}
npx skills add https://docs.air3.com
```

Select your agent in the CLI to install the skill.

<Accordion title="Before issuing or verifying credentials">
  Ask your agent to confirm these prerequisites before generating application code:

  * Your partner's public JWKS endpoint is reachable over HTTPS.
  * The exact JWKS URL is registered in the Developer Dashboard.
  * Your JWT signing key stays server-side, and its `kid` matches a published JWKS key.

  Follow [JWKS endpoint setup](/get-started/authentication/jwks-endpoint), then use the [issuance](/products/identity/issuing-credentials) or [verification](/products/identity/verify) guide for your flow.
</Accordion>

<Accordion title="Use static documentation files">
  ## Static docs files

  If your AI tool does not support MCP yet, you can use one of Moca Network's static documentation files instead.

  <Warning>
    Static files are snapshots and may not include the latest updates. Use MCP when possible for always-current docs.
  </Warning>

  ## Which file should I use?

  * **`llms.txt`** — A curated overview of Moca Network. Use it to route an agent to the right docs, understand product structure, and choose the right integration path.
  * **`llms-full.txt`** — A full static snapshot of the documentation. Use it when your tool needs more exhaustive reference material in one file.

  ## Setup with Cursor

  <Steps>
    <Step title="Open docs settings">
      Go to **Settings** → **Features** → **Docs**.
    </Step>

    <Step title="Add the overview file">
      Click **Add new doc** and paste: `https://docs.air3.com/llms.txt`
    </Step>

    <Step title="Optionally add the full snapshot">
      If your agent needs deeper static reference coverage, add: `https://docs.air3.com/llms-full.txt`
    </Step>

    <Step title="Reference in chat">
      Use **@docs** → **Moca** in your AI chat to reference the documentation.
    </Step>
  </Steps>

  ## Setup with Claude Desktop

  <Steps>
    <Step title="Download the overview file">
      Download the curated overview from: [https://docs.air3.com/llms.txt](https://docs.air3.com/llms.txt)
    </Step>

    <Step title="Optionally download the full snapshot">
      Download the full documentation snapshot from: [https://docs.air3.com/llms-full.txt](https://docs.air3.com/llms-full.txt)
    </Step>

    <Step title="Add to your project">
      Save one or both files in your project directory or another known location on your system.
    </Step>

    <Step title="Reference in chat">
      Drag and drop the file into your Claude Desktop chat, or use the attachment button to upload it. Claude will then have access to the uploaded Moca Network documentation context for that conversation.
    </Step>
  </Steps>
</Accordion>


# Sponsoring gas
Source: https://docs.air3.com/products/money/paymaster

Sponsor gas with the AIR Kit Paymaster — granular controls for transaction subsidies, budget caps, and policy management for your dApp's users.

<Warning>
  To update your gas sponsorship settings, please contact us.
</Warning>

1. **Granular Sponsorship Controls**
   You have fine-grained control over which on-chain activities you sponsor.
   * **Sponsor Specific Contract Functions:** Whitelist transactions based on the specific function being called (via its `function selector`).
     * *Example:* A DeFi protocol could sponsor the `deposit` function but not the `withdraw` function.
   * **Sponsor A Specific Contract:** Whitelist all interactions with a particular smart contract address.
   * **Support for Atomic Batch Transactions:** The service can process a `UserOperation` containing multiple actions. The entire batch is treated as a single, atomic unit; if any one of the bundled actions fails the policy validation, the entire transaction is rejected, preventing partial execution and unintended gas spending.
2. **ERC-20 Paymaster Support**
   * For user operations that do not qualify for sponsorship, users can opt to pay gas fees using ERC-20 tokens, including MOCA, USDT, USDC, EURe, and others. For a complete list of supported tokens, please contact us.
3. **Powerful Policy & Budget Management**
   You can define comprehensive policies to govern their sponsorship activities and control costs.
   * **Multi-Chain Policy Configuration:** Define and manage entirely separate sponsorship policies and allowlists for each supported blockchain (e.g., Ethereum, Polygon, Base).
   * **Set Granular Spending Limits:** Establish robust budgets with different scopes and reset intervals (daily, weekly, monthly):
   * **Global Limit:** A total budget for the entire policy.
   * **Per-User Limit:** A spending cap for each individual user.
   * **Control Transaction Costs:** Set a maximum gas cost (`maxGasCost`) you are willing to sponsor for a single `UserOperation` to protect against volatile or unexpectedly expensive transactions.
   * **Time-based Policy Activation:** Schedule policies to automatically activate and deactivate at specific `start` and `end` times, ideal for limited-time promotions or campaigns.

## How it works: the sponsorship flow

The sponsorship process is a high-speed, automated workflow compliant with the ERC-4337 standard for Account Abstraction. It functions as the core logic for the `pm_sponsorUserOperation` RPC method.

1. **Sponsorship Request:** The flow begins when a user action in a partner application, via our SDK, generates a `UserOperation`. The SDK then calls the `pm_sponsorUserOperation` endpoint to determine sponsorship eligibility.
2. **Webhook to Paymaster:** our bundler provider receives this request and forwards it as a webhook to our Paymaster Service.
3. **Policy Validation:** Our Paymaster Service validates the incoming `UserOperation` against the partner's configured **Sponsorship Policy**. This is a real-time check of all conditions, including spending limits, gas limits, and whether the transaction's target address and function selector are on the partner's Allowlist.
4. **Sponsorship Decision:** Based on the validation result, our service responds:
   * **On Success:** The Paymaster cryptographically signs the `UserOperation` and returns the `paymasterAndData` field. This serves as the on-chain proof of sponsorship, allowing the transaction to be bundled and executed.
   * **On Failure:** The service returns an error, rejecting the sponsorship request. Our SDK is designed to handle this failure gracefully, falling back to a standard transaction flow where the user pays the gas fee themselves.


# Accounts and transactions
Source: https://docs.air3.com/products/money/provider-functions

EIP-1193 wallet functions in the AIR Kit Web SDK — interact with EVM chains, manage smart accounts, sign messages, and send transactions from your dApp.

## Wallet preloading

### preloadWallet()

Preloads the wallet service to improve performance by initializing the wallet infrastructure before it's needed.

**Method Signature:**

```tsx theme={null}
public async preloadWallet(): Promise<void>
```

**Usage:**

```tsx theme={null}
try {
  await airService.preloadWallet();
  console.log("Wallet preloaded successfully");
} catch (error) {
  console.error("Failed to preload wallet:", error);
}
```

**Important notes:**

* The wallet can be preloaded even before the user is logged in
* Improves response time for subsequent wallet operations
* Even if preloading hasn't finished, using the provider or any other wallet operation will ensure that the wallet is done initializing before executing the actual call

**Requirements:**

* Service must be initialized

## EIP-1193 wallet provider

### getProvider()

Returns an EIP-1193 compatible provider that works seamlessly with popular Web3 libraries such as [web3](https://github.com/web3/web3.js), [ethers](https://github.com/ethers-io/ethers.js), and [Viem](https://viem.sh/).

**Method Signature:**

```tsx theme={null}
getProvider(): EIP1193Provider
```

**Returns:**
An EIP-1193 compatible provider object with the following interface:

```tsx theme={null}
interface EIP1193Provider {
  request(request: AirProviderParameters): Promise<unknown>;
  on<EventName extends keyof EIP1193EventMap>(
    event: EventName,
    listener: EIP1193EventMap[EventName]
  ): void;
  removeListener<EventName extends keyof EIP1193EventMap>(
    event: EventName,
    listener: EIP1193EventMap[EventName]
  ): void;
}
```

**Supported Events:**

```tsx theme={null}
type EIP1193EventMap = {
  accountsChanged(accounts: string[]): void;
  chainChanged(chainId: string): void;
  connect(connectInfo: ProviderConnectInfo): void;
  disconnect(error: ProviderRpcError): void;
  message(message: ProviderMessage): void;
};
```

**Requirements:**

* User must be logged in

## Standard RPC methods

The provider also supports all standard EIP-1193 methods:

```tsx theme={null}
// Get accounts
const accounts = await provider.request({ method: "eth_accounts" });

// Request accounts
const accounts = await provider.request({ method: "eth_requestAccounts" });

// Get chain ID
const chainId = await provider.request({ method: "eth_chainId" });

// Send transaction
const txHash = await provider.request({
  method: "eth_sendTransaction",
  params: [transactionParams]
});

// Sign message
const signature = await provider.request({
  method: "personal_sign",
  params: [message, address]
});

// Switch chain
await provider.request({
  method: "wallet_switchEthereumChain",
  params: [{ chainId: "0x2105" }] // Base mainnet
});

// And more standard RPC calls
```

## Wallet events

The EIP-1193 provider supports standard wallet events:

```tsx theme={null}
const provider = airService.getProvider();

// Listen for account changes
provider.on("accountsChanged", (accounts) => {
  console.log("Accounts changed:", accounts);
});

// Listen for chain changes
provider.on("chainChanged", (chainId) => {
  console.log("Chain changed to:", chainId);
});

// Listen for connection events
provider.on("connect", (connectInfo) => {
  console.log("Wallet connected:", connectInfo);
});

// Listen for disconnects
provider.on("disconnect", (error) => {
  console.log("Wallet disconnected:", error);
});
```


# Session Key Management (Beta)
Source: https://docs.air3.com/products/money/session-keys

Create scoped session keys in AIR Kit with air_grantPermissions and air_executeAction — approve once, then sign transactions without re-prompts (beta).

Session keys allow your application to execute transactions on behalf of users without requiring approval for each action. This is useful for gaming, automated strategies, or any flow where per-transaction signing creates friction.

**air\_listSessionKeyScopes**

```tsx theme={null}
const scopes = await provider.request({
  method: "air_listSessionKeyScopes",
  params: [chainId] // optional chain ID
});
// Returns: ActionPolicyInfo[]
```

**air\_grantPermissions**

```tsx theme={null}
const result = await provider.request({
  method: "air_grantPermissions",
  params: [policies] // ActionPolicyInfo[]
});
// Returns: { compressedSessionData: string, sessionOwnerPrivateKey: string, permissionIds: Hex[] }
```

**air\_revokePermission**

```tsx theme={null}
const txHash = await provider.request({
  method: "air_revokePermission",
  params: [permissionId] // Hex
});
// Returns: string (transaction hash)
```

**air\_executeAction**

```tsx theme={null}
const txHash = await provider.request({
  method: 'air_executeAction',
  params: [{
    compressedSessionData: string,
    sessionOwnerPrivateKey: string,
    call: {
      data?: Hex,
      to: Address,
      value?: bigint
    }
  }]
});
// Returns: string (transaction hash)
```


# Smart accounts
Source: https://docs.air3.com/products/money/smart-account

Check deployment status and deploy AIR Kit smart accounts on any supported chain, with gas sponsored by the paymaster on first transaction.

Smart accounts are the primary interface for blockchain interactions in AIR Kit. The smart account is always used when interacting with the AIR Account, while the MPC (Multi-Party Computation) wallet only acts as a signer. AIR Kit provides methods to check deployment status and deploy smart accounts when needed.

**Key Technical Details:**

* Smart accounts are **chain-specific** - deployment status and operations depend on the currently selected chain
* If a smart account is not deployed and your dApp triggers a transaction, AIR Kit will automatically bundle the smart account deployment with the transaction
* Smart account deployments are **sponsored by AIR Kit** via paymaster policy, so users don't need to pay gas fees for deployment

### isSmartAccountDeployed()

Checks whether the user's smart account has been deployed on the currently selected blockchain.

**Method Signature:**

```tsx theme={null}
public async isSmartAccountDeployed(): Promise<boolean>
```

**Returns:**

* `true` if the smart account is deployed on the current chain
* `false` if the smart account is not yet deployed on the current chain

**Requirements:**

* User must be logged in
* User must be on a supported chain

### deploySmartAccount()

Deploys the user's smart account to the currently selected blockchain. This method explicitly deploys the smart account, though deployment will also happen automatically when needed.

**Method Signature:**

```tsx theme={null}
public async deploySmartAccount(): Promise<{ txHash: string }>
```

**Returns:**

```tsx theme={null}
{
  txHash: string; // The transaction hash of the deployment transaction
}
```

**What happens during deployment:**

1. Checks if the smart account is already deployed on the current chain (throws error if already deployed)
2. Creates a deployment transaction that sends to the zero address with no value
3. Submits the transaction to the blockchain using the sponsored paymaster
4. Returns the transaction hash for tracking

**Requirements:**

* User must be logged in
* User must be on a supported chain
* Smart account must not already be deployed on the current chain

**Example:**

```tsx theme={null}
try {
  const { txHash } = await airService.deploySmartAccount();
} catch (error) {
  console.error("Smart account deployment failed:", error);
  // Handle error appropriately
}
```

**Important Notes:**

* **Deployment is sponsored by AIR Kit** - users don't pay gas fees for deployment
* The deployment transaction may take some time to be confirmed on the blockchain
* After deployment, the user will be able to perform blockchain operations on this chain
* **Automatic bundling**: If you don't explicitly deploy and trigger a transaction, deployment will be automatically bundled with the transaction

### Smart account deployment flow

When working with smart accounts, you have two approaches:

**Option 1: Explicit Deployment (Recommended for better UX)**

```tsx theme={null}
const isDeployed = await airService.isSmartAccountDeployed();
if (!isDeployed) {
  const { txHash } = await airService.deploySmartAccount();
  // Wait for deployment confirmation before proceeding
}
```

**Option 2: Let AIR Kit Handle Deployment Automatically**
Simply proceed with your transaction - deployment will be bundled automatically if needed.

**Recommendation:** Use Option 1 for better user experience, as it allows you to show deployment progress and handle any deployment-specific errors separately from your main transaction logic.


# Supported chains
Source: https://docs.air3.com/products/money/supported-chains

Supported chains in AIR Kit — list of mainnet and testnet EVM networks available for smart account deployment based on your partner configuration.

# Supported Chains

AIR Kit supports multiple blockchain networks. The available chains depend on your partner configuration.

**Mainnet Chains:**

* **Base** (Chain ID: 8453) - Default mainnet chain
* **BSC** (Chain ID: 56)
* **Gnosis** (Chain ID: 100)
* **Kaia** (Chain ID: 8217)
* **Soneium** (Chain ID: 1868)

**Testnet Chains:**

* **Base Sepolia** (Chain ID: 84532) - Default testnet chain
* **BSC Testnet** (Chain ID: 97)
* **Gnosis Chiado** (Chain ID: 10200)
* **Kairos** (Chain ID: 1001)
* **Soneium Minato** (Chain ID: 1946)
* **Sepolia** (Chain ID: 11155111)

## Chain configuration

Chains are configured per partner through the partner configuration:

```tsx theme={null}
// Partner configuration example
{
  chainId: "8453", // Default chain (Base mainnet)
  enabledChainIds: ["8453", "56", "100"] // All supported chains of that partner
}
```

## Gas cost reference

Gas costs on AIR Kit operations are paid in the native token of the selected chain (or sponsored via Paymaster). The table below shows **approximate gas units** for common operations. Actual \$MOCA costs for Moca Chain credential anchoring are listed separately.

<Note>
  These benchmarks reflect Testnet measurements as of Q1 2025. Mainnet costs may differ. Enable [Gas Sponsorship (Paymaster)](/products/money/paymaster) to abstract all gas costs from your end users.
</Note>

### Credential operations (Moca Chain)

| Operation | Estimated Gas | Approx. Cost |
| - | :-: | :-: |
| Smart account deployment (first-time) | \~200,000 | \~0.0002 MOCA |
| Credential issuance (on-chain anchor) | \~80,000 | \~0.00008 MOCA |
| Credential verification (ZK proof submit) | \~120,000 | \~0.00012 MOCA |
| Credential revocation | \~50,000 | \~0.00005 MOCA |
| Session key registration | \~60,000 | \~0.00006 MOCA |

### EVM chain operations (Base, BSC, Gnosis, etc.)

| Operation | Estimated Gas | Notes |
| - | :-: | - |
| Smart account deployment | \~200,000 | One-time per user per chain |
| UserOperation (ERC-4337) | \~150,000–300,000 | Varies by calldata size |
| ERC-20 transfer | \~65,000 | Standard token transfer |

## Gas sponsorship

Use the [Paymaster](/products/money/paymaster) to cover all user-facing gas costs from a pre-funded developer wallet. This removes all on-chain funding friction from your end users — they never need to hold or manage gas tokens.

<Note>
  For Moca Chain RPC endpoints, chain IDs, and explorers, see [Network information](/technicals/mocachain/network-information).
</Note>


# Use cases
Source: https://docs.air3.com/products/money/use-cases

Explore AIR Money examples for accounts, spending, and creator payouts, then follow the wallet integration guides.

Use these demos to explore the user experience before choosing your wallet integration.

<CardGroup>
  <Card title="Accounts and spending" icon="wallet" href="https://socialhomedemo.vercel.app/">
    Explore accounts, cards, and spending in the Socials Money demo.
  </Card>

  <Card title="Creator payouts" icon="money-bill-transfer" href="https://creator-pay-air-wallet.vercel.app/">
    Explore creator payouts, sending funds, and cashing out in the Creator Pay demo.
  </Card>
</CardGroup>

## Start building

* [Accounts and transactions](/products/money/provider-functions) — sign messages and send transactions through the wallet provider.
* [Sponsoring gas](/products/money/paymaster) — configure transaction subsidies and policy limits.
* [React walkthrough](/products/money/wagmi-integration) — connect AIR smart accounts to your React app.


# Wagmi Connector
Source: https://docs.air3.com/products/money/wagmi

Connect AIR Kit smart accounts to React dApps with @mocanetwork/airkit-connector for wagmi — wallet state, auto-connect, and signing hooks.

**Wagmi** is a collection of React Hooks containing everything you need to start working with Ethereum. `@mocanetwork/airkit-connector` is a connector for the popular [wagmi](https://github.com/tmm/wagmi) library to help you integrate and interact with the `AirService`.

This package can be used to initialize a [wagmi client](https://wagmi.sh/) that will seamlessly manage the interaction (wallet connection state and configuration, such as auto-connection, connectors, and ethers providers) of your dApp.

### Initialization

```ts theme={null}
import { http, createConfig, CreateConnectorFn } from "wagmi";
import { mainnet, sepolia } from "wagmi/chains";
import { airConnector, AirConnector, AirConnectorProperties } from "@mocanetwork/airkit-connector";

const wagmiConfig = createConfig({
  chains: [mainnet, sepolia],
  transports: {
    [mainnet.id]: http(),
    [sepolia.id]: http(),
  },
  connectors: [
    airConnector({
      partnerId: {{YOUR_PARTNER_ID}},
    }),
  ],
});
```

Inside your (root) React component you can add the wagmi provider to the component tree.

```ts theme={null}
function App() {
  return (
    <WagmiProvider config={wagmiConfig}>
      ...
    </WagmiProvider>
  );
}
```

### Usage

Now you can access the connector in any component and interact with the wagmi connector. The `AirService` itself can also be accessed by casting the `Connector` to a union type with `AirConnectorProperties` or directly to `AirConnector`.

```ts theme={null}
const { connect, connectors, error } = useConnect();
const { addresses, connector } = useAccount();

const isAirWalletConnector = (connector as Connector & AirConnectorProperties)
  ?.isMocaNetwork;
const airConnector = useMemo<AirConnector | null>(() => {
  if (isAirWalletConnector) {
    return connector;
  }
  return null;
}, [connector, isAirWalletConnector]);

const service = airConnector.airService;
```


# React walkthrough
Source: https://docs.air3.com/products/money/wagmi-integration

Use the @mocanetwork/airkit-connector wagmi connector in React to access AIR Kit smart accounts and sign transactions with useAccount and useConnect hooks.

This recipe shows how to wire up the `@mocanetwork/airkit-connector` package so your React app can use wagmi hooks (`useAccount`, `useConnect`, `useSendTransaction`, etc.) with AIR Kit smart accounts.

## Prerequisites

* A React project with wagmi v2+ installed
* AIR Kit SDK installed: `npm i @mocanetwork/airkit @mocanetwork/airkit-connector`
* A Partner ID from the [Developer Dashboard](https://developers.sandbox.air3.com/dashboard)

## Step 1: Create the wagmi config

```ts theme={null}
import { http, createConfig } from "wagmi";
import { mainnet, sepolia } from "wagmi/chains";
import { airConnector } from "@mocanetwork/airkit-connector";

export const wagmiConfig = createConfig({
  chains: [mainnet, sepolia],
  transports: {
    [mainnet.id]: http(),
    [sepolia.id]: http(),
  },
  connectors: [
    airConnector({
      partnerId: "your-partner-id",
    }),
  ],
});
```

## Step 2: Wrap your app with WagmiProvider

```tsx theme={null}
import { WagmiProvider } from "wagmi";
import { wagmiConfig } from "./config";

function App() {
  return (
    <WagmiProvider config={wagmiConfig}>
      {/* your app */}
    </WagmiProvider>
  );
}
```

## Step 3: Connect and use the account

```tsx theme={null}
import { useConnect, useAccount } from "wagmi";
import type { Connector } from "wagmi";
import type { AirConnector, AirConnectorProperties } from "@mocanetwork/airkit-connector";
import { useMemo } from "react";

function ConnectButton() {
  const { connect, connectors } = useConnect();
  const { addresses, connector, isConnected } = useAccount();

  const airWallet = useMemo<AirConnector | null>(() => {
    if ((connector as Connector & AirConnectorProperties)?.isMocaNetwork) {
      return connector as AirConnector;
    }
    return null;
  }, [connector]);

  if (isConnected && airWallet) {
    return <p>Connected: {addresses?.[0]}</p>;
  }

  return (
    <button onClick={() => connect({ connector: connectors[0] })}>
      Connect AIR Account
    </button>
  );
}
```

## Step 4: Access AirService from the connector

Once connected, you can access the underlying `AirService` for credential operations. Verification takes a Partner JWT signed on your server with `scope: "verify"` and the verification program ID:

```ts theme={null}
const service = airWallet.airService;

const { token } = await fetch("/api/verification-token", { method: "POST" }).then((r) => r.json());

const result = await service.verifyCredential({
  authToken: token,
  programId: process.env.NEXT_PUBLIC_VERIFY_PROGRAM_ID,
});

if (result.status === "COMPLIANT") {
  // unlock the gated feature
}
```

See [Verify a credential in your app](/get-started/recipes/verify-credential) for the server endpoint and result handling.

## Step 5: Send a transaction

With the connector active, standard wagmi transaction hooks work against the user's AIR Kit smart account:

```tsx theme={null}
import { useSendTransaction } from "wagmi";
import { parseEther } from "viem";

function SendButton() {
  const { sendTransaction } = useSendTransaction();

  return (
    <button
      onClick={() =>
        sendTransaction({
          to: "0xRecipientAddress",
          value: parseEther("0.01"),
        })
      }
    >
      Send 0.01 ETH
    </button>
  );
}
```

## Next steps

* [Wagmi Connector reference](/products/money/wagmi) for the full API
* [Smart Accounts](/products/money/smart-account) for account abstraction details
* [Supported Chains](/products/money/supported-chains) for the list of available networks


# What is AIR Money
Source: https://docs.air3.com/products/money/what-is-air-money

Connect AIR Accounts to smart accounts, wallet actions, and gas sponsorship in your application.

AIR Money gives users access to wallet and smart account capabilities through their AIR Account. Your application can support signing, sending assets, and supported wallet experiences while users sign in through AIR Kit.

## The account behind the experience

An AIR Account is the user's sign-in and identity account. A smart account is the chain-specific account used for blockchain transactions. AIR's MPC wallet acts as its signer. These roles work together, but they are not the same account or a single balance across every chain.

Your app chooses the enabled networks, wallet actions, and approval experience. It can use the wallet provider with existing EVM tools or open supported AIR Kit wallet screens.

## What you can build

* **Wallet transactions:** sign messages, send assets, and interact with supported contracts.
* **Gas sponsorship:** cover eligible transaction costs under an agreed paymaster policy.
* **Wallet screens:** offer supported send, receive, swap, and transaction-history experiences.
* **Scoped wallet permissions:** use session keys for supported repeated actions with defined permissions.

A wallet session key is a wallet feature; it does not establish identity delegation to an AIR Agent. Agent wallet delegation is planned separately.

## Choose your next step

Read [How it works](/products/money/how-it-works) for the sign-in-to-transaction flow, [Smart accounts](/products/money/smart-account) for the account model, and [Supported chains](/products/money/supported-chains) before choosing a network. Explore the [Use cases](/products/money/use-cases) for application examples.


# Advertising & Audiences
Source: https://docs.air3.com/solutions/advertising

Build verified, consent-based audience segments without third-party cookies. Advertisers buy access to cryptographically proven user attributes.

AIR Kit lets publishers issue verified audience credentials and configure programs that check audience eligibility using ZK proofs. Raw source records remain with the issuer. Encrypted credential payloads may be stored in DStorage, while users control decryption and disclosure to partners.

<Tabs>
  <Tab title="For business">
    ## The Problem

    Post-cookie advertising has a trust problem that no contextual or cohort-based replacement fully solves: someone still has to hold the raw user data and claim the audience is what they say it is. Data brokers vouch for segments they assembled from sources that are increasingly unverifiable. Advertisers pay for "35-44, high income, tech-interested" and get whatever the intermediary decided that means.

    ## What Changes With AIR Kit

    * **Users hold their own verified attributes** — Demographic and interest credentials are issued by your platform based on actual KYC and behaviour, not declared preferences. They're cryptographically signed
    * **Advertisers buy proof, not claims** — The DSP or SSP verifies the credential at serve time. They get COMPLIANT / NON\_COMPLIANT — a ZK proof that the user is 25–34, verified, consented, and located in AU. No raw data in the bid request
    * **Consent records are portable** — A credential can record consent collected by your CMP. Each publisher must still check that consent covers its purposes and recipients, and users control credential disclosure
    * **Age-restricted serving without storing DOB** — Prove `isOver18` at ad-serve time for gambling, alcohol, or adult categories. No DOB database to create or secure; confirm the setup meets your regulatory obligations

    ## How It Works

    <Steps>
      <Step title="User completes profile or KYC on your platform">
        Your existing onboarding. The user verifies their age, confirms their country, or completes interest profiling. Nothing new for the user.
      </Step>

      <Step title="AIR Kit issues an audience credential">
        Your backend fires one API call. A credential encoding the user's age range, verified country, IAB interest segments, and consent record lands in their AIR Account.
      </Step>

      <Step title="Ad server verifies at serve time">
        When the user visits a publisher page, the publisher's ad server calls one SDK method. It receives a verified boolean signal: age verified, consent confirmed, segment matched.
      </Step>

      <Step title="DSP bids on verified signals">
        The bid request carries a verified audience flag. DSPs can bid higher on ZK-proven attributes than on unverified self-reported data. The audience segment is now worth more.
      </Step>
    </Steps>

    ## What the Ad Server Actually Receives

    This example requests limited audience claims with user approval. The Verification Program determines the disclosed fields and whether a ZK proof is required.

    | What the Verifier Gets | What Stays Private |
    | - | - |
    | COMPLIANT / NON\_COMPLIANT | Date of birth, exact age |
    | Age range (`25-34`) | Full name, email address |
    | `isOver18: true` | IP address, device ID |
    | Country code (`AU`) | Precise location |
    | IAB segment IDs | Browsing history, clickstream |
    | Consent expiry | Declared interest details |

    ## What Compliance Will Ask

    **Does user consent need to be re-obtained?**
    The credential records consent collected by your CMP. A new publisher or purpose may require additional consent; a portable credential does not extend the scope of the original permission. Separately, users approve credential disclosure during verification.

    **Can users withdraw consent?**
    Users can withdraw consent through your consent-management process and deny future disclosure requests. Revoke the consent credential so subsequent checks reject it once the updated status is available. Revocation does not retract data already disclosed; apply withdrawal to the relevant downstream processing as well.

    **Does this replace our CMP?**
    No. Your CMP continues to collect and record consent. AIR Kit converts that consent record into a portable, cryptographically verifiable credential.

    ## Integration at a Glance

    | | |
    | - | - |
    | **What your team builds** | One API call in profile completion + one in your CMP callback |
    | **Engineering effort** | 1 backend engineer |
    | **Timeline to live** | 2–4 weeks |
    | **Partner publisher integration** | 3 lines of SDK code to verify |

    <CardGroup>
      <Card title="Compliance FAQ" icon="shield-check" href="/solutions/compliance-faq">
        Full GDPR, CCPA, and TCF answers.
      </Card>

      <Card title="Partner Economics" icon="coins" href="/solutions/partner-economics">
        Revenue model, fee structure, and rewards.
      </Card>
    </CardGroup>
  </Tab>

  <Tab title="For developers">
    ## What You Can Build

    * **Verified audience segments** — Issue demographic and interest credentials on profile completion or KYC; advertisers target against cryptographic proof, not self-reported fields
    * **Consent-portable targeting** — User consents once; that consent credential is verifiable by any publisher in the ecosystem without a consent management platform re-prompt
    * **Age-verified ad targeting** — Gate alcohol, gambling, and adult ad categories behind a ZK age proof — no DOB ever transmitted to the ad server
    * **Cross-publisher identity** — A user's verified attributes follow them across publisher sites without third-party cookies or device fingerprinting
    * **Bot and fraud resistance** — Issue a "verified human" credential after KYC or passkey authentication; DSPs and SSPs can filter on-credential instead of on-signal
    * **Brand safety compliance** — Verify user age and location at serve time without storing the data, supporting data-minimization requirements such as those in COPPA and GDPR Article 8. Whether a deployment complies depends on your implementation and jurisdiction

    ## Architecture

    ```mermaid theme={null}
    graph TD
        A["User completes profile / KYC\non your platform"] --> B[Your Backend]
        B -->| On-demand issuance| C[AIR Kit / Moca Chain]
        C --> D["Audience Credentials\nin User's AIR Account"]

        D --> E{Ad serve request}
        E -->|Publisher verifies| F["ZK proof: age ✓ location ✓\ninterest segment ✓"]
        F --> G[DSP receives verified segment signal]
        G --> H[Targeted ad served]

        D --> I{Cross-publisher visit}
        I -->|Any partner publisher| J["Same credentials verified\nno cookie / fingerprint needed"]
    ```

    ## Recommended Schemas

    ### Verified Audience Segment

    ```json theme={null}
    {
      "title": "Audience Segment",
      "description": "Publisher-verified user audience attributes — no raw PII included",
      "properties": {
        "publisherId": {
          "type": "string",
          "description": "Issuing publisher identifier"
        },
        "ageRange": {
          "type": "string",
          "enum": ["18-24", "25-34", "35-44", "45-54", "55+"],
          "description": "Verified age bracket — never the actual age or DOB"
        },
        "isOver18": {
          "type": "boolean"
        },
        "isOver21": {
          "type": "boolean"
        },
        "countryCode": {
          "type": "string",
          "description": "ISO 3166-1 alpha-2 — verified registration country"
        },
        "interestSegments": {
          "type": "array",
          "items": { "type": "string" },
          "description": "IAB content categories — e.g. ['IAB19', 'IAB9'] — derived from behaviour, not declared"
        },
        "verifiedAt": {
          "type": "string",
          "format": "date-time"
        }
      },
      "required": ["publisherId", "isOver18", "countryCode", "verifiedAt"]
    }
    ```

    ### Consent Credential

    ```json theme={null}
    {
      "title": "Ad Consent",
      "description": "Verifiable record of user consent for personalised advertising",
      "properties": {
        "publisherId": { "type": "string" },
        "consentedTo": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": ["personalised_ads", "cross_site_tracking", "interest_inference"]
          }
        },
        "consentVersion": {
          "type": "string",
          "description": "CMP policy version the user consented to"
        },
        "consentedAt": {
          "type": "string",
          "format": "date-time"
        },
        "expiresAt": {
          "type": "string",
          "format": "date-time",
          "description": "Consent expiry — re-issue when user re-confirms"
        }
      },
      "required": ["publisherId", "consentedTo", "consentVersion", "consentedAt"]
    }
    ```

    <Warning>
      Never include name, email address, IP address, device ID, or precise location in `credentialSubject`. Use only **derived, aggregated attributes** — `ageRange`, `countryCode`, `interestSegments`. The ZK proof lets the ad server confirm `isOver18 === true` without ever receiving the subscriber's date of birth.
    </Warning>

    ## Implementation

    ### Step 1 — Issue audience credentials on profile completion

    ```javascript theme={null}
    // profile-complete-handler.js
    const { getPartnerJwt } = require('./lib/jwt');
    // issuer-controlled helpers backed by your signing keys
    const { buildVc, signVc, encryptToHolder } = require('./lib/credential');

    const BASE_URL = 'https://api.sandbox.mocachain.org/v1';

    // Resolve the recipient, then build, sign, encrypt, and store the credential in DStorage
    async function issueEncryptedCredential({ recipientEmail, schemaId, credentialSubject }) {
      const token = await getPartnerJwt();

      const init = await fetch(`${BASE_URL}/auth/initialize-user`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json', 'x-partner-auth': token },
        body: JSON.stringify({ email: recipientEmail }),
      }).then((r) => r.json());

      const vc = buildVc({ holderDid: init.did, schemaId, credentialSubject });
      const encrypted = encryptToHolder(signVc(vc), init.publicKey); // SD-JWT VC, encrypted to holder

      const res = await fetch(`${BASE_URL}/dstorage/vcs`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json', 'x-partner-auth': token },
        body: JSON.stringify({
          holderDid: init.did,
          schemaId,
          expiresAt: vc.expirationDate,
          data: encrypted.encryptedData,
          iv: encrypted.iv,
          authTag: encrypted.authTag,
          encryptedKey: encrypted.dataEncPublicKey,
          externalId: vc.id,
        }),
      });
      if (!res.ok) throw new Error(`Issuance failed: ${res.status}`);
      return res.json(); // { storagePath }
    }

    async function issueAudienceCredential({ userEmail, profile }) {
      return issueEncryptedCredential({
        recipientEmail: userEmail,
        schemaId: process.env.AUDIENCE_CREDENTIAL_ID,
        credentialSubject: {
          publisherId: process.env.PUBLISHER_ID,
          ageRange: getAgeRange(profile.birthYear),    // "25-34" — NOT the DOB
          isOver18: profile.age >= 18,
          isOver21: profile.age >= 21,
          countryCode: profile.countryCode,
          interestSegments: profile.iabSegments,       // e.g. ['IAB19', 'IAB9-30']
          verifiedAt: new Date().toISOString(),
        },
      });
    }

    function getAgeRange(birthYear) {
      const age = new Date().getFullYear() - birthYear;
      if (age < 25) return '18-24';
      if (age < 35) return '25-34';
      if (age < 45) return '35-44';
      if (age < 55) return '45-54';
      return '55+';
    }

    // Fire on profile completion and on interest segment updates
    userEvents.on('profile:completed', ({ userEmail, profile }) =>
      issueAudienceCredential({ userEmail, profile })
    );
    userEvents.on('interests:updated', ({ userEmail, profile }) =>
      issueAudienceCredential({ userEmail, profile })
    );
    ```

    ### Step 2 — Issue consent credential when user accepts CMP

    ```javascript theme={null}
    // consent-handler.js
    async function issueConsentCredential({ userEmail, consentRecord }) {
      const expiresAt = new Date();
      expiresAt.setFullYear(expiresAt.getFullYear() + 1); // 1-year consent window

      await issueEncryptedCredential({
        recipientEmail: userEmail,
        schemaId: process.env.CONSENT_CREDENTIAL_ID,
        credentialSubject: {
          publisherId: process.env.PUBLISHER_ID,
          consentedTo: consentRecord.purposes,       // ["personalised_ads", ...]
          consentVersion: consentRecord.policyVersion,
          consentedAt: new Date().toISOString(),
          expiresAt: expiresAt.toISOString(),
        },
      });
    }

    // Wire into your CMP callback
    cmp.on('consent:granted', ({ userEmail, purposes, policyVersion }) =>
      issueConsentCredential({
        userEmail,
        consentRecord: { purposes, policyVersion },
      })
    );

    // Revoke consent credential on withdrawal
    cmp.on('consent:withdrawn', async ({ userEmail }) => {
      // Issue credential with empty consentedTo to effectively invalidate
      // Or call the revoke endpoint directly — see Issuance API Reference
    });
    ```

    ### Step 3 — Verify audience attributes at ad-serve time

    ```javascript theme={null}
    // ad-server-verify.js (publisher ad server / prebid adapter)
    import { AirService } from '@mocanetwork/airkit';

    import { AirService, BUILD_ENV } from "@mocanetwork/airkit";

    const airService = new AirService({ partnerId: process.env.PUBLISHER_PARTNER_ID });
    await airService.init({ buildEnv: BUILD_ENV.PRODUCTION });

    async function getVerifiedAudienceSignal() {
      // Check age compliance for restricted category
      const ageResult = await airService.verifyCredential({
        programId: process.env.AGE_18_VERIFY_PROGRAM_ID,
        // Program rule: isOver18 === true
        // Use a ZK age check without requesting the user's date of birth.
        // Successful results include a Verifiable Presentation.
      });

      // Check consent for personalised ads
      const consentResult = await airService.verifyCredential({
        programId: process.env.CONSENT_VERIFY_PROGRAM_ID,
        // Program rule: "personalised_ads" in consentedTo AND expiresAt > now
      });

      return {
        ageVerified: ageResult.status === 'COMPLIANT',
        consentVerified: consentResult.status === 'COMPLIANT',
        // Pass these as verified signals to your DSP bid request
        // No raw age, no raw consent record — just provable booleans
      };
    }

    // Enrich bid request with verified signals
    async function buildBidRequest(adSlot, user) {
      const signals = await getVerifiedAudienceSignal();

      return {
        ...adSlot,
        user: {
          ...user,
          ext: {
            airkit: {
              ageVerified: signals.ageVerified,
              consentVerified: signals.consentVerified,
              // DSP can bid higher on verified signals vs. unverified
            },
          },
        },
      };
    }
    ```

    ### Step 4 — Cross-publisher audience verification (partner publisher)

    Partner publishers integrate AIR Kit as a verifier. One SDK call replaces the cookie sync / data clean room round-trip.

    ```javascript theme={null}
    // partner-publisher.js
    import { AirService } from '@mocanetwork/airkit';

    // The PARTNER publisher uses their own Partner ID
    const airService = new AirService({ partnerId: 'PARTNER_PUBLISHER_PARTNER_ID' });
    await airService.init({ buildEnv: BUILD_ENV.PRODUCTION });

    async function verifyAudienceForPartner() {
      const result = await airService.verifyCredential({
        programId: process.env.CROSS_PUB_AUDIENCE_VERIFY_PROGRAM_ID,
        // Program checks: isOver18 === true AND countryCode in allowed list
        // The partner publisher never receives the user's raw profile data
        // They get: COMPLIANT / NON_COMPLIANT — that's it
      });
      return result.status === 'COMPLIANT';
    }
    ```

    ## Key Patterns

    | Pattern | Reissue behavior | When to Use |
    | - | :-: | - |
    | Initial audience credential | Skip if exists | Issue once on first profile completion |
    | Interest segment refresh | Revoke + reissue | Monthly or on significant interest drift |
    | Consent granted | Revoke + reissue | Always replace with latest consent record |
    | Consent withdrawn | Revoke | Reject future checks once revoked status is available; apply withdrawal to downstream processing |
    | KYC-backed audience | Revoke + reissue | Re-issue when KYC result updates |

    ## Data disclosure

    For this audience check, request only the necessary claims and use ZK proofs for conditions that do not require disclosing their underlying values. Successful verification returns a Verifiable Presentation with user-approved claims and any required proof. Configure the program to exclude DOB, email, IP address, and browsing history; the table below describes that limited-disclosure example.

    | What the Verifier Sees | What Stays Private |
    | - | - |
    | `COMPLIANT / NON_COMPLIANT` | Date of birth, exact age |
    | `ageRange` (`25-34`) | Full name, email address |
    | `isOver18: true` | IP address, device ID |
    | `countryCode` (`AU`) | Precise location |
    | IAB segment IDs | Browsing history, clickstream |
    | Consent expiry date | Declared interests |

    ## Regulatory Alignment

    Credentials can record consent and support age or eligibility checks, but do not establish regulatory compliance on their own. Review the scope of consent, applicable age requirements, opt-out handling, and retention for each publisher and purpose. Your CMP remains responsible for collecting and managing consent. See the [Compliance FAQ](/solutions/compliance-faq) for storage and disclosure considerations.

    ## Examples

    <CardGroup>
      <Card title="Verified traffic (offline)" icon="play" href="https://air-bd-v2.netlify.app/demo/verified-traffic-offline">
        Video walkthrough: a customer's airline status is verified at a partner restaurant.
      </Card>

      <Card title="Verified traffic (online)" icon="play" href="https://publisher-poc.netlify.app/">
        Live publisher demo: a visitor signs in with AIR on a storefront and reaches a partner campaign already recognized.
      </Card>
    </CardGroup>

    ## Next Steps

    <Columns>
      <Card title="On-demand Issuance — Concepts" icon="book" href="/products/identity/issuing-credentials#direct-issuance">
        On-demand issuance without user presence.
      </Card>

      <Card title="On-demand Issuance — API" icon="code" href="/api-reference/issuance-api">
        Full endpoint reference with error codes.
      </Card>

      <Card title="AIR for Fintech & Payments" icon="credit-card" href="/solutions/fintech">
        KYC portability and age verification patterns.
      </Card>

      <Card title="Schema Use Cases" icon="list" href="/products/identity/schema-use-cases">
        More credential schema examples.
      </Card>
    </Columns>
  </Tab>
</Tabs>


# Compliance & Privacy
Source: https://docs.air3.com/solutions/compliance-faq

GDPR, CCPA, data residency, PII storage, and breach liability questions answered for enterprise legal and compliance teams evaluating AIR Kit.

Answers to the questions legal and compliance teams ask when evaluating AIR Kit. If your question isn't covered here, reach out at [support@moca.network](mailto:support@moca.network).

***

## Data Storage & PII

**Does AIR Kit store our customers' personal data?**

Raw source documents remain with the issuer. Encrypted credential payloads may be stored in DStorage, while users control decryption and disclosure. The issuer signs the credential and encrypts it to the holder's public key before storage. AIR stores and routes opaque ciphertext and metadata, not plaintext issuer data.

**What does a credential actually contain?**

The credential contains the attributes defined by its schema. Prefer the minimum claims needed for the use case, such as `isOver18: true`, `kycLevel: "enhanced"`, or `tier: "Gold"`. These claims can still be personal data. The signed credential payload is encrypted before storage; it is not replaced by a hash or a boolean proof.

**Can AIR Kit or Moca Network read our customers' credential data?**

Issuers know the source data and the claims they issue. AIR receives encrypted credential payloads and metadata without the holder's decryption key. Users control decryption and disclosure. Verifiers receive the claims requested by their Verification Program and approved by the user; a ZK proof can establish a condition without disclosing the underlying value.

**Where is data stored geographically?**

Source documents remain in issuer-controlled systems. Encrypted credential payloads may be stored with DStorage providers, alongside storage metadata. On-chain records and off-chain verification sessions are separate from those payloads. Confirm provider locations, metadata processing, and any regional commitments with the AIR team when assessing data residency. Encryption alone does not make identifiable data anonymous; see the [European Commission's GDPR guidance](https://commission.europa.eu/law/law-topic/data-protection/information-business-and-organisations/application-gdpr_en).

***

## GDPR

**Is this compliant with GDPR Article 5(1)(c) — data minimisation?**

AIR Kit supports data minimisation through schema design, encryption, and program-controlled disclosure. Choose only the claims needed for your purpose and request only the fields your verifier needs. Compliance depends on your implementation and processing purposes; using derived claims or encryption does not establish it automatically.

**How do we handle Article 17 data subject deletion requests?**

Revocation prevents a credential from passing subsequent checks that recognize its revoked status. It does not delete encrypted payloads, metadata, source records, or data already disclosed to verifiers. Handle erasure and retention separately across issuer systems, storage providers, and verifiers, including any applicable retention obligations. On-chain records cannot be removed by revoking a credential.

**Does issuing credentials constitute international data transfer under GDPR Chapter V?**

Assess the actual data flow: encrypted credential payloads and metadata may be stored outside the issuer's systems, and verifiers may receive user-approved claims. Review provider locations, recipients, and applicable transfer safeguards with your data protection team. Do not assume that encryption or ZK proofs remove transfer obligations.

**Who is the data controller?**

Issuers control their source data and signing keys. Verifiers determine how they use disclosed claims. Establish controller and processor roles for each processing activity in your agreements, including AIR's handling of ciphertext, metadata, and verification sessions. The storage architecture alone does not determine every party's legal role.

**Does consent need to be obtained to issue credentials?**

Determine and document the lawful basis for issuance with your data protection team. User controls for decryption and disclosure are separate from that legal assessment. Direct issuance does not remove your notice or lawful-basis requirements.

***

## CCPA / CPRA

**Does issuing AIR Kit credentials constitute "selling" personal information under CCPA?**

Assess your actual processing, disclosures, purposes, and contracts. Credential issuance and verification can involve encrypted personal information, metadata, and user-approved claims; it is not a blanket exemption from sale or sharing rules. See the [California Attorney General's CCPA guidance](https://www.oag.ca.gov/privacy/ccpa).

**How do we handle opt-out requests?**

Apply the opt-out to the relevant processing and sharing activities. Revocation can stop future use of a credential, but it does not retract data already disclosed or replace your opt-out and deletion procedures.

***

## Security & Breach Liability

**What is the breach liability for verifiers accepting AIR Kit credentials?**

A proof-only program can reduce the data a verifier receives. Successful verification returns a Verifiable Presentation that can contain user-approved claims and optional proof material. Verifiers must protect any disclosed claims, identifiers, and session records they retain. Exposure depends on the program and the verifier's data handling.

**What is the breach liability for issuers?**

Issuers hold source data and signing keys and prepare the credential before encrypting it to the holder. AIR's storage and routing layer handles ciphertext and metadata. Assess exposure across source systems, issuer keys, encrypted storage, metadata, and any disclosed copies; encryption does not eliminate every breach risk or liability.

**Is there an audit trail for credential issuance and verification?**

AIR Kit uses verification sessions for usage and reporting. Whether a verification proof is submitted on-chain depends on the Verification Program. Do not assume every issuance or verification event appears in a single on-chain audit log; confirm the records available for your integration.

***

## Credentials & Revocation

**How quickly does credential revocation take effect?**

Revocation is checked during verification. The effect depends on the issuer's revocation mechanism and when the updated status is available to the verifier. Do not assume a universal one-block or instant propagation guarantee.

**What happens to credentials if a user closes their account?**

Include credential revocation in your account-closure process and handle source records, encrypted payloads, metadata, and previously disclosed data under your retention and deletion procedures. Account closure or revocation does not by itself erase all copies.

**Can a user hold credentials from multiple issuers in one AIR Account?**

Yes. An AIR Account can hold credentials from any number of issuers. The user controls which credentials to present at any given verifier.

**Can credentials expire?**

Yes. You set an `expirationDate` in the credential subject. After expiry, the credential returns NON\_COMPLIANT. You can re-issue with a new expiry at any time.

***

## Partnerships & Commercial

**Is AIR Kit SOC 2 certified?**

Reach out to [support@moca.network](mailto:support@moca.network) for current security certifications and our shared responsibility documentation.

**Can we run AIR Kit in a private deployment?**

Moca Chain is a public L1. The SDK connects to Moca Network infrastructure. Private / on-premise deployment is not currently available. Discuss specific requirements with our team.

**Who do we contact for a Data Processing Agreement (DPA)?**

Contact [support@moca.network](mailto:support@moca.network). We provide a standard DPA for enterprise partners.


# Fintech & Payments
Source: https://docs.air3.com/solutions/fintech

Reduce repeated KYC checks, limit disclosure, and enable cross-platform credential verification — without changing your KYC provider or your user flow.

Traditional KYC and compliance verification requires every platform to collect, store, and protect sensitive personal data — creating liability, compliance risk, and repeated friction for users. AIR Kit lets you **issue a KYC credential once**, and any partner platform can verify it via zero-knowledge proof without ever accessing raw PII.

<Tabs>
  <Tab title="For business">
    ## The Problem

    Financial services carry the heaviest identity verification burden of any industry. Every new product, every new partner integration, every new regulatory jurisdiction demands another round of KYC — costs running $5–$50 per user, abandonment rates averaging 30%, and a growing database of sensitive documents that represents liability, not value.

    ## What Changes With AIR Kit

    * **KYC costs fall per partner onboarded** — Your first KYC verification is the only one your customers need. Partners accept the credential, not a new document submission
    * **Limit verifier data collection** — A ZK proof can confirm eligibility without disclosing identity documents. Programs may also request user-approved claims; verifiers must protect the data they receive
    * **Age and accreditation gates with limited disclosure** — Prove a user is 18+, 21+, or an accredited investor without disclosing the underlying values to the verifier
    * **Reusable KYC without bilateral agreements** — One KYC credential, presentable to partners across the Moca ecosystem. Partner acceptance depends on their regulatory requirements

    ## Specific Use Cases

    **KYC Re-use Across Partners**
    Your bank onboards a customer, passes KYC, issues a credential. That customer opens an account with a partner fintech. The partner verifies the credential in one SDK call — no new document submission, no re-KYC cost, no waiting period. [See the reusable KYC demo](https://air-bd-v2.netlify.app/demo/reusable-kyc).

    **DeFi and Financial Product Access**
    Gate access to financial products, DeFi pools, or high-value transactions behind a KYC credential check. Users who have already verified are admitted instantly. Users who haven't are prompted to verify once.

    **Accredited Investor Verification**
    Issue an income or net worth attestation on your platform. Any partner offering private placements, alternative investments, or regulated financial products can verify it via ZK proof — without ever seeing the income figures.

    **Age Gating**
    Prove `isOver18` or `isOver21` without revealing the user's birthdate to the verifier. You check age eligibility without creating a new store of birthdates; confirm the approach meets the rules for your products and jurisdictions. [Try it live](https://air-bd-v2.netlify.app/try-it-live/meet-verified): the verifier learns only that an ID check passed.

    ## What Compliance Will Ask

    **Does this satisfy our AML/KYC obligations?**
    Your KYC obligations remain with your KYC provider. AIR Kit converts the pass result into a portable credential — it does not replace or modify the KYC process itself.

    **What does the credential contain?**
    The schema defines the claims. For this example, use KYC level, provider name, pass date, country of verification, and boolean age checks. Raw source documents remain with the issuer. Encrypted credential payloads may be stored in DStorage, while users control decryption and disclosure.

    **Who is liable if a credential is fraudulent?**
    You, as the issuer, are responsible for the KYC process that underlies the credential — the same as today. AIR Kit provides the credential infrastructure; the compliance process is yours.

    **Can we revoke credentials immediately?**
    Issuers can revoke credentials. Subsequent verification checks reject the credential once the updated status is available. Revocation does not erase stored or previously disclosed data.

    ## Integration at a Glance

    | | |
    | - | - |
    | **What your team builds** | One API call in your KYC webhook |
    | **Engineering effort** | 1 backend engineer |
    | **Timeline to live** | 2–3 weeks |
    | **User flow changes** | None |
    | **Partner integration** | 3 lines of SDK code |

    <CardGroup>
      <Card title="Compliance FAQ" icon="shield-check" href="/solutions/compliance-faq">
        Full regulatory and data handling answers.
      </Card>

      <Card title="Partner Economics" icon="coins" href="/solutions/partner-economics">
        Revenue model, fee structure, and rewards.
      </Card>
    </CardGroup>
  </Tab>

  <Tab title="For developers">
    ## What You Can Build

    * **KYC credentials** — Issue a verified identity attestation the moment a user passes KYC; partner platforms accept it without re-running the check
    * **Income / accreditation proofs** — Issue an "Accredited Investor" credential backed by income verification, provable via ZK proof
    * **Compliance gating** — Gate DeFi pools, financial products, or high-value transactions behind credential checks
    * **Age verification** — Prove a user is 18+ or 21+ without revealing their birthdate to the verifier
    * **Cross-border compliance** — One credential, accepted at every partner service in the ecosystem

    ## Architecture

    ```mermaid theme={null}
    graph TD
        A["User completes KYC\nwith your KYC provider"] --> B["KYC Provider webhook / callback"]
        B --> C[Your Backend]
        C -->|On-demand issuance| D[AIR Kit / Moca Chain]
        D --> E[KYC Credential in User's AIR Account]

        E --> F{User accesses financial product}
        F -->|Your platform| G["Verify KYC credential\nUser-approved claims and proofs"]
        F -->|Partner DeFi protocol| H["ZK proof: user is KYC'd"]
        F -->|Cross-border service| I[Compliance check passed]
    ```

    ## Recommended Schema

    ### KYC Attestation

    ```json theme={null}
    {
      "title": "KYC Attestation",
      "description": "Identity verification attestation — no raw PII included",
      "properties": {
        "kycLevel": {
          "type": "string",
          "enum": ["basic", "enhanced", "institutional"],
          "description": "Level of KYC verification completed"
        },
        "kycProvider": {
          "type": "string",
          "description": "Name of the KYC provider (e.g. 'Jumio', 'Onfido')"
        },
        "verifiedAt": {
          "type": "string",
          "format": "date-time"
        },
        "countryCode": {
          "type": "string",
          "description": "ISO 3166-1 alpha-2 country code"
        },
        "isOver18": {
          "type": "boolean"
        },
        "isOver21": {
          "type": "boolean"
        }
      },
      "required": ["kycLevel", "kycProvider", "verifiedAt", "isOver18"]
    }
    ```

    <Warning>
      Never include raw PII — full name, passport number, date of birth, address — in `credentialSubject`. Store only **attestations and derived facts**. ZK proofs let verifiers confirm `isOver18 === true` without seeing any underlying data.
    </Warning>

    ## Implementation

    ### Step 1 — Issue KYC credential from your KYC webhook

    ```javascript theme={null}
    // kyc-webhook.js  — called when your KYC provider sends a completion event
    const { getPartnerJwt } = require('./lib/jwt');
    // issuer-controlled helpers backed by your signing keys
    const { buildVc, signVc, encryptToHolder } = require('./lib/credential');

    const BASE_URL = 'https://api.sandbox.mocachain.org/v1';

    async function issueKycCredential({ userEmail, kycResult }) {
      if (kycResult.status !== 'APPROVED') return; // only issue on success

      const token = await getPartnerJwt();

      // Resolve the user's AIR Account
      const init = await fetch(`${BASE_URL}/auth/initialize-user`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json', 'x-partner-auth': token },
        body: JSON.stringify({ email: userEmail }),
      }).then((r) => r.json());

      // Build, sign (SD-JWT VC), and encrypt the credential to the holder
      const schemaId = process.env.KYC_CREDENTIAL_ID;
      const vc = buildVc({
        holderDid: init.did,
        schemaId,
        credentialSubject: {
          kycLevel: kycResult.level,             // "basic" | "enhanced" | "institutional"
          kycProvider: 'YourKYCProvider',
          verifiedAt: new Date().toISOString(),
          countryCode: kycResult.countryCode,    // e.g. "US", "GB"
          isOver18: kycResult.age >= 18,
          isOver21: kycResult.age >= 21,
        },
      });
      const encrypted = encryptToHolder(signVc(vc), init.publicKey);

      // Store the encrypted envelope in DStorage
      const res = await fetch(`${BASE_URL}/dstorage/vcs`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json', 'x-partner-auth': token },
        body: JSON.stringify({
          holderDid: init.did,
          schemaId,
          expiresAt: vc.expirationDate,
          data: encrypted.encryptedData,
          iv: encrypted.iv,
          authTag: encrypted.authTag,
          encryptedKey: encrypted.dataEncPublicKey,
          externalId: vc.id,
        }),
      });
      if (!res.ok) throw new Error(`KYC credential issuance failed: ${res.status}`);
      return res.json(); // { storagePath }
    }

    // Express webhook endpoint
    app.post('/webhooks/kyc', async (req, res) => {
      const { userEmail, kycResult } = req.body;
      await issueKycCredential({ userEmail, kycResult });
      res.json({ ok: true });
    });
    ```

    ### Step 2 — Gate financial products with credential verification

    ```javascript theme={null}
    // fintech-gate.js  (frontend)
    import { AirService } from '@mocanetwork/airkit';

    import { AirService, BUILD_ENV } from "@mocanetwork/airkit";

    const airService = new AirService({ partnerId: process.env.PARTNER_ID });
    await airService.init({ buildEnv: BUILD_ENV.SANDBOX });

    async function requireKyc() {
      const result = await airService.verifyCredential({
        programId: process.env.KYC_VERIFY_PROGRAM_ID,
        // Verifier program rule: kycLevel is "enhanced" or "institutional"
      });

      if (result.status !== 'COMPLIANT') {
        throw new Error('KYC_REQUIRED');
      }
      return result;
    }

    // Gate a high-value transaction
    try {
      await requireKyc();
      proceedWithTransaction();
    } catch (err) {
      if (err.message === 'KYC_REQUIRED') showKycOnboarding();
    }
    ```

    ### Step 3 — Age verification gate (no birthdate exposed)

    ```javascript theme={null}
    // age-gate.js  (frontend)
    async function requireAgeVerification() {
      const result = await airService.verifyCredential({
        programId: process.env.AGE_18_VERIFY_PROGRAM_ID,
        // Program checks: isOver18 === true  — verifier never sees the actual age/DOB
      });
      return result.status === 'COMPLIANT';
    }
    ```

    ## Privacy Guarantee

    A program configured for a ZK eligibility check can avoid disclosing raw KYC documents. Successful verification returns a Verifiable Presentation with user-approved claims and any required proof. Verifiers remain responsible for data they request and retain.

    | What the Verifier Sees | What Stays Private |
    | - | - |
    | `COMPLIANT / NON_COMPLIANT` | Full name, passport / ID number |
    | Credential expiry date | Date of birth |
    | KYC level (`basic` / `enhanced`) | Residential address |
    | Issuer DID | Income figures, net worth |
    | `isOver18: true` | Actual age |

    ## Examples

    <CardGroup>
      <Card title="KYC Passport — demo" icon="play" href="https://air-bd-v2.netlify.app/demo/reusable-kyc">
        Walk through reusable KYC: verify once, then open an account with a partner without re-running KYC.
      </Card>

      <Card title="KYC Passport — Issuer" icon="github" href="https://github.com/MocaNetwork/air-examples/tree/main/kyc-passport/issuer">
        KYC provider app: issues credentials once; user carries the proof to other platforms.
      </Card>

      <Card title="KYC Passport — Verifier" icon="github" href="https://github.com/MocaNetwork/air-examples/tree/main/kyc-passport/verifier">
        Lending platform app: verifies the credential and accepts the proof without re-running KYC.
      </Card>

      <Card title="ZK Age Verification — Issuer" icon="github" href="https://github.com/MocaNetwork/air-examples/tree/main/zk-age-verification/issuer">
        Identity provider app: issues age credential; user proves 18+ without revealing date of birth.
      </Card>

      <Card title="ZK Age Verification — Verifier" icon="github" href="https://github.com/MocaNetwork/air-examples/tree/main/zk-age-verification/verifier">
        iGaming platform app: verifies age-gate (e.g. 18+) via ZK proof; no birthdate disclosure required.
      </Card>
    </CardGroup>

    ## Next Steps

    <Columns>
      <Card title="On-demand Issuance — Concepts" icon="book" href="/products/identity/issuing-credentials#direct-issuance">
        On-demand issuance without user presence.
      </Card>

      <Card title="Architecture & Data Flow" icon="diagram-project" href="/technicals/architecture">
        ZK proof flow end-to-end.
      </Card>

      <Card title="Partner Authentication" icon="key" href="/get-started/authentication/sdk-auth">
        JWT signing setup for your backend.
      </Card>

      <Card title="Verifying Credentials" icon="shield-check" href="/products/identity/verify">
        SDK verification reference.
      </Card>
    </Columns>
  </Tab>
</Tabs>


# Gaming & Entertainment
Source: https://docs.air3.com/solutions/gaming

Make player achievements, ranks, and identities portable across games. Issue credentials at milestones for tournaments, partner games, and airdrops.

In gaming, players rebuild their reputation from zero every time they switch titles. AIR Kit lets you **make achievements, badges, and identities portable** — a player's rank in your game becomes a credential they carry to partner games, tournaments, communities, and airdrops.

<Tabs>
  <Tab title="For business">
    ## The Problem

    In gaming, players rebuild their reputation from zero every time they switch titles. A Diamond-ranked player in your game is nobody in the next one. Achievements don't transfer. Identities don't travel. Bot accounts create fake engagement metrics that poison every distribution event you run.

    ## What Changes With AIR Kit

    * **Player achievements become portable** — A rank, badge, or title earned in your game is a verifiable credential the player carries to partner games, tournaments, and community platforms
    * **Cross-game identity without account linking** — Players authenticate with their AIR Account in any game in the ecosystem. Same identity, no re-registration
    * **Bot-resistant distribution** — Gate airdrops, whitelist spots, and in-game rewards to players who provably hold specific credentials — verified human, minimum playtime, achieved rank
    * **Guild and DAO membership proofs** — Issue guild credentials that gate Discord roles, governance votes, and cross-game benefits without a separate verification tool

    ## How It Works

    <Steps>
      <Step title="In-game event fires">
        A player reaches Diamond rank. Completes a raid. Achieves 100 hours of playtime. Your game server triggers the same event it always has.
      </Step>

      <Step title="Achievement credential issues automatically">
        Your backend calls AIR Kit with the achievement details. The credential lands in the player's AIR Account in the background. No wallet prompt, no UX interruption.
      </Step>

      <Step title="Player carries the credential anywhere">
        In tournament registration, partner game login, or airdrop claims — the player presents their credential. One tap. Verified instantly.
      </Step>

      <Step title="Partners verify with one call">
        Any partner game or platform calls one SDK method. They receive COMPLIANT or NON\_COMPLIANT — plus the achievement tier. No account linking required.
      </Step>
    </Steps>

    ## What Your Players Experience

    Nothing changes at the moment of earning. The credential issues silently. Players see a notification: "You earned a Diamond Rank credential." When they arrive at a partner tournament or airdrop, they tap once to present it. No new account, no form, no ID.

    ## What Compliance Will Ask

    **What data does the credential contain?**
    Your schema defines the claims. This example uses game ID, achievement name, tier, and timestamp. These can still be personal data when linked to a player. Credential payloads are encrypted in DStorage, and users control decryption and disclosure.

    **Can players transfer or sell credentials?**
    Credentials are tied to the user's AIR Account. They are not transferable — which is precisely what makes them useful for anti-cheat and anti-bot purposes.

    **Do we need to change our terms of service?**
    Review your terms and privacy notice for encrypted credential storage, cross-platform verification, and user-controlled disclosure. Confirm that the purposes, recipients, and retention of achievement data are covered by your agreements and applicable requirements.

    ## Integration at a Glance

    | | |
    | - | - |
    | **What your team builds** | One API call in your rank-up / achievement event handler |
    | **Engineering effort** | 1 backend engineer |
    | **Timeline to live** | 2–3 weeks |
    | **Frontend changes** | None required for issuance |
    | **Partner integration** | 3 lines of SDK to verify |

    <CardGroup>
      <Card title="Compliance FAQ" icon="shield-check" href="/solutions/compliance-faq">
        Data handling and GDPR answers.
      </Card>

      <Card title="Partner Economics" icon="coins" href="/solutions/partner-economics">
        Revenue model, fee structure, and rewards.
      </Card>
    </CardGroup>
  </Tab>

  <Tab title="For developers">
    ## What You Can Build

    * **Achievement badges** — Issue a verifiable credential proving a player reached Diamond rank, completed a raid, or earned a title
    * **Cross-game identity** — Let players carry their AIR Account identity and credentials into any game in the Moca ecosystem
    * **Anti-cheat / bot gating** — Verify a player holds a "verified human" or KYC credential before allowing tournament entry
    * **Airdrop gating** — Reward only players who hold specific credentials (e.g. "played > 100 hrs", "held NFT for 90 days")
    * **Guild / DAO membership** — Issue guild membership credentials that gate Discord roles, in-game benefits, and governance votes

    ## Architecture

    ```mermaid theme={null}
    graph TD
        A["In-game event\ne.g. rank achieved, raid completed"] --> B[Game Server]
        B -->|On-demand issuance| C[AIR Kit / Moca Chain]
        C --> D[Achievement Credential in Player's AIR Account]

        D --> E{Player uses credential}
        E --> F[Display badge in game profile]
        E --> G[Enter partner game tournament]
        E --> H[Claim ecosystem airdrop]
        E --> I[Access guild Discord role]
    ```

    ## Recommended Schema

    ```json theme={null}
    {
      "title": "Game Achievement",
      "description": "Verifiable proof of a player achievement or rank",
      "properties": {
        "gameId": {
          "type": "string",
          "description": "Unique identifier of the game"
        },
        "achievementId": {
          "type": "string",
          "description": "Unique identifier of the achievement"
        },
        "achievementName": {
          "type": "string",
          "description": "Display name — e.g. 'Diamond Rank Season 3'"
        },
        "tier": {
          "type": "string",
          "enum": ["Bronze", "Silver", "Gold", "Platinum", "Diamond"],
          "description": "Achievement tier"
        },
        "earnedAt": {
          "type": "string",
          "format": "date-time"
        },
        "season": {
          "type": "string",
          "description": "Game season, e.g. 'Season 3'"
        }
      },
      "required": ["gameId", "achievementId", "achievementName", "earnedAt"]
    }
    ```

    ## Implementation

    ### Step 1 — Issue an achievement credential on rank-up

    ```javascript theme={null}
    // game-server.js
    const { getPartnerJwt } = require('./lib/jwt');
    // issuer-controlled helpers backed by your signing keys
    const { buildVc, signVc, encryptToHolder } = require('./lib/credential');

    const BASE_URL = 'https://api.sandbox.mocachain.org/v1';

    async function issueAchievement({ playerEmail, achievement }) {
      const token = await getPartnerJwt();

      // Resolve the player's AIR Account
      const init = await fetch(`${BASE_URL}/auth/initialize-user`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json', 'x-partner-auth': token },
        body: JSON.stringify({ email: playerEmail }),
      }).then((r) => r.json());

      // Build, sign (SD-JWT VC), and encrypt the credential to the holder
      const schemaId = process.env.ACHIEVEMENT_CREDENTIAL_ID;
      const vc = buildVc({
        holderDid: init.did,
        schemaId,
        credentialSubject: {
          gameId: process.env.GAME_ID,
          achievementId: achievement.id,
          achievementName: achievement.name,
          tier: achievement.tier,
          earnedAt: new Date().toISOString(),
          season: 'Season 3',
        },
      });
      const encrypted = encryptToHolder(signVc(vc), init.publicKey);

      // Store the encrypted envelope in DStorage
      const res = await fetch(`${BASE_URL}/dstorage/vcs`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json', 'x-partner-auth': token },
        body: JSON.stringify({
          holderDid: init.did,
          schemaId,
          expiresAt: vc.expirationDate,
          data: encrypted.encryptedData,
          iv: encrypted.iv,
          authTag: encrypted.authTag,
          encryptedKey: encrypted.dataEncPublicKey,
          externalId: vc.id,
        }),
      });
      if (!res.ok) throw new Error(`Achievement issuance failed: ${res.status}`);
      return res.json(); // { storagePath }
    }

    // Wire into your game's rank-up event system
    gameEvents.on('player:rank_up', async ({ playerEmail, newRank }) => {
      await issueAchievement({
        playerEmail,
        achievement: {
          id: `rank-${newRank.toLowerCase()}`,
          name: `${newRank} Rank`,
          tier: newRank,
        },
      });
      console.log(`Achievement issued to ${playerEmail}: ${newRank}`);
    });
    ```

    ### Step 2 — Gate tournament entry with credential check

    ```javascript theme={null}
    // tournament-gate.js  (frontend or server)
    import { AirService } from '@mocanetwork/airkit';

    import { AirService, BUILD_ENV } from "@mocanetwork/airkit";

    const airService = new AirService({ partnerId: process.env.PARTNER_ID });
    await airService.init({ buildEnv: BUILD_ENV.SANDBOX });

    async function canJoinTournament() {
      const result = await airService.verifyCredential({
        programId: process.env.TOURNAMENT_VERIFY_PROGRAM_ID,
        // Verifier program rule: tier === "Diamond" AND gameId === process.env.GAME_ID
      });
      return result.status === 'COMPLIANT';
    }

    const eligible = await canJoinTournament();
    if (!eligible) {
      showMessage('Reach Diamond rank to enter this tournament.');
    }
    ```

    ### Step 3 — Cross-game SSO with AIR Account

    Partner games authenticate using the same AIR Account — no new signup required.

    ```javascript theme={null}
    // partner-game.js  (any game integrating AIR Kit)
    import { AirService } from '@mocanetwork/airkit';

    const airService = new AirService({ partnerId: 'PARTNER_GAME_PARTNER_ID' });
    await airService.init({ buildEnv: BUILD_ENV.SANDBOX });

    await airService.login(); // player logs in with existing AIR Account
    const user = await airService.getUserInfo();
    // user.email is the same across all games — portable, unified identity
    ```

    ### Step 4 — Bot-resistant airdrop gating

    Only distribute tokens to players who provably hold a real game achievement — filtered by verifiable credentials.

    ```javascript theme={null}
    // airdrop.js  (server-side)
    async function getEligiblePlayers(allPlayers) {
      const eligible = [];
      for (const { email } of allPlayers) {
        // Verify each player against your achievement verification program.
        // In production, batch this with your own DB query first to reduce calls.
        const result = await verifyPlayer(email, process.env.ACHIEVEMENT_VERIFY_PROGRAM_ID);
        if (result.status === 'Compliant') eligible.push(email);
      }
      return eligible;
    }
    ```

    ## Examples

    <CardGroup>
      <Card title="ZK Age Verification — Issuer" icon="github" href="https://github.com/MocaNetwork/air-examples/tree/main/zk-age-verification/issuer">
        Identity provider app: issues age credential; user proves 18+ without revealing date of birth.
      </Card>

      <Card title="ZK Age Verification — Verifier" icon="github" href="https://github.com/MocaNetwork/air-examples/tree/main/zk-age-verification/verifier">
        iGaming or age-gated app: verifies age via ZK proof and grants access; no birthdate disclosure required.
      </Card>
    </CardGroup>

    ## Next Steps

    <Columns>
      <Card title="On-demand Issuance" icon="code" href="/api-reference/issuance-api">
        Full endpoint reference and error codes.
      </Card>

      <Card title="Issuing Credentials (SDK)" icon="badge-check" href="/products/identity/issuing-credentials">
        User-initiated issuance for in-game claim flows.
      </Card>

      <Card title="Schema Use Cases" icon="list" href="/products/identity/schema-use-cases">
        More schema examples including event pass.
      </Card>

      <Card title="AIR for Ticketing & Events" icon="ticket" href="/solutions/ticketing">
        Attendance credentials for live events.
      </Card>
    </Columns>
  </Tab>
</Tabs>


# Identity & Compliance
Source: https://docs.air3.com/solutions/identity

Issue portable KYC credentials with encrypted storage and user-controlled disclosure. Partners configure the claims and proofs needed for verification.

Every platform that needs to verify a user's identity runs its own KYC process and stores a copy of the result. AIR Kit lets you **issue a KYC credential once** that partners can verify using their Verification Programs. ZK proofs can confirm eligibility without revealing underlying values; additional disclosure requires user approval.

<Tabs>
  <Tab title="For business">
    ## The Problem

    Every platform that needs to verify a user's identity runs its own KYC process, stores a copy of the result, and takes on the liability for protecting it. The user goes through the same friction — passport upload, liveness check, waiting period — at every new service they join.

    The industry has accepted this as the cost of compliance. It isn't.

    ## What Changes With AIR Kit

    * **Your customer verifies once** — KYC passed at your platform issues a portable credential. Every partner in the ecosystem accepts it without running KYC again
    * **Control what verifiers receive** — Programs can request ZK proofs of eligibility or specific claims with user approval
    * **Your KYC provider doesn't change** — You keep Jumio, Onfido, Persona, or whoever you use. AIR Kit converts their pass result into a portable credential. The verification itself stays with your provider
    * **Limit copies of identity data** — Raw source documents remain with the issuer or its KYC provider. Encrypted credential payloads may be stored in DStorage, and users control decryption and disclosure. Verifiers remain responsible for protecting any data they receive

    ## Use Cases

    <CardGroup>
      <Card title="KYC Portability" icon="id-card" href="https://air-bd-v2.netlify.app/demo/reusable-kyc">
        Issue a KYC attestation on verification pass. Partner platforms accept it without re-running checks. One verification, ecosystem-wide acceptance.
      </Card>

      <Card title="Age Verification" icon="cake-candles" href="https://air-bd-v2.netlify.app/try-it-live/meet-verified">
        Prove a user is 18+ or 21+ without revealing their birthdate. The verifier learns only the boolean result — the actual age stays private.
      </Card>

      <Card title="Accredited Investor" icon="chart-line">
        Issue an income or net worth attestation for financial products, DeFi access, or private token sales. The verifier never sees the underlying figures.
      </Card>

      <Card title="Professional Credentials" icon="graduation-cap">
        Verify licences, certifications, and professional qualifications. Portable across employers, platforms, and jurisdictions.
      </Card>
    </CardGroup>

    ## How It Works

    <Steps>
      <Step title="User completes KYC with your provider">
        Your existing flow. Your existing KYC provider. Nothing changes for the user or your team at this step.
      </Step>

      <Step title="Your backend issues a KYC credential">
        The moment your KYC provider returns a pass result, your backend calls on-demand issuance. One call. The credential issues silently — no user action needed.
      </Step>

      <Step title="Credential lands in the user's AIR Account">
        The user can access an issuer-signed credential encrypted to their public key and stored in DStorage. The issuer retains the source documents, while the user controls decryption and disclosure of the credential.
      </Step>

      <Step title="Any partner verifies via ZK proof">
        At a partner service, the user approves the requested disclosure. The partner receives a compliance result and, on success, a Verifiable Presentation containing the approved claims and any required proof.
      </Step>
    </Steps>

    ## What the Verifier Actually Sees

    The following example uses a program that requests KYC status and limited claims with user approval. Other programs can request different disclosures.

    | What the Verifier Receives | What Stays Private |
    | - | - |
    | COMPLIANT / NON\_COMPLIANT | Full name, passport number |
    | KYC level (basic / enhanced / full) | Date of birth |
    | `isOver18: true` | Residential address |
    | Credential expiry date | National ID / tax number |
    | Issuer identifier | Income, net worth, financial data |

    [Try it live](https://air-bd-v2.netlify.app/try-it-live/meet-verified): a marketplace learns only that the user passed an ID check.

    ## What Compliance Will Ask

    **Is this GDPR Article 5(1)(c) compliant — data minimisation?**
    Use the minimum claims needed for the check, such as KYC level and `isOver18`. These derived claims can still be personal data. Credential encryption and user-controlled disclosure support minimisation, but compliance depends on your implementation.

    **How do we handle data subject deletion requests?**
    Revoke the credential to stop future successful checks once its revoked status is available. Handle deletion of source records, encrypted payloads, metadata, and disclosed copies separately. See the [Compliance FAQ](/solutions/compliance-faq).

    **Who has access to the underlying identity documents?**
    Raw source documents remain with the issuer or its KYC provider. AIR may store encrypted credential payloads in DStorage.

    **What if a user disputes their KYC result?**
    The dispute process stays entirely with your KYC provider, as it does today. You revoke or re-issue the AIR Kit credential once the dispute resolves.

    **Does AIR Kit have access to our users' data?**
    Your backend signs the credential and encrypts it to the holder before storage. AIR stores and routes ciphertext and metadata, not plaintext issuer data. The user controls decryption and disclosure; encrypted claims and metadata may still be personal data.

    ## Integration at a Glance

    | | |
    | - | - |
    | **What your team builds** | One API call in your KYC webhook / callback handler |
    | **Engineering effort** | 1 backend engineer |
    | **Timeline to live** | 2–3 weeks |
    | **Changes to your KYC provider setup** | None |
    | **What partners build** | 3 lines of SDK code to verify |

    ## Next Steps

    <CardGroup>
      <Card title="Full Compliance FAQ" icon="shield-check" href="/solutions/compliance-faq">
        GDPR, CCPA, data residency, and breach liability answers.
      </Card>

      <Card title="Architecture & Data Flow" icon="diagram-project" href="/technicals/architecture">
        ZK proof flow explained end-to-end.
      </Card>

      <Card title="Talk to our team" icon="handshake" href="https://air3.com/partner-with-us">
        Start a partnership conversation.
      </Card>
    </CardGroup>
  </Tab>

  <Tab title="For developers">
    Identity credentials are issued and verified with the same AIR Kit flows used across every vertical. Start with the managed KYC service if you need identity verification out of the box, or wire your existing KYC provider into on-demand issuance.

    <CardGroup>
      <Card title="KYC (Veriff powered by zkMe)" icon="id-card" href="/solutions/kyc">
        Managed identity verification that issues a KYC credential on pass. How it works, data handling, and pricing.
      </Card>

      <Card title="Issue a KYC credential on event" icon="code" href="/get-started/recipes/issue-kyc-credential">
        Recipe: convert your KYC provider's pass result into a portable credential from a backend webhook.
      </Card>

      <Card title="Quickstart: verify credentials" icon="shield-check" href="/get-started/quickstarts/verify-credentials">
        Verify a credential and handle a Verifiable Presentation with program-defined disclosures.
      </Card>

      <Card title="Fintech & Payments" icon="credit-card" href="/solutions/fintech">
        KYC credential schema, webhook code, and verification patterns in the Fintech developer guide.
      </Card>
    </CardGroup>
  </Tab>
</Tabs>


# AIR Kit solutions by industry vertical
Source: https://docs.air3.com/solutions/index

Explore AIR Kit by industry: portable credentials for loyalty, gaming, advertising, ticketing, fintech, and telco. No code required to evaluate the fit.

Explore what AIR Kit enables by industry — no code required. For implementation and integration guides, see [AIR Kit](/get-started/what-is-airkit).

AIR Kit is the integration layer that lets your platform issue verifiable credentials — proofs of identity, membership, loyalty status, or any user attribute — that your customers can carry and reuse across your partner ecosystem.

Your customers stop re-verifying. Your partners stop building bilateral APIs with you. Your compliance team stops holding raw PII they don't need to hold.

## Two Ways to Use These Docs

<CardGroup>
  <Card title="I'm evaluating AIR Kit" icon="briefcase" href="/products/loyalty/business">
    Explore what AIR Kit enables for your vertical. No code, no technical setup required.
  </Card>

  <Card title="I'm ready to integrate" icon="code" href="/get-started/dashboard/account-setup">
    Jump to the developer Quick Setup and integration guides.
  </Card>
</CardGroup>

**See it first:** the [AIR Kit demo site](https://air-bd-v2.netlify.app/overview) walks through [user onboarding](https://air-bd-v2.netlify.app/onboarding), [data monetization](https://air-bd-v2.netlify.app/data-monetization), and [wallets and payments](https://air-bd-v2.netlify.app/wallets), or you can [try it live](https://air-bd-v2.netlify.app/try-it-live).

## What AIR Kit Does

At its core, AIR Kit enables three things:

**1. Issue credentials from your existing backend**
When a business event happens — a user passes KYC, reaches loyalty Gold, activates a subscription — your backend fires one API call. A verifiable credential lands in that user's AIR Account. No user action required, no wallet to open.

**2. Verify credentials at any point of use**
When that user shows up at your app, a partner's app, or any service in the ecosystem, one SDK call checks their credential against your Verification Program. Successful verification returns a Verifiable Presentation with user-approved claims and any required proof. A program can use a ZK proof to check a condition without revealing the underlying value.

**3. Let credentials travel across platforms**
The credential belongs to the user, not your database. A loyalty Gold earned with you is presentable at a partner hotel, airline, or retailer — without a direct API agreement between you and that partner. The credential is the integration.

## Which Vertical Fits Your Business

<CardGroup>
  <Card title="Loyalty & Rewards" icon="gift" href="/products/loyalty/business">
    Cross-brand tier portability. No bilateral APIs. No unredeemed point silos.
  </Card>

  <Card title="Identity & Compliance" icon="shield-check" href="/solutions/identity">
    Portable KYC credentials with encrypted storage and user-controlled disclosure.
  </Card>

  <Card title="Fintech & Payments" icon="credit-card" href="/solutions/fintech">
    Compliance gating, accredited investor proofs, age verification without DOB storage.
  </Card>

  <Card title="Gaming & Entertainment" icon="gamepad" href="/solutions/gaming">
    Portable player achievements, cross-game identity, bot-resistant airdrop gating.
  </Card>

  <Card title="Telco & Subscriptions" icon="signal" href="/solutions/telco">
    Subscriber KYC portability for roaming, MVNO, and partner services.
  </Card>

  <Card title="Advertising & Audiences" icon="megaphone" href="/solutions/advertising">
    Verified audience segments without cookies. Age-gated serving without storing DOB.
  </Card>

  <Card title="KYC (Veriff powered by zkMe)" icon="id-card" href="/solutions/kyc">
    Turnkey KYC, AML, and NFC ePassport verification — legally provided by zkMe , issued as AIR Credentials.
  </Card>
</CardGroup>

## Common Questions

<AccordionGroup>
  <Accordion title="Do our users need a crypto wallet?">
    No. AIR Account is a smart account — users authenticate with email, social login, or passkey. The blockchain layer is invisible to them.
  </Accordion>

  <Accordion title="How long does integration take?">
    Most partners are live in 2–4 weeks for a backend engineer. The core integration is one API call in your existing event handler.
  </Accordion>

  <Accordion title="Does AIR Kit replace our KYC provider?">
    No. You keep your existing KYC provider. AIR Kit converts the pass result into a portable credential. Your provider still runs the verification.
  </Accordion>

  <Accordion title="Where does our customer data go?">
    Raw source documents remain with the issuer. Encrypted credential payloads may be stored in DStorage, while users control decryption and disclosure. See the [Compliance FAQ](/solutions/compliance-faq) for full detail.
  </Accordion>
</AccordionGroup>


# Connect your agent
Source: https://docs.air3.com/solutions/integrating-using-ai

Add the AIR docs MCP server to your agent, then start building.

## Connect via MCP

Choose your tool below and add the AIR documentation server:

```text theme={null}
https://docs.air3.com/mcp
```

<Tabs>
  <Tab title="Claude">
    <Steps>
      <Step title="Add the Moca Network MCP server to Claude">
        1. Navigate to the [Connectors](https://claude.ai/settings/connectors) page in the Claude settings.
        2. Select **Add custom connector**.
        3. Add the Moca Network MCP server:
           * Name: `MocaNetwork`
           * URL: `https://docs.air3.com/mcp`
        4. Select **Add**.
      </Step>

      <Step title="Access the MCP server in your chat">
        1. When using Claude, select the attachments button (the plus icon).
        2. Select the MocaNetwork MCP server.
        3. Ask Claude a question about Moca Network or AIR Kit.
      </Step>
    </Steps>

    See the [Model Context Protocol documentation](https://modelcontextprotocol.io/docs/tutorials/use-remote-mcp-server#connecting-to-a-remote-mcp-server) for more details.
  </Tab>

  <Tab title="Claude Code">
    <Steps>
      <Step title="Add the MCP server to Claude Code">
        Run the following command:

        ```bash theme={null}
        claude mcp add --transport http MocaNetwork https://docs.air3.com/mcp
        ```
      </Step>

      <Step title="Test the connection">
        Verify the connection by running:

        ```bash theme={null}
        claude mcp list
        ```
      </Step>
    </Steps>

    See the [Claude Code documentation](https://docs.anthropic.com/en/docs/claude-code/mcp#installing-mcp-servers) for more details.
  </Tab>

  <Tab title="Cursor">
    <Steps>
      <Step title="Open MCP settings">
        1. Use <kbd>Command</kbd> + <kbd>Shift</kbd> + <kbd>P</kbd> (<kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>P</kbd> on Windows) to open the command palette.
        2. Search for "Open MCP settings".
        3. Select **Add custom MCP**. This opens the `mcp.json` file.
      </Step>

      <Step title="Configure the Moca Network MCP server">
        In `mcp.json`, add:

        ```json theme={null}
        {
          "mcpServers": {
            "MocaNetwork": {
              "url": "https://docs.air3.com/mcp"
            }
          }
        }
        ```
      </Step>

      <Step title="Test the connection">
        In Cursor's chat, ask "What tools do you have available?" Cursor should show the MocaNetwork MCP server as an available tool.
      </Step>
    </Steps>

    See the [Cursor documentation](https://docs.cursor.com/en/context/mcp#installing-mcp-servers) for more details.
  </Tab>

  <Tab title="VS Code">
    <Steps>
      <Step title="Create MCP configuration">
        Create a `.vscode/mcp.json` file in your project root.
      </Step>

      <Step title="Configure the Moca Network MCP server">
        In `.vscode/mcp.json`, add:

        ```json theme={null}
        {
          "servers": {
            "MocaNetwork": {
              "type": "http",
              "url": "https://docs.air3.com/mcp"
            }
          }
        }
        ```
      </Step>
    </Steps>

    See the [VS Code documentation](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) for more details.
  </Tab>
</Tabs>

For another MCP-compatible tool, add the URL as a remote HTTP MCP server in its connection settings.

## Try your first prompt

Once connected, ask your agent to look up the docs and help with a specific task:

```text theme={null}
Use the AIR docs MCP server to help me add AIR Kit login to my app.
Check my framework and existing authentication, then explain the setup
and changes before implementing them.
```

You can also ask about credential issuance and verification, wallet transactions, or integration errors. Include your framework and what you have already built.

## Choose your setup

| Option | What it provides | When to use it |
| - | - | - |
| **Docs MCP** | Searchable AIR documentation, SDK guides, and API references. | Start here for current reference material. |
| **AIR skill** | Integration workflows and checks for setup, authentication, and common errors. | Add alongside MCP for guidance while building. |
| **Static docs** | Documentation files you attach or index in your tool. | Use when your tool cannot connect through MCP; refresh the files as docs change. |

Your agent uses these resources to plan, write, and review integration code. Live AIR operations run through your application's configured account, authentication, and programs.

## Add the AIR skill (optional)

For tools that support [Agent Skills](https://agentskills.io/home), run:

```bash theme={null}
npx skills add https://docs.air3.com
```

Select your agent in the CLI to install the skill.

<Accordion title="Before issuing or verifying credentials">
  Ask your agent to confirm these prerequisites before generating application code:

  * Your partner's public JWKS endpoint is reachable over HTTPS.
  * The exact JWKS URL is registered in the Developer Dashboard.
  * Your JWT signing key stays server-side, and its `kid` matches a published JWKS key.

  Follow [JWKS endpoint setup](/get-started/authentication/jwks-endpoint), then use the [issuance](/products/identity/issuing-credentials) or [verification](/products/identity/verify) guide for your flow.
</Accordion>

<Accordion title="Use static documentation files">
  ## Static docs files

  If your AI tool does not support MCP yet, you can use one of Moca Network's static documentation files instead.

  <Warning>
    Static files are snapshots and may not include the latest updates. Use MCP when possible for always-current docs.
  </Warning>

  ## Which file should I use?

  * **`llms.txt`** — A curated overview of Moca Network. Use it to route an agent to the right docs, understand product structure, and choose the right integration path.
  * **`llms-full.txt`** — A full static snapshot of the documentation. Use it when your tool needs more exhaustive reference material in one file.

  ## Setup with Cursor

  <Steps>
    <Step title="Open docs settings">
      Go to **Settings** → **Features** → **Docs**.
    </Step>

    <Step title="Add the overview file">
      Click **Add new doc** and paste: `https://docs.air3.com/llms.txt`
    </Step>

    <Step title="Optionally add the full snapshot">
      If your agent needs deeper static reference coverage, add: `https://docs.air3.com/llms-full.txt`
    </Step>

    <Step title="Reference in chat">
      Use **@docs** → **Moca** in your AI chat to reference the documentation.
    </Step>
  </Steps>

  ## Setup with Claude Desktop

  <Steps>
    <Step title="Download the overview file">
      Download the curated overview from: [https://docs.air3.com/llms.txt](https://docs.air3.com/llms.txt)
    </Step>

    <Step title="Optionally download the full snapshot">
      Download the full documentation snapshot from: [https://docs.air3.com/llms-full.txt](https://docs.air3.com/llms-full.txt)
    </Step>

    <Step title="Add to your project">
      Save one or both files in your project directory or another known location on your system.
    </Step>

    <Step title="Reference in chat">
      Drag and drop the file into your Claude Desktop chat, or use the attachment button to upload it. Claude will then have access to the uploaded Moca Network documentation context for that conversation.
    </Step>
  </Steps>
</Accordion>


# Data collection & sharing
Source: https://docs.air3.com/solutions/kyc/data-collection-and-sharing

Data lifecycle for Moca's on-chain KYC — what users submit, what partners receive, what is anchored on-chain, and how disclosure modes work.

This page is for **legal, compliance, and security reviewers** evaluating **Veriff powered by zkMe** — Moca Network's **on-chain IDV/KYC solution** — alongside AIR Kit on Moca Network. It complements [How it works](/solutions/kyc/how-it-works) and [zkMe security architecture](/solutions/kyc/zkme-security-architecture).

The **disclosure spectrum** (pass/fail and selective attributes) is summarized on the [KYC overview](/solutions/kyc) under **Disclosure flexibility**.

***

## What the user provides

Typical inputs across programmatic and manual paths include:

| Category | Examples | Purpose |
| - | - | - |
| Identity document | Passport, national ID, driver's license, residence permit | Document authenticity, MRZ/OCR, chip read where NFC applies |
| Biometrics | Selfie images or video, liveness challenge | Match user to document portrait; fraud resistance |
| Device signals | IP address, coarse geo, device metadata | Risk scoring and sanctions workflows |
| NFC chip payload | ePassport / eID chip data | Cryptographic authenticity (zkPassport path) |

Exact fields depend on the verification program configured for your partnership. **Your application does not need to persist these artifacts** to participate in the **on-chain IDV/KYC model** unless your own compliance policy requires local copies.

***

## What the partner receives

What your platform and downstream verifiers see depends entirely on the **verification program** — not on a single fixed "privacy mode."

| Data | When does the partner or verifier receive it? |
| - | - |
| Passport / ID images | Not delivered to verifiers. Stays under zkMe's protection model. |
| MRZ text, structured chip fields | Not delivered as raw fields. Programs can request specific attributes derived from them. |
| Selfie / liveness media | Not delivered to verifiers. |
| AML policy outputs | Usually reflected as **credential attributes** or pass/fail eligibility (for example sanctions-clear flag). Raw vendor hit detail is not delivered to verifiers. |
| **AIR Credential** reference and attributes | **Yes** — whatever the Issuance program encodes (for example `kycLevel`, `isOver18`, compliance flags) for selective or pass/fail modes. |
| **Verifier outcome** | **Yes** — from a simple **COMPLIANT** / **NON\_COMPLIANT** signal through to the **selective attributes** the program requests and the user approves. |

Partners should treat the credential and verification program as the **integration contract**: define the minimum disclosure that meets each use case, and rely on revocation and re-issuance when users or regulators require updates.

***

## What Moca Chain stores

Raw source documents remain with the issuer, which is zkMe for this KYC offering. Encrypted credential payloads may be stored in **DStorage**, while users control decryption and disclosure. AIR stores and routes ciphertext and metadata, not plaintext issuer data.

Storage providers hold encrypted payloads; Moca Chain records storage metadata and state. Verification proofs are submitted on-chain when the Verification Program requires it. These records are distinct from the credential payloads and the issuer's source documents. Encryption does not automatically remove personal-data obligations; see the [Compliance FAQ](/solutions/compliance-faq).

***

## What zkMe holds

**zkMe** operates the verification orchestration for **Veriff powered by zkMe** and **encrypts sensitive verification payloads** under the **zkVault** model (hardware-backed trusted execution, threshold encryption, and supporting cryptography — summarized on [zkMe security architecture](/solutions/kyc/zkme-security-architecture)).

zkMe stores the original verification material so it can be **re-issued**, **refreshed**, or **partially or fully disclosed** in line with each verifier's program configuration and the **user's consent**. Retention follows regulated identity-provider practices: fraud investigation, regulatory inquiry support, and operational quality — not resale to unrelated third parties.

***

## How the verification stack fits together

End-user verification sessions for **Veriff powered by zkMe** may execute on infrastructure operated under **zkMe's** commercial and technical arrangements. Outputs are consumed by **zkMe** as the **legal and contracting party** for your Moca-facing KYC bundle. Partners contract for this path with **zkMe** only.

Always refer to the offering in public materials as **Veriff powered by zkMe** — use the full product name, not a shortened form.

***

## Disclosure spectrum (configured per verification program)

Two common patterns — both are **first-class** options:

1. **Pass/fail** — the verifier receives only an eligibility boolean (for example **COMPLIANT** / **NON\_COMPLIANT**).
2. **Selective disclosure** — the verifier receives an agreed subset of attributes from the credential (and any attached proofs your schema defines).

<CardGroup>
  <Card title="Selective disclosure" icon="eye-slash" href="/products/identity/selective-disclosure">
    AIR Kit capability for attribute-level presentation controls.
  </Card>

  <Card title="Privacy & compliance" icon="scale-balanced" href="/technicals/architecture/privacy-and-compliance">
    Encryption, ZK proofs, and user consent on Moca Network.
  </Card>
</CardGroup>

***

## Pass/fail program (eligibility-only signal)

When the verification program is configured for **eligibility only**, a typical verifier sees:

| Verifier may receive | Not part of this program unless separately requested |
| - | - |
| **COMPLIANT** / **NON\_COMPLIANT** | Full legal name, document number, DOB, address |
| Credential identifier, expiry, issuer DID | Passport / ID images, selfie video |
| (Optional) a small set of boolean flags encoded in the credential schema | MRZ or raw AML vendor payloads |

For **selective** programs, the left column expands to include whichever attributes the schema and verification program expose (for example `kycLevel`, `isOver18`).

Exact fields depend on your **credential schema** and **verification program** configuration in the Developer Dashboard.

***

## Related reading

<CardGroup>
  <Card title="Overview" icon="book" href="/solutions/kyc" />

  <Card title="zkMe security architecture" icon="shield-halved" href="/solutions/kyc/zkme-security-architecture" />

  <Card title="Pricing & FAQ" icon="circle-dollar" href="/solutions/kyc/pricing-and-faq" />
</CardGroup>


# How Veriff powered by zkMe works
Source: https://docs.air3.com/solutions/kyc/how-it-works

End-to-end on-chain KYC on Moca Network — programmatic and manual verification, AML screening, AIR Credential issuance, and per-program verifier outcomes.

This page describes the **product flow** for **Veriff powered by zkMe**, the **on-chain IDV/KYC solution** on Moca Network. It is not an integration guide; for AIR Kit setup and APIs, see [AIR Kit](/get-started/what-is-airkit).

***

## End-to-end flow

<Steps>
  <Step title="User starts verification in your app">
    The user launches the **Veriff powered by zkMe** experience inside your application (AIR Kit surfaces the flow; your product does not need to host raw KYC storage to participate).
  </Step>

  <Step title="Programmatic path (default)">
    The user completes document capture, **NFC chip read** where the document supports it (electronic passport / eID), **liveness**, and **face matching**. On supported documents, **zkPassport** establishes cryptographic authenticity of the chip (ICAO-style passive authentication). The verified outcome feeds the **AIR Credential** with whatever **disclosure level** the issuance and verification programs require — from pass/fail only through selective attributes.
  </Step>

  <Step title="AML and sanctions screening">
    Screening runs as part of the **on-chain IDV/KYC pipeline** so the resulting credential reflects both **identity** and **financial crime compliance** signals your programs require.
  </Step>

  <Step title="Manual reverification (when needed)">
    If the automated path cannot complete — for example unreadable chip, document edge case, or biometric mismatch — the session moves to **human review** under **Veriff powered by zkMe**. From the user's perspective this matches a traditional eKYC outcome: approved, rejected, or more information requested.
  </Step>

  <Step title="Credential issuance (AIR)">
    On success, **zkMe** (as Issuer) issues an **AIR Credential** into the user's **AIR Account**. Cryptographic commitments anchor on **Moca Chain**; sensitive payloads remain under zkMe's protection model (see [Data collection & sharing](/solutions/kyc/data-collection-and-sharing) and [zkMe security architecture](/solutions/kyc/zkme-security-architecture)).
  </Step>

  <Step title="Verification at any partner">
    When the user presents the credential elsewhere in the ecosystem, the verifier calls AIR Kit verification and receives **whatever the verification program is configured to return** — a pass/fail signal or a selective set of attributes, with user approval.
  </Step>
</Steps>

***

## Sequence overview

```mermaid theme={null}
sequenceDiagram
  participant User
  participant PartnerApp as PartnerApp
  participant VpZ as VeriffPoweredByZkMe
  participant ZkMeIssuer as ZkMeIssuer
  participant MocaChain as MocaChain
  participant Verifier as VerifierApp

  User->>PartnerApp: Start KYC
  PartnerApp->>VpZ: Verification session
  alt ProgrammaticPass
    VpZ->>User: NFC_liveness_doc
    VpZ->>ZkMeIssuer: PassPlusAML
  else ManualReview
    VpZ->>VpZ: HumanReview
    VpZ->>ZkMeIssuer: PassOrFail
  end
  ZkMeIssuer->>MocaChain: CredentialAnchor
  ZkMeIssuer->>User: AIRCredentialInWallet
  User->>Verifier: PresentCredential
  Verifier->>MocaChain: VerifyCredential
  Verifier->>User: AccessDecision
```

***

## Geographic coverage (zkPassport)

For **electronic passport** flows that rely on published country signing keys, **zkPassport** supports a large set of issuing countries. Documents from other jurisdictions may still be verified through the **document-and-biometric** path without NFC, subject to **Veriff powered by zkMe** coverage rules.

For the authoritative country list, see zkMe documentation: [Supported countries](https://docs.zk.me/hub/how-built/id-infra/zkpassport/supported-countries).

***

## Related reading

<CardGroup>
  <Card title="Overview" icon="book" href="/solutions/kyc">
    On-chain IDV/KYC positioning, disclosure flexibility, and what the bundle includes.
  </Card>

  <Card title="Data lifecycle" icon="database" href="/solutions/kyc/data-collection-and-sharing">
    What each party sees and stores across pass/fail and selective modes.
  </Card>
</CardGroup>


# KYC (Veriff powered by zkMe)
Source: https://docs.air3.com/solutions/kyc/index

Turnkey KYC for Moca partners — document checks, NFC ePassport, liveness, AML screening, and manual review, issued as portable AIR Credentials by zkMe.

**Veriff powered by zkMe** is Moca Network's **on-chain IDV/KYC solution**. The bundled pipeline runs document, biometric, liveness, and AML checks; on success, **zkMe** issues a portable **AIR Credential** that any partner in the ecosystem can verify — without you running a separate KYC vendor procurement or holding raw identity data on your servers.

**Disclosure is configurable per verification program.** Verifiers can receive a simple pass/fail eligibility signal or a selective set of attributes.

***

## What the on-chain IDV/KYC bundle includes

* **Programmatic IDV** — including **zkPassport**-style NFC reading of ICAO-compliant electronic passports and national eIDs where supported, with **strong document authenticity** via NFC chip signatures — the same class of evidence as high-assurance eKYC, feeding whatever disclosure level your verification program defines.
* **Manual reverification** — if automated checks cannot reach a decision (poor NFC read, edge-case document, biometric mismatch), the case escalates to human review under the **Veriff powered by zkMe** operator workflow — the same review path as a classic eKYC session.
* **AML and sanctions screening** — bundled as part of the **on-chain IDV/KYC pipeline** (not optional add-ons you must source separately).
* **Face matching and liveness** — standard components of compliant identity verification.

***

## Disclosure flexibility

Each **verification program** in the Developer Dashboard defines what downstream verifiers receive. Typical patterns:

* **Pass/fail** — a single eligibility signal (for example **COMPLIANT** / **NON\_COMPLIANT**) with no underlying document fields.
* **Selective disclosure** — an explicit subset of attributes (for example `kycLevel`, `isOver18`, country band) without sharing the full KYC packet.

```mermaid theme={null}
flowchart LR
  passFail["PassFail eligibility signal"]
  selective["Selective attribute set"]
  passFail --> selective
```

For selective disclosure product detail on AIR Kit, see [Selective disclosure](/products/identity/selective-disclosure).

***

## Next steps

<CardGroup>
  <Card title="How it works" icon="diagram-project" href="/solutions/kyc/how-it-works">
    Programmatic verification, manual fallback, AML, credential issuance, and verifier outcomes — end to end.
  </Card>

  <Card title="Data collection & sharing" icon="database" href="/solutions/kyc/data-collection-and-sharing">
    What is collected, what partners see, what lands on Moca Chain, and how disclosure modes work.
  </Card>

  <Card title="zkMe security architecture" icon="shield-halved" href="/solutions/kyc/zkme-security-architecture">
    zkPassport, zkVault, homomorphic face matching, and credential cryptography — in Moca context.
  </Card>

  <Card title="Pricing & FAQ" icon="circle-dollar" href="/solutions/kyc/pricing-and-faq">
    Per-check pricing, what is included, and how disclosure level is chosen per verification program.
  </Card>
</CardGroup>


# Pricing & FAQ
Source: https://docs.air3.com/solutions/kyc/pricing-and-faq

Pricing and FAQ for Moca's on-chain KYC (Veriff powered by zkMe) — per-check pricing for automated and manual paths, contracting, and disclosure modes.

Pricing for **Veriff powered by zkMe**, Moca Network's **on-chain IDV/KYC solution**.

Pricing figures below follow **zkMe's public list pricing** communicated for this partnership model. **Moca Chain** transaction fees (gas, storage operations) are **separate** — your finance team should model both zkMe verification charges and on-chain costs for issuance and verification traffic.

***

## Pricing

| Check type | Price (USD) | When it applies |
| - | - | - |
| **Automated verification** | **\$0.50** per credential | User completes the programmatic path successfully; credential issued for the agreed validity window. |
| **Manual reverification** | **\$1.50** per credential | Automated path cannot complete; case is resolved via human review under **Veriff powered by zkMe**, then a credential is issued or the user fails. |

Billing semantics (per issuance year, refresh rules, volume discounts) should be confirmed in your **order form or statement of work** with **zkMe**. Published zkMe materials describe pay-as-you-go credential billing; enterprise volume may differ.

***

## FAQ

### Who is my contracting party?

**zkMe.** Services for this turnkey path are legally provided by zkMe. You do **not** need a separate direct agreement outside **zkMe** for the standard **Veriff powered by zkMe** bundle described in these docs.

### How should we refer to the product in writing?

Always use the full product name **Veriff powered by zkMe**. Do not shorten it in customer-facing materials.

### What does the verifier actually receive?

It depends on how you configure each **verification program**:

* **Pass/fail** — typically a single eligibility outcome (for example **COMPLIANT** / **NON\_COMPLIANT**) plus credential metadata your schema defines.
* **Selective disclosure** — the verifier receives only the attributes and proofs the program asks for (for example tier, age gate, jurisdiction band).

### Is AML screening included?

Yes. **Sanctions and AML screening** are part of the regulated identity bundle — not an optional third SKU you must license separately for this path.

### Are liveness and face matching included?

Yes. They are standard components of compliant **KYC** and are part of **Veriff powered by zkMe**.

### What happens if NFC or automation fails?

The user may be routed to **manual reverification**. Pricing for that path is the **\$1.50** manual rate (see table above). From a product perspective the experience matches traditional eKYC with human review.

### What do we store on our servers?

Many partners rely on **AIR Credentials** and verifier outcomes without duplicating raw KYC media on their own infrastructure. If your policy or regulator requires local retention, that is a separate architectural decision; coordinate with your compliance team and with **zkMe** contract terms.

### Can a verifier ever see raw KYC fields?

Verifiers receive the pass/fail outcome or the attributes their **verification program** requests and the user approves. If your use case requires access to raw KYC documents, contact the AIR team.

### Where is zkPassport supported?

See zkMe's published list: [Supported countries](https://docs.zk.me/hub/how-built/id-infra/zkpassport/supported-countries). Other documents may still verify without NFC subject to program rules.

***

## Related reading

<CardGroup>
  <Card title="How it works" icon="route" href="/solutions/kyc/how-it-works" />

  <Card title="Privacy & compliance" icon="scale-balanced" href="/technicals/architecture/privacy-and-compliance" />

  <Card title="Contact us" icon="envelope" href="https://air3.com/partner-with-us" />
</CardGroup>


# zkMe security architecture
Source: https://docs.air3.com/solutions/kyc/zkme-security-architecture

Security architecture behind Moca's on-chain KYC — zkPassport trust anchors, zkVault encryption, homomorphic face matching, and on-chain credential proofs.

Behind Moca Network's **on-chain IDV/KYC solution**, **zkMe** contributes the cryptographic stack summarized below. The content below summarizes **public zkMe Protocol documentation** in language consistent with Moca Network. It explains how **zkMe** under **Veriff powered by zkMe** acts as a **credential Issuer** and how cryptographic components support **pass/fail** and **selective** disclosure models on AIR Kit. For the canonical technical detail, see [zkMe docs — Architecture](https://docs.zk.me/hub/how-works/architecture) and [zkPassport](https://docs.zk.me/hub/how-built/id-infra/zkpassport).

***

## zkPassport: cryptographic trust for documents

Traditional document verification infers authenticity from **images**. **zkPassport** instead anchors trust in **sovereign-issued public key infrastructure** (PKI) embedded in ICAO-style **electronic passports** and compatible eIDs:

* The chip stores **signed data groups** and a **Security Object Document (SOD)** chaining to the issuing country's **Document Signer** and **Country Signing Certification Authority (CSCA)**.
* **Passive authentication** proves chip data was signed by a legitimate national issuer and was not tampered with since issuance — without a "confidence score," only pass or fail.
* **zkPassport** reads the chip over **NFC on the user's device**, validates the certificate chain against known trust material (for example ICAO PKD and related registries), and builds **zero-knowledge proofs** so relying parties learn **attribute statements** (for example nationality band, age threshold, document not expired) rather than full plaintext chip payloads.

This directly mitigates **synthetic document** risk for the NFC path: a convincing image does not forge a valid **CSCA-backed** signature.

***

## zkVault: encrypted secrets and regulated payloads

zkMe's **zkVault** is an encrypted storage and execution model for sensitive material (including secrets relevant to **AI agent** scenarios in zkMe's broader roadmap). For identity, the important properties are:

* **AES-256-GCM** encryption for data at rest.
* **Threshold encryption** and **Shamir secret sharing** so no single operator party can arbitrarily decrypt user payloads.
* **Trusted Execution Environments (TEEs)** — Intel SGX / AMD SEV — so decryption and high-risk operations occur inside **attested enclaves** rather than in ordinary application memory.

Partners on Moca still receive **AIR Credentials** and **program-configured verification outcomes** (pass/fail or selective attributes as defined per verification program); they do not host zkVault.

***

## Face binding without exposing raw biometrics

zkMe documentation describes using **fully homomorphic encryption (FHE)** in the **CKKS** family to compare **encrypted facial feature vectors** — enabling **face-to-identity** binding with reduced plaintext biometric handling compared to naive pipelines. This is complementary to liveness vendors and document portraits in **Veriff powered by zkMe**.

***

## Credentials: Merkle commitments and ZK verification

zkMe's credential system (W3C Verifiable Credentials style, JSON-LD claims) uses:

* **Sparse Merkle trees** and **Poseidon** hashing on the **Baby JubJub** curve for compact commitments.
* **Groth16** zk-SNARKs for efficient on-chain verification of proofs.
* **Selective disclosure** patterns so a verification program can request a specific subset of attributes.
* **Anti-sybil** tooling such as **nullifiers** where "one person, one action" guarantees matter.

On **Moca Network**, your integration still lands as an **AIR Credential** with on-chain anchoring and AIR Kit verifier flows — the zkMe cryptographic stack sits **behind** Issuance operated by zkMe for this product bundle.

***

## How this connects to AIR Kit on Moca

```mermaid theme={null}
flowchart LR
  subgraph userDevice [UserDevice]
    NFC[NFC_read]
    ZKP[ZKP_generate]
  end
  subgraph zkMe [ZkMeLabs]
    VpZ[VeriffPoweredByZkMe]
    Vault[ZkVault_encrypted]
    Issuer[Issuer_DID]
  end
  subgraph moca [MocaNetwork]
    Chain[MocaChain_commitments]
    AIR[AIRKit_verify]
  end

  NFC --> ZKP
  VpZ --> Vault
  Vault --> Issuer
  Issuer --> Chain
  AIR --> Chain
```

***

## External references

* [zkMe — Architecture overview](https://docs.zk.me/hub/how-works/architecture)
* [zkMe — zkPassport](https://docs.zk.me/hub/how-built/id-infra/zkpassport)
* [zkMe — Supported countries (zkPassport)](https://docs.zk.me/hub/how-built/id-infra/zkpassport/supported-countries)


# Partner Economics
Source: https://docs.air3.com/solutions/partner-economics

How the AIR Kit revenue model works for issuers, verifiers, and ecosystem partners — reward sharing, transaction fees, and the data marketplace.

AIR Kit is a two-sided network. Issuers earn by enabling verifications. Verifiers earn by participating in the ecosystem. The model is designed so that the more credentials circulate, the more value returns to the partners who issued them.

***

## The Three Revenue Streams

### 1. Rewards Sharing (Issuers)

When a user's AIR Account holds stablecoin-backed AIR SP points, the reward generated by the underlying reserves is split between the network and the issuing partner.

The default split is **95% to the partner, 5% to Moca Network**.

This means every active user you onboard — who holds a balance in their AIR Account — generates ongoing reward for you without any transaction being required.

### 2. Verification Fees (Verifiers)

When a third-party verifier checks one of your credentials, a micro-fee is collected. A portion of that fee flows back to you as the issuer.

This creates a direct economic incentive to issue high-quality, widely-accepted credentials: the more partners verify your credentials, the more fee revenue you earn.

### 3. Data Marketplace (Opt-in)

Partners who choose to participate can list anonymised, consent-backed audience segments in the Moca data marketplace. Advertisers and third parties pay to access verified segments. Revenue shares to the issuing partner.

Participation in the data marketplace is entirely opt-in and requires explicit user consent at the credential level.

***

## What This Looks Like in Practice

**A loyalty programme partner** issues tier credentials to 2 million members. 800,000 of those members hold AIR SP balances. The partner earns reward on those balances at a 95/5 split. Simultaneously, 50 partner retailers verify those tier credentials 4 million times per year — generating per-verification fee revenue for the issuing brand.

**A fintech partner** issues KYC credentials to their verified user base. Partner financial services verify those credentials for onboarding. The fintech earns a share of each verification fee — effectively monetising their KYC investment for the first time.

**A publisher** issues consent and audience credentials. Advertisers query those credentials at ad-serve time. The publisher earns per-query revenue on top of their standard CPM, and can command a premium for verified audience segments vs. unverified.

***

## What You Need to Get Started

Revenue sharing requires:

1. **An active AIR Kit partnership** — contact our team to get a Partner ID and configure your issuer account
2. **Credential issuance volume** — revenue scales with active credentials in circulation
3. **Verifier network activation** — for verification fee revenue, partner verifiers need to be onboarded to your credential programs

***

<CardGroup>
  <Card title="Talk to our team" icon="handshake" href="https://air3.com/partner-with-us">
    Discuss specific revenue projections and partnership terms.
  </Card>

  <Card title="Get started as a developer" icon="code" href="/get-started/dashboard/account-setup">
    Begin the technical integration while commercial terms are agreed.
  </Card>
</CardGroup>


# Telco & Subscriptions
Source: https://docs.air3.com/solutions/telco

Issue subscriber credentials at activation. Roaming and MVNO partners verify KYC status with program-defined claims and user-controlled disclosure.

Carriers run identity verification for every new subscriber, but that verified status stays locked inside each operator's silo. A prepaid user who passes KYC at one carrier starts from zero at a roaming partner. AIR Kit lets you **issue a subscriber credential at activation** — so your KYC investment travels with the user across carriers, MVNOs, and partner services.

<Tabs>
  <Tab title="For business">
    ## The Problem

    Carriers spend on KYC at activation, then that verified status expires at the edge of their network. A prepaid subscriber who passed full identity verification at your MVNO is unknown to your roaming partner. Carrier partnerships that could unlock subscriber benefits require bilateral API agreements that take months to negotiate and are rarely worth the integration cost.

    ## What Changes With AIR Kit

    * **KYC travels with the subscriber** — Pass once at activation, accept everywhere in the ecosystem. Roaming partners verify the credential without calling your API or receiving subscriber data
    * **Loyalty tiers become cross-carrier benefits** — Issue a Silver or Gold subscriber credential. Partner MVNOs, device retailers, and service providers accept it to unlock benefits — no direct agreement required
    * **Age-restricted services gated properly** — Prove `isOver18` at point of service without transmitting or storing a subscriber's date of birth
    * **Churn intervention without data sharing** — Issue a "5-year subscriber" tenure credential. Retention partners can verify loyalty without accessing your customer database

    ## How It Works

    <Steps>
      <Step title="Subscriber activates and passes KYC">
        Your existing activation flow. Your existing identity verification. Nothing changes at this step.
      </Step>

      <Step title="AIR Kit issues a subscriber credential">
        At activation success, your backend fires one API call. A credential encoding KYC level, plan type, and age verification lands in the subscriber's AIR Account. Invisible to the subscriber.
      </Step>

      <Step title="Subscriber accesses a partner service">
        At a roaming partner, MVNO, or retail service, the subscriber authenticates with their AIR Account — the same login they use with you.
      </Step>

      <Step title="Partner verifies the requested claims">
        The partner calls one SDK method. A successful result includes a Verifiable Presentation with user-approved claims and any required proof. Configure the program to request KYC status without subscriber identifiers or documents when those are unnecessary.
      </Step>
    </Steps>

    ## What Crosses the Network — and What Doesn't

    This example requests limited claims with user approval. The Verification Program determines which claims are disclosed and whether a ZK proof is required.

    | What the Roaming Partner Receives | What Stays Private |
    | - | - |
    | COMPLIANT / NON\_COMPLIANT | MSISDN / phone number |
    | KYC level (basic / enhanced / full) | IMSI / SIM identifiers |
    | `isOver18: true` | Date of birth, full name |
    | Plan type (prepaid / postpaid) | Address, national ID |
    | Credential expiry | Billing history |

    ## What Compliance Will Ask

    **Does this satisfy roaming KYC obligations?**
    The credential attests to the level of KYC completed at your platform. Roaming partners accepting it are verifying that fact — the underlying compliance obligation remains with the issuing carrier.

    **Is subscriber PII transmitted to roaming partners?**
    A ZK proof can confirm KYC status without disclosing MSISDN or subscriber documents. Verification Programs may also request claims with user approval. Limit disclosures to what the roaming partner needs.

    **GDPR: where is subscriber data stored?**
    Raw source documents remain with the issuer. Encrypted credential payloads may be stored in DStorage, while users control decryption and disclosure. Subscriber claims and metadata can still be personal data; assess storage-provider locations and retention as part of your GDPR review.

    ## Integration at a Glance

    | | |
    | - | - |
    | **What your team builds** | One API call in your activation event handler |
    | **Engineering effort** | 1 backend engineer |
    | **Timeline to live** | 2–4 weeks |
    | **Changes to existing activation flow** | None |
    | **Roaming partner integration** | 3 lines of SDK code to verify |

    <CardGroup>
      <Card title="Compliance FAQ" icon="shield-check" href="/solutions/compliance-faq">
        Full GDPR and regulatory answers.
      </Card>

      <Card title="Partner Economics" icon="coins" href="/solutions/partner-economics">
        Revenue model, fee structure, and reward.
      </Card>
    </CardGroup>
  </Tab>

  <Tab title="For developers">
    ## What You Can Build

    * **Subscriber credentials** — Issue a verified subscriber attestation the moment a user activates; roaming and partner carriers accept it without re-running identity checks
    * **Plan tier credentials** — Issue a "Premium" or "Business" tier badge that unlocks partner benefits automatically, with no bilateral API required
    * **Device ownership proofs** — Issue a verified device credential (IMEI-bound) for device insurance, warranty, and repair partner integrations
    * **Churn intervention** — Trigger a "Loyalty Reward" credential when a subscriber hits a retention milestone; partner services can verify and honour the benefit
    * **Roaming partner verification** — Let partner carriers verify a subscriber's KYC status via ZK proof without requesting subscriber documents
    * **Age-gated service access** — Gate adult content, gambling, or age-restricted add-ons behind an age credential without storing birthdates

    ## Architecture

    ```mermaid theme={null}
    graph TD
        A["User activates SIM / subscription"] --> B[Your Activation Backend]
        B -->|KYC pass + activation event| C[On-demand issuance]
        C --> D[Subscriber Credential in User's AIR Account]

        D --> E{User accesses partner service}
        E -->|Roaming carrier| F["Verify subscriber KYC\nUser-approved claims and proofs"]
        E -->|MVNO partner| G["Tier unlock\nno API integration required"]
        E -->|Device insurer| H["Device ownership proof"]
        E -->|Your retention offer| I["Loyalty reward gated by tenure credential"]
    ```

    ## Recommended Schemas

    ### Subscriber Credential

    ```json theme={null}
    {
      "title": "Subscriber Credential",
      "description": "Verified mobile subscriber attestation — no raw PII included",
      "properties": {
        "carrierId": {
          "type": "string",
          "description": "Issuing carrier identifier"
        },
        "planType": {
          "type": "string",
          "enum": ["prepaid", "postpaid", "business", "iot"],
          "description": "Subscription plan category"
        },
        "kycLevel": {
          "type": "string",
          "enum": ["basic", "enhanced", "full"],
          "description": "Level of identity verification completed at activation"
        },
        "activatedAt": {
          "type": "string",
          "format": "date-time"
        },
        "isOver18": {
          "type": "boolean"
        },
        "countryCode": {
          "type": "string",
          "description": "ISO 3166-1 alpha-2 — subscriber's registration country"
        }
      },
      "required": ["carrierId", "planType", "kycLevel", "activatedAt", "isOver18"]
    }
    ```

    ### Subscriber Loyalty Tier

    ```json theme={null}
    {
      "title": "Subscriber Loyalty Tier",
      "description": "Carrier loyalty tier based on tenure and spend",
      "properties": {
        "carrierId": { "type": "string" },
        "tier": {
          "type": "string",
          "enum": ["Standard", "Silver", "Gold", "Platinum"],
          "description": "Current loyalty tier"
        },
        "tenureMonths": {
          "type": "number",
          "description": "Months as active subscriber"
        },
        "memberSince": {
          "type": "string",
          "format": "date"
        }
      },
      "required": ["carrierId", "tier", "tenureMonths"]
    }
    ```

    <Warning>
      Never include MSISDN (phone number), IMSI, full name, or address in `credentialSubject`. Store only **attestations and derived facts** — `isOver18`, `kycLevel`, `planType`. ZK proofs let partner services confirm subscriber attributes without receiving any underlying data.
    </Warning>

    ## Implementation

    ### Step 1 — Issue subscriber credential at activation

    Your activation system already fires an event when a subscriber passes KYC and activates. Add one server-side issuance call to that event handler.

    ```javascript theme={null}
    // activation-handler.js
    const { getPartnerJwt } = require('./lib/jwt');
    // issuer-controlled helpers backed by your signing keys
    const { buildVc, signVc, encryptToHolder } = require('./lib/credential');

    const BASE_URL = 'https://api.sandbox.mocachain.org/v1';

    // Resolve the recipient, then build, sign, encrypt, and store the credential in DStorage
    async function issueEncryptedCredential({ recipientEmail, schemaId, credentialSubject }) {
      const token = await getPartnerJwt();

      const init = await fetch(`${BASE_URL}/auth/initialize-user`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json', 'x-partner-auth': token },
        body: JSON.stringify({ email: recipientEmail }),
      }).then((r) => r.json());

      const vc = buildVc({ holderDid: init.did, schemaId, credentialSubject });
      const encrypted = encryptToHolder(signVc(vc), init.publicKey); // SD-JWT VC, encrypted to holder

      const res = await fetch(`${BASE_URL}/dstorage/vcs`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json', 'x-partner-auth': token },
        body: JSON.stringify({
          holderDid: init.did,
          schemaId,
          expiresAt: vc.expirationDate,
          data: encrypted.encryptedData,
          iv: encrypted.iv,
          authTag: encrypted.authTag,
          encryptedKey: encrypted.dataEncPublicKey,
          externalId: vc.id,
        }),
      });
      if (!res.ok) throw new Error(`Issuance failed: ${res.status}`);
      return res.json(); // { storagePath }
    }

    async function issueSubscriberCredential({ userEmail, activation }) {
      if (activation.kycStatus !== 'APPROVED') return;

      return issueEncryptedCredential({
        recipientEmail: userEmail,
        schemaId: process.env.SUBSCRIBER_CREDENTIAL_ID,
        credentialSubject: {
          carrierId: process.env.CARRIER_ID,
          planType: activation.planType,          // "prepaid" | "postpaid" | "business"
          kycLevel: activation.kycLevel,          // "basic" | "enhanced" | "full"
          activatedAt: new Date().toISOString(),
          isOver18: activation.age >= 18,
          countryCode: activation.countryCode,    // e.g. "AU", "SG"
        },
      });
    }

    // Hook into your existing activation pipeline
    activationPipeline.on('subscriber:activated', async ({ userEmail, activationData }) => {
      await issueSubscriberCredential({ userEmail, activation: activationData });
    });
    ```

    ### Step 2 — Issue loyalty tier on tenure milestone

    ```javascript theme={null}
    // churn-prevention.js — runs nightly or on billing cycle
    async function issueLoyaltyTierIfEligible({ userEmail, tenureMonths }) {
      const tier =
        tenureMonths >= 36 ? 'Platinum' :
        tenureMonths >= 24 ? 'Gold' :
        tenureMonths >= 12 ? 'Silver' : 'Standard';

      await issueEncryptedCredential({
        recipientEmail: userEmail,
        schemaId: process.env.LOYALTY_TIER_CREDENTIAL_ID,
        credentialSubject: {
          carrierId: process.env.CARRIER_ID,
          tier,
          tenureMonths,
          memberSince: getMemberSinceDate(userEmail),
        },
      });
    }

    // Run on each billing cycle to keep tiers current
    billingCycle.on('invoice:settled', async ({ userEmail, tenureMonths }) => {
      await issueLoyaltyTierIfEligible({ userEmail, tenureMonths });
    });
    ```

    ### Step 3 — Verify subscriber KYC at a roaming partner

    The roaming partner integrates AIR Kit as a verifier and selects a Verification Program. A successful SDK result includes a Verifiable Presentation with user-approved claims and any required proof. For this example, request KYC status without subscriber identifiers or documents.

    ```javascript theme={null}
    // roaming-partner.js (frontend — partner carrier's app)
    import { AirService } from '@mocanetwork/airkit';

    import { AirService, BUILD_ENV } from "@mocanetwork/airkit";

    const airService = new AirService({ partnerId: process.env.ROAMING_PARTNER_ID });
    await airService.init({ buildEnv: BUILD_ENV.PRODUCTION });

    async function verifyRoamingSubscriber() {
      const result = await airService.verifyCredential({
        programId: process.env.ROAMING_VERIFY_PROGRAM_ID,
        // Verifier program rule: kycLevel === "enhanced" OR "full"
        // The verifier sees only: COMPLIANT / NON_COMPLIANT
        // No MSISDN, no name, no raw subscriber data
      });

      if (result.status !== 'COMPLIANT') {
        throw new Error('SUBSCRIBER_KYC_REQUIRED');
      }
      return result;
    }
    ```

    ### Step 4 — Gate age-restricted services

    ```javascript theme={null}
    // age-restricted-service.js (frontend)
    async function requireAgeVerification() {
      const result = await airService.verifyCredential({
        programId: process.env.AGE_18_VERIFY_PROGRAM_ID,
        // Program checks: isOver18 === true — subscriber's birthdate never exposed
      });
      return result.status === 'COMPLIANT';
    }

    const allowed = await requireAgeVerification();
    if (!allowed) showAgeVerificationPrompt();
    ```

    ## Key Patterns

    | Pattern | Reissue behavior | When to Use |
    | - | :-: | - |
    | Initial activation | Skip if exists | Issue once at first activation; don't re-issue if user reinstalls |
    | Plan upgrade / re-KYC | Revoke + reissue | Always reissue with updated `kycLevel` or `planType` |
    | Loyalty tier update | Revoke + reissue | Monthly billing cycle refresh |
    | Device credential | Skip if exists | One credential per device — immutable proof of ownership |

    ## Privacy Guarantee

    For this KYC-status check, configure the program to use a ZK proof without requesting MSISDN, IMSI, or subscriber documents. Successful verification returns a Verifiable Presentation with any approved claims and required proof; other programs may request additional disclosure.

    | What the Verifier Sees | What Stays Private |
    | - | - |
    | `COMPLIANT / NON_COMPLIANT` | MSISDN / phone number |
    | `kycLevel` (`basic` / `enhanced` / `full`) | IMSI / SIM data |
    | `isOver18: true` | Full name, date of birth |
    | `planType` | Address, national ID |
    | Credential expiry | Billing history |

    ## Examples

    The repo uses fintech and loyalty app names (KYC provider, lending platform, airline, hotel). The same code adapts to telco (carrier, roaming partner) via schema and branding — see each example's `schema.json` and the README's "Adapting to Your Vertical" section.

    <CardGroup>
      <Card title="KYC Passport — Issuer" icon="github" href="https://github.com/MocaNetwork/air-examples/tree/main/kyc-passport/issuer">
        KYC provider app: issues credentials once; user carries the proof to other platforms.
      </Card>

      <Card title="KYC Passport — Verifier" icon="github" href="https://github.com/MocaNetwork/air-examples/tree/main/kyc-passport/verifier">
        Lending platform app: verifies the credential and accepts the proof without re-running KYC.
      </Card>

      <Card title="VIP Status Portability — Issuer" icon="github" href="https://github.com/MocaNetwork/air-examples/tree/main/vip-status-portability/issuer">
        Airline loyalty app: issues tier credential; user carries status to partner brands.
      </Card>

      <Card title="VIP Status Portability — Verifier" icon="github" href="https://github.com/MocaNetwork/air-examples/tree/main/vip-status-portability/verifier">
        Hotel chain app: verifies tier and grants equivalent perks (e.g. room upgrade, lounge).
      </Card>
    </CardGroup>

    ## Next Steps

    <Columns>
      <Card title="On-demand Issuance — Concepts" icon="book" href="/products/identity/issuing-credentials#direct-issuance">
        On-demand issuance without user presence.
      </Card>

      <Card title="On-demand Issuance — API" icon="code" href="/api-reference/issuance-api">
        Full endpoint reference with error codes.
      </Card>

      <Card title="AIR for Fintech & Payments" icon="credit-card" href="/solutions/fintech">
        KYC portability patterns used in financial services.
      </Card>

      <Card title="Architecture & Data Flow" icon="diagram-project" href="/technicals/architecture">
        ZK proof flow end-to-end.
      </Card>
    </Columns>
  </Tab>
</Tabs>


# Ticketing & Events
Source: https://docs.air3.com/solutions/ticketing

Turn every venue scan into a portable attendance credential fans can reuse for loyalty rewards, presale access, and partner discounts.

Traditional event tickets are one-time-use and forgotten after the show. AIR Kit lets you transform every venue scan into a **permanent, portable attendance credential** — proof the fan was there, reusable for loyalty rewards, presale access, partner discounts, and cross-brand partnerships.

<Tabs>
  <Tab title="For business">
    ## What Changes With AIR Kit

    * **Every scan becomes a credential** — Venue check-in issues a verifiable "attended this event" proof into the fan's AIR Account. No app to open, no action from the fan
    * **Fan loyalty without a new program** — Fans who reach an attendance threshold can be upgraded to a "Loyal Fan" credential automatically
    * **Gated access that partners can trust** — VIP lounges, meet-and-greets, and presales unlock for verified attendees. The verifier learns only that the fan qualifies
    * **Cross-brand fan benefits** — Merchandise, hotel, and streaming partners accept the attendance credential directly. No bilateral API between you and each partner
    * **Anti-scalping** — Secondary ticket access can be gated behind an attendance credential from a prior event

    ## What Your Fans Experience

    Nothing changes at the door. The fan scans in as they do today; the credential issues silently in the background.

    Later, at a partner or your own presale, the fan authenticates with their AIR Account and the benefit unlocks. No code to enter, no account linking.

    ## Next Steps

    <CardGroup>
      <Card title="Compliance FAQ" icon="shield-check" href="/solutions/compliance-faq">
        GDPR, PII, and data residency answers.
      </Card>

      <Card title="Partner Economics" icon="coins" href="/solutions/partner-economics">
        How the revenue model works for issuers and verifiers.
      </Card>

      <Card title="Loyalty & Rewards" icon="gift" href="/products/loyalty/business">
        Build tier-based loyalty on top of attendance credentials.
      </Card>

      <Card title="Talk to our team" icon="handshake" href="https://air3.com/partner-with-us">
        Start a partnership conversation.
      </Card>
    </CardGroup>
  </Tab>

  <Tab title="For developers">
    ## What You Can Build

    * **Attendance credentials** — Issue a verifiable "I attended X event" badge at check-in
    * **Fan loyalty tiers** — Auto-upgrade fans after 5 attended events to "Loyal Fan" credential
    * **Exclusive access gating** — Gate VIP lounges, artist meet-and-greets, and presales to verified attendees
    * **Cross-brand fan credentials** — Share attendance proof with partner brands (merchandise, hotels, streaming). [Try it live](https://air-bd-v2.netlify.app/try-it-live/hotel-package): the ticketing site issues, the hotel verifies
    * **Anti-scalping** — Gate secondary ticket access behind an attendance credential from a prior event

    ## Architecture

    ```mermaid theme={null}
    graph TD
        A[Fan arrives at venue] --> B["Venue scanner / check-in system"]
        B -->|"Scan detects fan's AIR Account email"| C[On-demand issuance]
        C --> D["Attendance Credential\nin Fan's AIR Account"]

        D --> E{Fan uses credential later}
        E --> F[Claim loyalty reward]
        E --> G[Access VIP presale]
        E --> H[Redeem partner discount]
        E --> I[Prove attendance history]
    ```

    ## Recommended Schema

    ```json theme={null}
    {
      "title": "Event Attendance",
      "description": "Verifiable proof of physical attendance at a live event",
      "properties": {
        "eventId": {
          "type": "string",
          "description": "Unique event identifier"
        },
        "eventName": {
          "type": "string",
          "description": "Display name — e.g. 'Coachella 2025 Day 1'"
        },
        "venue": {
          "type": "string",
          "description": "Venue name and city"
        },
        "attendedAt": {
          "type": "string",
          "format": "date-time",
          "description": "Timestamp of check-in scan"
        },
        "ticketTier": {
          "type": "string",
          "enum": ["General", "VIP", "Backstage", "Artist"],
          "description": "Ticket category"
        },
        "organizerId": {
          "type": "string",
          "description": "Issuing organizer / promoter identifier"
        }
      },
      "required": ["eventId", "eventName", "attendedAt", "organizerId"]
    }
    ```

    ## Implementation

    ### Step 1 — Issue attendance credential at check-in

    Your venue scanner calls your backend on each valid scan. The backend issues the credential on-demand — the fan does nothing, no wallet open, no UX friction at the door.

    ```javascript theme={null}
    // venue-checkin.js
    const { getPartnerJwt } = require('./lib/jwt');
    // issuer-controlled helpers backed by your signing keys
    const { buildVc, signVc, encryptToHolder } = require('./lib/credential');

    const BASE_URL = 'https://api.sandbox.mocachain.org/v1';

    async function issueAttendanceCredential({ fanEmail, eventDetails }) {
      const token = await getPartnerJwt();

      // Resolve the fan's AIR Account
      const init = await fetch(`${BASE_URL}/auth/initialize-user`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json', 'x-partner-auth': token },
        body: JSON.stringify({ email: fanEmail }),
      }).then((r) => r.json());

      // Build, sign (SD-JWT VC), and encrypt the credential to the holder
      const schemaId = process.env.ATTENDANCE_CREDENTIAL_ID;
      const vc = buildVc({
        holderDid: init.did,
        schemaId,
        credentialSubject: {
          eventId: eventDetails.id,
          eventName: eventDetails.name,
          venue: eventDetails.venue,
          attendedAt: new Date().toISOString(),
          ticketTier: eventDetails.ticketTier,   // "General" | "VIP" | "Backstage"
          organizerId: process.env.ORGANIZER_ID,
        },
      });
      const encrypted = encryptToHolder(signVc(vc), init.publicKey);

      // Store the encrypted envelope in DStorage
      const res = await fetch(`${BASE_URL}/dstorage/vcs`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json', 'x-partner-auth': token },
        body: JSON.stringify({
          holderDid: init.did,
          schemaId,
          expiresAt: vc.expirationDate,
          data: encrypted.encryptedData,
          iv: encrypted.iv,
          authTag: encrypted.authTag,
          encryptedKey: encrypted.dataEncPublicKey,
          externalId: vc.id,
        }),
      });
      if (!res.ok) throw new Error(`Attendance issuance failed: ${res.status}`);
      const { storagePath } = await res.json();
      return storagePath;
    }

    // Called by your ticketing system on each valid scan
    app.post('/api/checkin', async (req, res) => {
      const { fanEmail, eventId } = req.body;
      const event = await getEventDetails(eventId);
      const storagePath = await issueAttendanceCredential({ fanEmail, eventDetails: event });
      res.json({ success: true, storagePath });
    });
    ```

    ### Step 2 — Gate VIP presale to verified attendees

    ```javascript theme={null}
    // presale-gate.js  (frontend)
    import { AirService } from '@mocanetwork/airkit';

    import { AirService, BUILD_ENV } from "@mocanetwork/airkit";

    const airService = new AirService({ partnerId: process.env.PARTNER_ID });
    await airService.init({ buildEnv: BUILD_ENV.SANDBOX });

    async function canAccessPresale() {
      const result = await airService.verifyCredential({
        programId: process.env.PRESALE_VERIFY_PROGRAM_ID,
        // Verifier program rule: organizerId === process.env.ORGANIZER_ID
        // (attended at least 1 prior event by this organizer)
      });
      return result.status === 'COMPLIANT';
    }

    const isVerifiedFan = await canAccessPresale();
    if (isVerifiedFan) {
      showPresaleRegistration();
    } else {
      showMessage('Presale access requires verified attendance at a prior event.');
    }
    ```

    ### Step 3 — Auto-upgrade fans to loyalty tiers after N events

    ```javascript theme={null}
    // loyalty-tier-check.js — called after each attendance credential issuance
    async function checkAndIssueLoyaltyTier(fanEmail) {
      const attendedCount = await getAttendanceCount(fanEmail); // your DB

      if (attendedCount === 5)  await issueLoyaltyTier({ fanEmail, tier: 'Loyal Fan' });
      if (attendedCount === 20) await issueLoyaltyTier({ fanEmail, tier: 'Super Fan' });
    }

    // issueLoyaltyTier uses the same on-demand issuance pattern — see AIR for Loyalty guide
    ```

    ## Zero-Friction Fan UX

    The key advantage for events: **fans never interact with the credential system at the door**. They scan their ticket as normal, the credential lands in their AIR Account in the background, and they use it the next time they want a reward or presale.

    <Steps>
      <Step title="Fan scans ticket at the door">
        No app to open, no wallet prompt. Exactly the same experience as today.
      </Step>

      <Step title="Your backend issues the attendance credential">
        On-demand issuance fires silently. The credential lands in the fan's AIR Account, encrypted to them.
      </Step>

      <Step title="Fan opens the app the next day">
        Sees a notification: "You earned a Verified Attendee credential for Coachella 2025."
      </Step>

      <Step title="Fan uses the credential">
        One tap to register for the presale, claim a merchandise discount, or prove their fan tier to a partner brand.
      </Step>
    </Steps>

    ## Examples

    <CardGroup>
      <Card title="Fan Attendance — live demo" icon="play" href="https://air-bd-v2.netlify.app/try-it-live/tour-record">
        Check in at the concert hall, then buy a record sold only to fans who went to the show.
      </Card>

      <Card title="Cross-brand package — live demo" icon="play" href="https://air-bd-v2.netlify.app/try-it-live/hotel-package">
        The ticketing site issues the credential and a hotel verifies it for a festival package.
      </Card>

      <Card title="Fan Attendance — Issuer" icon="github" href="https://github.com/MocaNetwork/air-examples/tree/main/fan-attendance/issuer">
        Venue check-in app: issues attendance credential when the fan scans in at the event.
      </Card>

      <Card title="Fan Attendance — Verifier" icon="github" href="https://github.com/MocaNetwork/air-examples/tree/main/fan-attendance/verifier">
        Merch store app: verifies attendance and unlocks rewards (e.g. discount, exclusive offer).
      </Card>

      <Card title="VIP Status Portability — Issuer" icon="github" href="https://github.com/MocaNetwork/air-examples/tree/main/vip-status-portability/issuer">
        Airline loyalty app: issues tier credential; user carries status to partner brands.
      </Card>

      <Card title="VIP Status Portability — Verifier" icon="github" href="https://github.com/MocaNetwork/air-examples/tree/main/vip-status-portability/verifier">
        Hotel chain app: verifies tier and grants equivalent perks (e.g. room upgrade, lounge).
      </Card>
    </CardGroup>

    ## Next Steps

    <Columns>
      <Card title="AIR for Loyalty & Rewards" icon="gift" href="/products/loyalty/developers">
        Build tier-based loyalty on top of attendance credentials.
      </Card>

      <Card title="On-demand Issuance — API" icon="code" href="/api-reference/issuance-api">
        Full endpoint reference and error handling.
      </Card>

      <Card title="Architecture & Data Flow" icon="diagram-project" href="/technicals/architecture">
        End-to-end system overview.
      </Card>
    </Columns>
  </Tab>
</Tabs>


# Credential Security
Source: https://docs.air3.com/technicals/architecture/credential-security

How Moca Network credentials are signed by issuers, encrypted to the holder, stored as ciphertext, and verified with program-defined proofs.

Verifiable credentials on Moca Network are designed to be tamper-evident, privacy-preserving, and portable to any verifier that uses AIR verification.

## Issuance integrity

When a credential is issued:

1. The issuer signs the credential data with issuer-controlled keys, bound to their DID. SD-JWT issuers (`SD_JWT_VC`) publish the verifying keys in a `did:web` document on their own domain. When the holder provides a key, the issuer writes it to the credential's `cnf` claim, binding the credential to the holder.
2. The signed credential payload is encrypted to the holder's public key.
3. The encrypted envelope is stored in DStorage. AIR stores and routes opaque ciphertext and metadata as a blind facilitator — it never sees the plaintext.

The issuer's signature acts as a tamper seal. If the credential data is modified after issuance, any verification will fail because the signature no longer matches.

## Verification

Verification is program-driven:

* The verifier asks a question: "Does this user hold a valid credential matching schema X?"
* The holder decrypts the matching credential and approves the requested disclosure.
* For SD-JWT credentials, the holder signs a key-binding JWT over the verifier's nonce and `programId`, so the presentation cannot be replayed or altered.
* The verifier receives a compliance result and a Verifiable Presentation containing the disclosed claims — nothing else.

The presentation wrapper is not signed. Verifiers should check the SD-JWT inside it on their own backend: see [Verify SD-JWT on your backend](/products/identity/verify-sd-jwt).

## Selective disclosure

Holders can disclose individual attributes without revealing the full credential. How this works depends on the [credential format](/products/identity/credential-formats):

* **SD-JWT VC.** Each disclosable claim is replaced in the signed credential by a salted digest. The holder sends only the disclosures for the requested claims, and the verifier checks each against its digest. The verifier sees the exact value of each disclosed claim.
* **Iden3.** A zero-knowledge proof can establish a condition, such as `kycLevel >= 2`, without revealing the value. An attribute Merkle root binds the proven fields to the signed credential.

Disclosed claims may still be personal data. Selective disclosure is defined at the schema and verification program level. See [Schema Design](/products/identity/schema-overview) for configuration.

## Credential revocation

Issuers revoke credentials from their own issuer service. Verification programs that enable issuer revocation checks reject a revoked credential once the revoked status is published. SD-JWT issuers can also publish an IETF Token Status List, which verifiers cache; revocation then reaches them after the issuer's publish interval. See [Revoke credentials](/products/identity/revocation).

## Credential storage

| Storage layer | What is stored | Encrypted? |
| - | - | - |
| Issuer systems | Raw source documents and issuer signing keys | Protected under issuer controls |
| DStorage (decentralized) | Signed credential payload (VC envelope) | Yes — encrypted to the holder |
| Moca Chain (on-chain) | Cryptographic hashes, storage metadata, and status records; for Iden3 programs, verification proofs when required | Do not treat public metadata as encrypted payloads |
| User device | Private keys, session tokens | Yes, managed by MPC shards |

## Further reading

* [Privacy & Compliance](/technicals/architecture/privacy-and-compliance) for encryption, ZK proofs, and consent
* [zkTLS](/technicals/architecture/zktls) for the zero-knowledge transport layer
* [Schema Design](/products/identity/schema-overview) for defining verifiable attributes


# Data Privacy
Source: https://docs.air3.com/technicals/architecture/data-privacy

Privacy-by-design in Moca Network — where user data lives, what is encrypted, who has access, and how data minimization is enforced across the stack.

Moca Network follows a privacy-by-design approach. User data is minimized at every layer, and access is gated by cryptographic controls and explicit user consent.

## Data minimization

The default AIR Kit integration stores the minimum data necessary:

| Data type | Stored by Moca? | Notes |
| - | - | - |
| User email | Yes (hashed identifier) | Used as the AIR Account identifier for cross-partner portability |
| Raw source documents | Remain with the issuer | Not shared with AIR or verifiers |
| Credential claims | Encrypted envelope in DStorage | Payloads are encrypted to the holder; AIR stores opaque ciphertext and metadata, never plaintext |
| Private keys | No | Keys are split via MPC; no single party holds a full key |
| Verification records | Off-chain by default | Recorded on-chain only when a program requires on-chain verification |

## Who can access what

### Standard flow (all credentials)

Every credential is signed by the issuer and encrypted to the holder before storage. Credential claims and metadata can still be personal data:

* **Issuers** know the data they put into the credential (they are the source of truth) and hold their own signing keys.
* **Verifiers** receive a Verifiable Presentation containing the claims requested by the program and approved by the user, plus any required proof. They never see undisclosed claim data.
* **AIR** stores encrypted credential objects and metadata as a blind facilitator. It cannot reconstruct credential content.
* **Users** hold the encrypted credential in their AIR Account and control when and to whom it is presented.

## Data residency

* **Encrypted credential payloads** are stored in decentralized storage (DStorage) on Moca Chain as opaque ciphertext.
* **On-chain data** includes DStorage object metadata and state records, replicated across validators. Verification proofs are recorded on-chain only when the Verification Program requires it.
* **Session tokens and MPC key shards** are stored on the user's device and in secure execution environments. They are not centrally stored.

## User control

Users can:

* **Revoke consent** — If a user previously authorized a verifier, they can deny future requests.
* **Export keys** — Users can export their wallet private key for portability.
* **Request account deletion** — Handle account records, encrypted payloads, metadata, and previously disclosed copies through the relevant retention and deletion processes. Account deletion or credential revocation does not erase every copy. On-chain records remain and may still be linkable to a user.

## Compliance considerations

Moca Network provides technical primitives (encryption, consent management, audit trails) that support compliance frameworks such as GDPR, CCPA, and industry-specific regulations. The [Security Checklist](/technicals/architecture/security-checklist) covers integration best practices for maintaining compliance.

<Warning>
  Moca Network provides infrastructure and tooling. Compliance responsibility ultimately lies with the issuer and verifier organizations. Consult legal counsel for your specific regulatory requirements.
</Warning>


# Architecture & Data Flow
Source: https://docs.air3.com/technicals/architecture/index

End-to-end technical architecture of AIR Kit — SDK services, Moca Chain, credential lifecycle, and how data moves through the system.

AIR Kit connects your application to AIR services and Moca Chain. It exposes **Account Services** for authentication and wallet operations and **Credential Services** for orchestrating issuance and verification. Your issuer backend owns credential authorization, source data, signing, encryption, and storage.

## System overview

```mermaid theme={null}
graph TD
    APP[Your application]
    SDK[AIR Kit SDK]
    API[AIR APIs]
    ISS[Issuer backend and data source]
    STORE[Encrypted dStorage]
    EVM[Moca Chain EVM layer]

    APP -->|Web / Flutter SDK| SDK
    SDK -->|Login, discovery, issuance, verification| API
    API -->|Route issuer requests| ISS
    ISS -->|Store signed and encrypted VCs| STORE
    SDK -->|Fetch encrypted VCs| STORE
    SDK -->|On-chain verification when configured| EVM
```

The SDK manages user interaction and calls AIR APIs. AIR routes issuance requests to the registered issuer backend. The issuer backend owns authorization, source data, credential creation and signing, encryption, and storage. Credential storage and on-chain proof verification are separate operations. See [Account Services](/get-started/authentication/login) for login and wallet details.

## Issuance modes

| Mode | User presence | How it works |
| - | - | - |
| **On-demand issuance** | User present | The user reviews available credentials and confirms issuance through the SDK. |
| **Direct issuance** | Can run without the user present | The issuer creates and stores the credential; the user claims it when they log in to AIR. |
| **Pre-issue** | Can run before the user logs in | Uses Direct Issuance to prepare credentials for the user to claim later. |

## On-demand issuance flow (user-initiated)

Your app calls `issueCredential()` with the issuance program/schema context and an optional identifier. This is the client-side entry point: the SDK ensures AIR login, discovers available credentials, obtains the user's confirmation, and requests issuance through AIR.

The issuance program identifies the configured flow; the schema defines the credential's data structure. They are distinct identifiers. The sequence below describes the orchestration, rather than an SDK parameter signature.

```mermaid theme={null}
sequenceDiagram
    participant U as User
    participant App as Your App (Issuer)
    participant SDK as AIR Kit SDK
    participant AIR as AIR APIs
    participant Iss as Issuer Backend
    participant Data as Issuer Data Source
    participant DS as Encrypted DStorage

    U->>App: Triggers credential claim
    App->>SDK: issueCredential() with issuance context
    SDK->>SDK: Load issuance program and schema
    opt User is not logged in
        SDK->>U: Show AIR login
        U->>SDK: Authenticate
        SDK->>AIR: Establish AIR session
        AIR-->>SDK: Holder DID and public key
    end
    SDK->>AIR: GET /v2/issuer/{partnerId}/available-vc
    AIR->>Iss: POST /available-vc (holder DID, public key, schema, identifier)
    Iss->>Data: Check eligibility and load available claims
    Data-->>Iss: Eligible credential data
    Iss-->>AIR: Encrypted credential previews
    AIR-->>SDK: Encrypted previews
    SDK->>SDK: Decrypt previews
    SDK->>U: Show available credentials for review
    U->>SDK: Select credential and confirm issuance
    SDK->>AIR: POST /v2/issuer/{partnerId}/issue-vc
    AIR->>Iss: POST /issue-vc (holder DID, public key, signing key, schema, identifier)
    Iss->>Iss: Authorize issuance
    Iss->>Data: Retrieve source data
    Data-->>Iss: Authoritative claims
    Iss->>Iss: Build VC, sign with issuer key, encrypt to holder
    Iss->>DS: Store encrypted VC envelope
    DS-->>Iss: storagePath
    Iss-->>AIR: Issuance result / reference
    AIR-->>SDK: Issuance result / reference
    SDK-->>App: Return issuance result / reference
    App-->>U: Credential delivered to AIR Account
```

The `/v2/issuer/{partnerId}/…` routes are AIR proxy endpoints, addressed by your Partner ID. AIR forwards them to the `POST /available-vc` and `POST /issue-vc` routes on your own issuer service, which use a different host and the `x-api-key` header.

`available-vc` discovers credentials and returns encrypted previews. It does not issue a credential. The SDK calls `issue-vc` only after the user confirms. The issuer backend remains responsible for authorization, data retrieval, VC generation and signing, encryption, and storage; `issueCredential()` orchestrates these steps without creating or signing the VC itself.

## Credential verification flow

The SDK loads the verification program and ensures the user is logged in to AIR. It discovers matching credentials through AIR, fetches and decrypts the selected credential, and displays the requested data for consent. After the user agrees, the SDK records consent and generates the verifiable presentation and any required proof.

<Steps>
  <Step title="Start verification">
    The partner app calls `verifyCredential()` with a verification program. The SDK loads the program and ensures the holder is logged in to AIR.
  </Step>

  <Step title="Find a matching credential">
    The SDK requests matching credential metadata and dStorage paths. If no credential exists, the SDK can start the accepted issuer's on-demand issuance flow, including user confirmation.
  </Step>

  <Step title="Decrypt and review">
    The SDK fetches the encrypted credential, decrypts it on the holder's device, and shows the requested claims.
  </Step>

  <Step title="Get consent and create the presentation">
    The user consents to verification and sharing. The SDK records consent, generates the verifiable presentation, and creates any proof required by the program.
  </Step>

  <Step title="Verify and return the result">
    The SDK runs the configured verification mode and returns the result and applicable presentation or proof material to the partner app.
  </Step>
</Steps>

If the user declines consent, the flow stops before generating or sharing the presentation. If no matching credential can be issued, verification cannot proceed with that credential.

### Off-chain and on-chain verification

The verification program selects the mode. Both paths use the credential discovery, decryption, and consent steps above.

| Mode | Where verification runs | What the app receives |
| - | - | - |
| **Off-chain** | The proof or presentation is checked outside a blockchain transaction against the program's requirements. | Verification status and the presentation/proof material applicable to the program. |
| **On-chain** | The proof is submitted for verification on-chain. This mode is available only for [Iden3](/products/identity/iden3-credentials) `BJJ_SIG_2021` credentials. | The verification outcome and applicable on-chain transaction information. |

Using dStorage or anchoring issuer state does not, by itself, mean that verification runs on-chain. The verification mode describes where the proof is checked. The app uses the returned outcome to decide whether to grant access.

## Direct issuance and pre-issue flow

Use Direct Issuance when a backend event or batch job should issue a credential without requiring the user to be present. The issuer backend resolves the recipient's holder DID and public key, authorizes issuance, retrieves the source data, then builds, signs, encrypts, and stores the VC. The user claims the credential when they log in to AIR.

**Pre-issue uses Direct Issuance** to prepare credentials ahead of that login and claim step.

<Steps>
  <Step title="Trigger issuance">
    A backend event or batch job starts the flow, such as a completed KYC check, purchase, or check-in.
  </Step>

  <Step title="Resolve the recipient">
    The issuer backend uses the AIR API to resolve or create the recipient's holder DID and public key. No active user session is required.
  </Step>

  <Step title="Create and store the credential">
    The issuer authorizes issuance, retrieves source data, creates and signs the VC, encrypts it to the holder, and stores the encrypted envelope in dStorage.
  </Step>

  <Step title="Claim later">
    The user logs in to AIR later and claims the credential. Pre-issue follows this same Direct Issuance path, ahead of the user's login.
  </Step>
</Steps>

## Integrating with existing systems

Your issuer backend can connect to loyalty platforms, KYC providers, ticketing systems, and payment processors. Those systems can trigger Direct Issuance, while the SDK supports user-present issuance, later claims, and verification. See the [vertical integration guides](/airkit/guides/air-for-loyalty) for examples.

## Service independence and login requirements

Choose the service capabilities your app needs. An AIR login is required for the user-present credential flows below; it does not imply that your app must also integrate wallet operations, gas sponsorship, or other Account Services features.

| Credential flow | Service | AIR login requirement |
| - | - | - |
| On-demand issuance | Credential Services | User logs in before reviewing and confirming issuance. |
| Direct issuance | Credential Services | No active user session required to issue; user logs in to claim later. |
| Pre-issue | Credential Services, using Direct Issuance | No active user session required to pre-issue; user logs in to claim later. |
| SDK verification | Credential Services | User logs in before reviewing the requested data and consenting. |

## Next steps

<Columns>
  <Card title="Quick Setup" icon="bolt" href="/get-started/dashboard/account-setup">
    Install and initialize the SDK in minutes.
  </Card>

  <Card title="Solutions by vertical" icon="puzzle-piece" href="/solutions">
    Business overview and developer guide for Loyalty, Identity, Fintech, Gaming, Ticketing, Telco, and Advertising.
  </Card>

  <Card title="Quickstart: Issue Credentials" icon="badge-check" href="/get-started/quickstarts/issue-credentials">
    Step-by-step credential issuance walkthrough.
  </Card>

  <Card title="Direct Issuance and Pre-issue" icon="server" href="/airkit/guides/overview#direct-issuance-and-pre-issue-flow">
    Issue without an active user session; users claim credentials when they log in.
  </Card>
</Columns>


# Privacy & Compliance
Source: https://docs.air3.com/technicals/architecture/privacy-and-compliance

How AIR Kit protects sensitive user data through encryption, zero-knowledge proofs, and explicit user consent.

AIR Kit stores encrypted credential payloads and metadata, while raw source documents remain with the issuer. Users control decryption and disclosure. Verification Programs define requested claims, optional ZK proofs, and off-chain or on-chain verification. Successful verification returns a Verifiable Presentation with approved claims and any required proof.

When **zkMe** issues credentials (for example through **Veriff powered by zkMe**), the cryptographic protections behind that Issuer — zkPassport, zkVault, and related zkMe Protocol components — are summarized for partners in [KYC (Veriff powered by zkMe) — zkMe security architecture](/solutions/kyc/zkme-security-architecture).

***

## How data is protected

<CardGroup>
  <Card title="Encryption at rest" icon="lock">
    Issuers sign credentials with their own keys and encrypt them to the holder before upload. DStorage holds ciphertext; AIR and storage providers cannot read the payload.
  </Card>

  <Card title="User consent" icon="user-shield">
    The user approves each disclosure during verification. Without that approval, the verifier receives nothing.
  </Card>

  <Card title="Data minimization" icon="filter">
    A Verification Program requests only the claims it needs. A ZK proof can establish a condition, such as an age threshold, without disclosing the underlying value.
  </Card>

  <Card title="Separation of roles" icon="arrows-split-up-and-left">
    Issuers hold source records, holders hold their credentials, and verifiers receive only the approved result. No single party sees everything.
  </Card>
</CardGroup>

***

## What each party receives

| Party | Receives | Does not receive |
| - | - | - |
| **Issuer** | Its own source records and the claims it issues | The holder's decryption key |
| **AIR / DStorage** | Encrypted credential payloads and metadata | Plaintext credential content |
| **Verifier** | The claims its program requests and the user approves, plus any required proof | Undisclosed claims or the issuer's source documents |
| **Holder** | Their credentials and control over disclosure | — |

Encryption and ZK proofs reduce exposure but do not remove personal-data obligations. See the [Compliance FAQ](/solutions/compliance-faq).

***

## Next steps

<CardGroup>
  <Card title="Data privacy" icon="lock" href="/technicals/architecture/data-privacy">
    Where data lives and who can access it
  </Card>

  <Card title="Verifying credentials" icon="magnifying-glass" href="/products/identity/verify">
    Result shape, selective disclosure, and proofs
  </Card>

  <Card title="Selective disclosure" icon="eye-slash" href="/products/identity/selective-disclosure">
    Attribute-level presentation controls
  </Card>
</CardGroup>


# Security Checklist
Source: https://docs.air3.com/technicals/architecture/security-checklist

Security checklist for AIR Kit integrations — Partner JWT key management, secrets handling, callback security, and credential issuance best practices.

Use this checklist when integrating AIR Kit to ensure your implementation follows security best practices.

## Partner JWT security

* [ ] Private keys are stored in a secrets manager or HSM — never in source code or environment files checked into version control.
* [ ] JWTs are short-lived (`exp` set to 5 minutes or less).
* [ ] `kid` in the JWT header matches a key in your publicly accessible JWKS endpoint.
* [ ] JWKS endpoint is served over HTTPS with a valid TLS certificate.
* [ ] JWTs are generated server-side only. The private key never reaches the client.

## Authentication

* [ ] Use the authentication required by each surface: [Partner JWT](/get-started/authentication/sdk-auth) for SDK and direct AIR API operations, `x-api-key` for issuer-hosted endpoints, and `x-admin-api-key` for self-hosted admin endpoints.
* [ ] If using Custom Auth (BYO), verify the user's identity in your own system before issuing the Partner JWT.
* [ ] Enable [MFA](/get-started/authentication/mfa) for high-value operations (credential issuance, large transactions).
* [ ] Set `skipRehydration: true` if your security model requires login on every session.

## Credential issuance

* [ ] Validate credential data on your backend before signing and issuing. Do not trust client-supplied values.
* [ ] Dedupe issuance by recipient email + program ID; revoke the existing credential before reissuing when data changes (e.g. tier upgrades).
* [ ] For on-demand issuance, confirm DStorage returned a `storagePath` or that `POST /issue-vc` succeeded and the issuer persisted its DStorage result.
* [ ] Sign credentials with issuer-controlled keys and encrypt them to the holder before DStorage upload. Keep raw source documents in issuer-controlled systems.
* [ ] Configure requested claims and proof requirements in the Verification Program; require user approval for disclosure.

## API security

* [ ] Use HTTPS for all API calls. Do not downgrade to HTTP, even in development.
* [ ] Implement retry logic with exponential backoff for transient failures (HTTP 500, network timeouts).
* [ ] Log API errors and monitor for unusual patterns (spikes in 401/403 responses may indicate key compromise).
* [ ] Rotate signing keys periodically. Update your JWKS endpoint before removing the old key.

## Frontend security

* [ ] Do not expose your Partner ID's private key on the client. The `partnerId` itself is safe to include in client code.
* [ ] Validate callback URLs and redirect URIs to prevent open-redirect attacks.
* [ ] If embedding AIR Kit in an iframe, configure `Content-Security-Policy` headers to allow `frame-src` from AIR Kit domains.

## Smart accounts and transactions

* [ ] Use the [Paymaster](/products/money/paymaster) for gas sponsorship. Monitor sponsorship spend to detect abuse.
* [ ] Validate transaction parameters on your backend before relaying to the user's smart account.
* [ ] If using [session keys](/products/money/session-keys), scope permissions to the minimum necessary operations and set short expiry times.

## Monitoring

* [ ] Set up alerts for failed authentication attempts.
* [ ] Monitor credential issuance volumes for anomalies.
* [ ] Log user consent events for audit compliance.


# Security Overview
Source: https://docs.air3.com/technicals/architecture/security-overview

How Moca Network protects user identity, credentials, and data — split-trust architecture, on-chain anchoring, encryption, and zero-knowledge proofs.

Moca Network is an identity infrastructure platform. Security is foundational to every design decision — from how credentials are issued to how keys are managed and how data flows between parties.

## Trust model

AIR Kit separates issuer source data and signing authority from encrypted credential storage and holder-controlled disclosure:

| Party | What they hold | What they cannot do |
| - | - | - |
| **User (Holder)** | Private keys, consent authority, credential wallet | Cannot forge credentials or bypass schema rules |
| **Issuer** | Source data, issuer signing keys | Cannot decrypt holder-encrypted storage without the relevant key; retains access to its own source records |
| **Verifier** | Verification programs, approved claims, optional ZK proofs | Cannot access undisclosed claims without user consent |
| **Moca Chain** | Storage metadata, state records, optional on-chain verification proofs | Cannot reconstruct private keys or decrypt stored data |
| **dStorage** | Encrypted credential payloads | Cannot decrypt without the user-consented key |

## Security layers

### Zero-knowledge proofs

The Verification Program determines the requested claims, whether ZK proofs are required, and whether verification is off-chain or on-chain. Successful verification returns a Verifiable Presentation with user-approved claims and any required proof. A ZK proof can confirm a condition without disclosing the underlying value.

### MPC-based key management

User accounts are backed by multi-party computation (MPC). Private keys are never held in one place — shards are distributed so that no single party (including Moca) can reconstruct the key. Keys are only assembled in a secure execution environment at the moment of signing.

### On-chain anchoring

The issuer's signature makes the credential tamper-evident. Programs that require on-chain verification can submit proofs to Moca Chain; other programs verify off-chain. DStorage object metadata is distinct from these optional verification records.

### Encrypted storage

Raw source documents remain with the issuer. Encrypted credential payloads may be stored in DStorage, while users control decryption and disclosure. Credential payloads are encrypted by default. See [Privacy & Compliance](/technicals/architecture/privacy-and-compliance).

### Account abstraction

User wallets use smart accounts (ERC-4337 account abstraction) with paymaster-sponsored gas. Users interact with the chain without managing private keys or gas tokens directly.

## Further reading

<CardGroup>
  <Card title="Credential security" icon="shield-check" href="/technicals/architecture/credential-security">
    How credentials are signed, encrypted, and verified with user-controlled disclosure.
  </Card>

  <Card title="Data privacy" icon="lock" href="/technicals/architecture/data-privacy">
    Where data lives, what is encrypted, and who can access it.
  </Card>

  <Card title="Security checklist" icon="list-check" href="/technicals/architecture/security-checklist">
    Integration best practices for partners.
  </Card>

  <Card title="Privacy & Compliance" icon="key" href="/technicals/architecture/privacy-and-compliance">
    Encryption, ZK proofs, and user consent.
  </Card>
</CardGroup>


# zkTLS: Secure Web2 → On-Chain Proofs
Source: https://docs.air3.com/technicals/architecture/zktls

How zkTLS bridges Web2 sources like KYC, social, and email to on-chain proofs — enabling private identity onboarding without exposing raw HTTPS payloads.

One of the critical challenges in decentralized identity is bridging the gap between **Web2 data sources** (e.g., social accounts, emails, KYC providers) and **Web3 smart contracts** without compromising privacy.

**zkTLS (Zero-Knowledge Transport Layer Security)** solves this problem by enabling verifiable proofs of HTTPS interactions, allowing on-chain applications to trust data from Web2 endpoints without exposing the underlying payload.

## How zkTLS Works

1. **TLS Handshake Capture**
   * When a client communicates with a Web2 service (e.g., an email provider), the TLS handshake and session are cryptographically captured.

2. **Proof Generation**
   * A **zero-knowledge proof** is constructed showing that the interaction took place with the genuine server, over HTTPS, with specific outputs (e.g., "this email is verified").
   * Importantly, the raw data exchanged remains private.

3. **On-Chain Verification**
   * The ZK proof is submitted to a smart contract, which verifies the claim without needing access to the underlying data.

## Key Advantages

* **Privacy-Preserving**\
  Users can prove statements about their Web2 accounts (like GitHub activity, employment, or KYC status) without exposing personal details.

* **Trustless Bridging**\
  Eliminates the need for centralized verification intermediaries between Web2 and Web3.

* **Interoperability**\
  Works across diverse Web2 data sources and can integrate with multiple blockchains.

* **Data minimization**\
  Sensitive data never leaves the user’s control, which reduces the data dApps and partners hold. Compliance still depends on each implementation and jurisdiction.

## Example Use Cases

* **Proof of Humanity**: Verifying a user’s email or social profile to prevent bots.
* **KYC/AML**: On-chain DeFi protocols can accept compliance proofs without storing user passports or IDs.
* **Reputation Systems**: Bringing provable GitHub or LinkedIn credentials into decentralized professional networks.


# Moca Chain Architecture Overview
Source: https://docs.air3.com/technicals/mocachain/architecture

Moca Chain architecture overview — EVM-compatible Layer 1 built on EVMOS and CometBFT consensus, paired with the MCSP decentralized storage network.

# How Moca Chain Works

Moca Chain is built on the **CometBFT (Cosmos)** framework with Ethereum Virtual Machine **(EVM) compatibility** based on EVMOS and integrates with its own decentralized data storage network based on BNB Greenfield.

## Key Components

Moca Chain's architecture primarily comprises two interconnected components:

1. **EVM-Compatible Blockchain**
2. **Moca Chain Storage Providers (MCSP)**

These elements work synergistically alongside the account & credential services powered by AIR Kit to provide secure, scalable data management and identity verification.

## Integration and Operations

Moca Chain's components integrate to form a cohesive system:

* **Consensus and Security:** Validators use PoS to secure the network, challenge data integrity, and govern parameters.
* **Token Economics:** [\$MOCA](/technicals/mocachain/moca-coin) enables governance, staking, fees (verification, gas, storage), and incentives for honest behavior.
* **Cross-Chain Programmability:** EVM support allows smart contracts to interact across chains.
* **Data Flow:** Users store data via MCSPs, which sync metadata with the chain. Challenges ensure integrity, and ZKPs maintain privacy.


# Moca Chain Block Explorer
Source: https://docs.air3.com/technicals/mocachain/block-explorer

Moca Chain Block Explorer overview — inspect blocks, transactions, validators, MCSP storage, and identity data on the Moca Chain Testnet network.

# Moca Chain Explorer: A Functional Overview

<Tip>
  📢 **Check it out here:** [Moca Chain Explorer (Mainnet)](https://scan.mocachain.org/) · [Testnet Explorer](https://testnet-scan.mocachain.org/)
</Tip>

The **Moca Chain Explorer** is the primary interface for viewing and interacting with the Moca Network.

It provides users and developers with direct access to **on-chain data** and the **decentralized storage layer**, ensuring transparency and accessibility for all participants.

## Core Functionalities

The explorer is organized into several key sections, each serving a distinct purpose for **data inspection** and **analysis**.

### 1. Network Dashboard

The **main dashboard** provides a high-level summary of the Moca Network’s current state.

**Key metrics displayed include:**

* **Live Feeds**: Latest blocks and transactions as they are confirmed
* **Network Statistics**: Real-time data on average block time, total transactions, and number of unique/active addresses
* **Storage Analytics**: Overview of the decentralized storage system, including total data stored and daily storage volume

### 2. Universal Search

A **central search bar** allows efficient querying of chain data.

Users can search by:

* Block Height
* Transaction Hash
* Wallet Address
* Storage Bucket Name
* Storage Object Name

### 3. Blockchain Data Exploration

Detailed views of core blockchain components:

* **Blocks**: Complete list of all blocks, including block proposer, transaction count, and metadata
* **Transactions**: Comprehensive log of all transactions with type, status, and associated logs
* **Accounts**: Directory of all on-chain accounts, showing balances and historical transaction counts

### 4. Decentralized Storage Inspection

Transparent view into Moca Chain’s **unique decentralized storage layer**, organized into three categories:

| Category | Description |
| - | - |
| **Objects** | Individual data files stored on the network. Explorer lists size, type, visibility (Public/Private), and status (Created/Sealed). |
| **Buckets** | Containers for organizing objects. Shows status, creator, and number of active objects. |
| **Groups** | Used for managing permissions for shared/private data. Displays group members, owners, and resources controlled. |

### 5. Developer Tools

To support the developer community, the explorer includes a **Faucet**.

This tool allows developers to:

* Request **testnet tokens**
* Build and test applications in a sandbox environment
* Experiment without needing real assets


# How to Connect a Wallet With Moca Chain
Source: https://docs.air3.com/technicals/mocachain/connect-to-mocachain

Connect a Web3 wallet to Moca Chain Mainnet or Testnet — configure MetaMask and other EVM wallets, deploy an AIR Account, and interact with the network.

Blockchain wallets allow you, and only you, to access your assets on Moca Chain. Wallets enable this by allowing you to create and store your private keys, which can then be used to prove that you can access the assets in the wallet to do things such as trade tokens, buy NFTs, play games, and more.

**To interact with Moca Chain you can either:**

* Deploy your AIR Account on Moca Chain
* Connect via your Web3 Wallet
* Or try out our [Block Explorer](/technicals/mocachain/block-explorer)

### Deploy your AIR Account on Moca Chain

<Tip>
  Interactive demo coming soon
</Tip>

## Moca Chain Networks 🌐

Copy and paste these values into any wallet that supports importing RPCs. Choose **Mainnet** for production assets or **Testnet** for development and experimentation. For the full network specification (CometBFT, LCD, consensus, and gas parameters), see the [Network Information](/technicals/mocachain/network-information) page.

### Moca Chain Mainnet

<Tip>
  The quickest way to add mainnet to your wallet is [ChainList](https://chainlist.org/chain/2288). To add it by hand, use these values.
</Tip>

| Key | Value |
| - | - |
| Network | `Moca Chain Mainnet` |
| RPC URL | `https://rpc.mocachain.org` |
| Chain ID | `2288` (`0x8F0`) |
| Currency symbol | `MOCA` |
| Decimals | `18` |
| Block explorer URL | `https://scan.mocachain.org` |

### Moca Chain Testnet

| Key | Value |
| - | - |
| Network | `Moca Chain Testnet` |
| RPC URL | `https://rpc.testnet.mocachain.dev` |
| Chain ID | `222888` (`0x366A8`) |
| Currency symbol | `MOCA` |
| Decimals | `18` |
| Block explorer URL | `https://testnet-scan.mocachain.org` |

## Supported Wallets 👛

Currently, any [EVM-based wallet](https://ethereum.org/en/wallets/find-wallet/) that allows `RPC importing` can be configured to work with Moca Chain.

Here are some examples of compatible wallets:

* [MetaMask](https://metamask.io)
* [Trust Wallet](https://trustwallet.com)
* [OKX Wallet](https://web3.okx.com/)
* [Ledger](https://www.ledger.com/)

## How To Set Up A MetaMask Wallet With Moca Chain 🦊

This will walk you through the steps of setting up and configuring a MetaMask wallet with Moca Chain.

<Info>Note: It is recommended that you set this up through Chrome.</Info>

### Step 1 - Install MetaMask

Go to MetaMask's [website](https://metamask.io/) and click to download the browser extension for your browser of choice. Make sure the extension is being offered by `metamask.io`.

<img alt="Metamask Chrome Store" />

### Step 2 - Create Your Wallet in MetaMask

Once MetaMask finishes installing as a Chrome extension, the initial prompt will show up. Click the `Create a new wallet` button to start the process.

<img alt="Metamask Get Started" />

This will ask you to first set a password. This is the password you will enter when you open up the MetaMask extension:

<img alt="Metamask Create Password" />

Next, follow the instructions to secure your wallet phrase. This step is very important as the wallet phrase is what is used to prove that you own the assets in your wallet.

<img alt="Metamask Recovery Phrase" />

🎉 Congratulations! You've set up your MetaMask wallet!

## Add Moca Chain Network To Your Wallet

Wallets can connect to various blockchains, with MetaMask setting Ethereum as its default blockchain. In order to connect to Moca Chain, we'll need to add the network to MetaMask and select it.

### Add Moca Chain Network in One Click

Use the network details from the **Mainnet** or **Testnet** table above to add Moca Chain to your MetaMask wallet, or add it manually below.

### Add Moca Chain Network Manually

To add the network manually, click the drop-down in the top-left of MetaMask.

<img alt="Metamask Add Network Step 1" />

When the modal appears, click the `Add network` button.

<img alt="Metamask Add Network Step 2" />

At the bottom of the existing list, click `Add network manually`.

<img alt="Metamask Add Network Step 3" />

Enter the values from the table that matches the network you want to use — Moca Chain Mainnet or Moca Chain Testnet — to configure MetaMask.

Once the data is entered correctly, click `Save`.

After saving the network configuration, you should be connected to your selected Moca Chain network.


# Consensus Layer
Source: https://docs.air3.com/technicals/mocachain/consensus-layer

How the Moca Chain consensus layer works — CometBFT Proof-of-Stake, 1-second block times, validator roles, governance, and EVM-compatible execution.

Moca Chain is built on the **CometBFT** consensus framework (the Cosmos SDK's BFT engine, formerly Tendermint Core) with Ethereum Virtual Machine **(EVM) compatibility** (based on EVMOS) and integrates with its own decentralized data storage network (based on Binance Greenfield).

## How Moca Chain works

The Moca Chain adopts a Proof-of-Stake (PoS) mechanism based on CometBFT consensus to ensure network security. This consensus mechanism ensures network security while providing efficient block generation. On Moca Chain, blocks are generated by a group of validators every 1 second, ensuring fast confirmation and processing of transactions.

### Moca Coin (\$MOCA)

In the Moca Chain ecosystem, the Moca serves as both the gas and governance token. As a gas token, Moca is used to pay for transaction fees and smart contract execution costs on the network. As a governance token, Moca holders can participate in the governance and decision-making process of the blockchain, promoting the decentralized development of the network.

### Validators

Validators on the Moca Chain play a crucial role in the network's security and reliability, but their responsibilities go beyond that. Here are the key duties and functions of validators within the Moca Chain network:

* **Ensuring Data Integrity and Availability**: Validators play an important role in ensuring the integrity and availability of data provided by Moca Chain Storage Providers (MCSPs). They can challenge the availability of the data provided by service providers either specifically or randomly to detect potential malicious actors or underperforming providers. For such actors, validators can impose appropriate penalties, such as slashing their stakes, thereby maintaining the quality and reliability of services within the Moca Chain ecosystem.
* **Participation in Network Governance**: Validators also play a key role in network governance. They participate in deciding the future direction of the Moca Chain ecosystem by voting and can adjust various network parameters as needed.

### CometBFT PoS

In CometBFT, consensus is achieved through a voting process among validators—nodes responsible for proposing and validating blocks. Here's a step-by-step breakdown:

1. **Block Proposal and Voting Rounds:** Validators take turns proposing blocks. Each block contains transactions that modify the chain's state, such as token transfers or data storage updates. Proposals are broadcast to the network, and validators vote in rounds: Prevote, Precommit, and Commit. A block is finalized if more than two-thirds of validators (by stake weight) precommit to it.

2. **Proof-of-Stake Mechanics:** Validators stake `\$MOCA` tokens to participate. The probability of being selected to propose a block is proportional to their stake. This incentivizes honest behavior, as malicious actions (e.g., double-signing) result in slashing—automatic deduction of staked tokens. Moca Chain produces blocks every (1) second, ensuring low latency and high throughput.

3. **Fault Tolerance:** CometBFT (formerly Tendermint) tolerates up to one-third of validators being faulty or offline without halting the network. This BFT property makes it resilient against attacks, provided the majority of stake is held by honest validators.

This consensus model secures Moca Chain's two primary states: account balances (including `\$MOCA` ledgers) and metadata for its object storage system. Transactions, such as uploading data to Moca Chain Storage Providers (MCSPs), directly impact these states, with validators ensuring integrity through consensus.


# Decentralized Storage
Source: https://docs.air3.com/technicals/mocachain/decentralized-storage

Moca Chain Storage Providers (MCSPs) — decentralized data storage for credentials, including provider lifecycle, data integrity, and payment flows.

# Moca Chain Storage Provider (MCSP)

Moca Chain Storage Provider(MCSP) is an infrastructure provider for storage services. They work in synergy with Moca Chain validators to provide a complete storage service. Validators store metadata and financial ledgers with consensus, while MCSPs store the actual data (payload data) of objects using the Moca Chain chain as the ledger and single source of truth. MCSPs provide a range of convenient services for users and DApps to manage data on Moca Chain.

### Key Functions

* **Data Handling:** Provide APIs (similar to Amazon S3) for uploading, downloading, and managing data.
* **Redundancy and Integrity:** Use virtual groups (GVGs) for data replication across providers, ensuring availability.
* **Service Lifecycle:** From proposal and staking to maintenance and exit, MCSPs follow a structured process.

## How it Works

MCSP need to register themselves firstly by depositing on the Moca Chain as their Service Stake. The Moca Chain validators will then conduct a governance procedure to vote to elect the MCSP. When joining and leaving the network, MCSP must follow specific actions to ensure data redundancy for users, or they will face fines on their Service Stake.

MCSP provide publicly accessible APIs that allow users to upload, download and manage data. These APIs are designed to be similar to Amazon S3 APIs, making it easier for existing developers to write code for them. MCSP are responsible for responding to user requests to write (upload) and read (download) data, as well as managing user permissions and authentications.

Each MCSP maintains its own **local full node**, allowing for a strong connection with the Moca Chain network. This enables the MCSP to directly monitor state changes, properly index data, send transaction requests in a timely manner and manage local data accurately.

To encourage MCSP to showcase their capabilities and provide a professional storage system with high-quality SLA, it is recommended that they advertise their information and prove to the community.

## Technical Details

### Architecture

MCSP contains fifteen core modules as shown below:

* **Gater**: Serves as the gateway for MCSP, providing HTTP services and adhering to the S3 protocol.
* **Authenticator**: Responsible for verifying authentication.
* **Approver**: Responsible for handling approval requests.
* **Uploader**: Handles `PutObject` requests and stores payload data into the piece store of the primary MCSP.
* **Downloader**: Responsible for handling `GetObject` requests and `GetChallengeInfo` requests.
* **Executor**: Responsible for handling background tasks.
* **Manager**: Responsible for managing task scheduling and other management functions.
* **P2P**: Responsible for handling the interaction of control information between MCSP.
* **Receiver**: Receives data from the primary MCSP, calculates the integrity hash, signs it, and returns it to the primary MCSP for sealing.
* **Signer**: Handles the signing of the MCSP data and holds all the SP's private keys.
* **Metadata**: Provides efficient query interfaces for meta info in MCSP.
* **BlockSyncer**: Records block info in Moca Chain.
* **PieceStore**: Interacts with underlying storage vendors, e.g., AWS S3, MinIO, OSS, etc.
* **SPDB**: Stores all the contexts of the background jobs and the metadata of MCSP.
* **BSDB**: Stores all the events' data from the Moca Chain and provides them to the Metadata service of MCSP.

### Implement Customization in the Moca Chain Storage Provider

From the code level, MCSP is not only an implementation layer, it has been expanded into a framework called **MocaSP**, which allows users to implement their own logics according to their own needs. If users want to implement some specific functions, they can override these methods that are declared in the abstract interfaces. If users don't need to implement customized requirements, MocaSP will use default implementations. There are nine important layers of abstraction:

* `lifecycle`: Provides abstract interfaces to manage services.
* `module`: Provides abstract interfaces to interact with different modules in MocaSP.
* `consensus`: Provides abstract interfaces about how to query data on Moca Chain.
* `piecestore`: Used to interact with underlying storage systems.
* `spdb`: Provides abstract interfaces about how to store background tasks and metadata of MCSP.
* `bsdb`: Provides abstract interfaces about how to query metadata in MCSP.
* `rcmgr`: Provides abstract interfaces about managing cpu and memory resources in MCSP.
* `task`: Provides abstract interfaces about the smallest unit for interacting with MCSP background services.
* `taskqueue`: Provides abstract interfaces about task scheduling and executing.

## Moca Chain Storage Provider Lifecycle

### Preparation

First, the storage provider needs to learn how to run and create a storage provider node, which requires several different user accounts and a unified external EndPoint.

* Follow Recommended Prerequisites to get ready
* Create the required accounts, E.g operator/funding/seal/approval/gv/bls
* Run all services of Storage Provider

### Proposal

The Moca Chain Storage Provider (MCSP) must initiate an on-chain proposal that outlines the `Msg` information to be automatically executed after receiving approval through the voting process. Specifically, the `Msg` in this case is `MsgCreateStorageProvider`. It's essential to ensure that the deposit tokens exceed the minimum deposit tokens specified on the chain.

Below are the required fields that need to be modified in the proposal:

* **Addresses**:
  * `sp_address`: The address of the storage provider that will be added to the network.
  * `seal_address`: The address used for sealing object.
  * `approval_address`: The address responsible for approving bucket/object creation.
  * `gc_address`: The address for garbage collection.
  * `maintenance_address`: The address is used for testing while in maintenance mode.
* **EndPoint**: Details of the endpoint where the MCSP will serve data requests.
* **Quota & Price**:
  * `read_price`: The cost in Gwei per byte per second for read operations.
  * `store_price`: The cost in Gwei per byte per second for data storage.
  * `free_read_quota`: The default free read quota allocated to users (e.g., 10GB).
* **Deposit for MCSP Staking**: The MCSP must stake the minimum required amount of \$MOCA as a commitment to providing storage services. Refer to the latest network parameters for the current staking requirement.
* **Deposit for Proposal**: The proposal itself must meet the minimum deposit requirement. Refer to the latest network parameters for the current deposit amount.

Initiating this on-chain proposal with the necessary modifications and deposits is a crucial step for the MCSP to become an active participant in the Moca Chain network, offering reliable and secure storage services to users.

### In Service

During the in-service status, Moca Chain Storage Providers (MCSPs) actively engage in the network's daily operations. They handle a variety of user requests, including data storage, retrieval, and other storage-related operations.

MCSPs assume a critical role in maintaining the availability, integrity, and confidentiality of the data they store. As gatekeepers of user access, they enforce proper authentication and authorization procedures to safeguard data from unauthorized access or tampering.

At this stage, MCSPs must create **virtual groups** within the Moca Chain network to efficiently serve buckets and objects. These virtual groups, resembling disk sectors, allow MCSPs to manage data storage in a more organized and optimized manner. By associating objects with virtual groups, MCSPs can limit the range of secondary storage providers responsible for storing object replica data, which enhances data redundancy and resilience.

Additionally, MCSPs are required to provide corresponding stakes for the amount of data they store. This staking mechanism further incentivizes MCSPs to offer reliable and high-quality services to users.

Moreover, the creation of virtual groups and staking helps to disentangle the interdependency between buckets/objects and MCSPs. By doing so, MCSPs mitigate the need for an extensive volume of transactions when modifying on-chain `BucketInfo` and `ObjectInfo` during MCSP exits and bucket migrations. This leads to more efficient network management and smoother transitions during changes in the network's composition.

### In Maintenance

The maintenance mode for service providers (MCSPs) is a status in which MCSPs do not serve any create/upload requests from users. There are two circumstances in which an MCSP can be in maintenance mode:

* When an MCSP joins the network after a proposal has passed, it will stay in `STATUS_IN_MAINTENANCE` until it sends a transaction including `msg MsgUpdateStorageProviderStatus` to Moca Chain to change its status to `STATUS_IN_SERVICE`.
* If an MCSP is already in service, it can send a transaction with `msg MsgUpdateStorageProviderStatus` to Moca Chain and request a maintenance duration. If there are no restrictions violated, the MCSP is allowed to enter maintenance mode immediately.

There are two restrictions that apply when an MCSP requests to be in maintenance:

* The total maintenance duration for each MCSP, within the number of blocks defined by `num_of_historical_blocks_for_maintenance_records`, should not exceed the `maintenance_duration_quota`.
* An MCSP is not allowed to make two consecutive requests to `STATUS_IN_MAINTENANCE` within `num_of_lockup_blocks_for_maintenance`, even if there are enough quotas for it.

To ensure the quality of service provided, we strongly recommend that MCSPs conduct a self-test via the maintenance account before turning back to `STATUS_IN_SERVICE`. This includes creating buckets/objects to verify that all functionalities work as expected.

### Exit

There are two types of exit based on the behavior and choices of the MCSP: **Graceful Exit** and **Forced Exit**.

### Graceful Exit

At some point, the MCSP may choose to voluntarily exit the Moca Chain storage network for various reasons. A graceful exit process is crucial to ensure a seamless transition of responsibilities and data to other MCSPs. During the exit process, the MCSP must continue to fulfill user query requests. Once the exit process is successfully completed, the MCSP can retrieve all the staked Moca.

To execute a graceful exit, all its stored data need to be migrated to other successor MCSPs that are willing to take over. This data migration process involves recovering data from the exiting MCSP by successor MCSPs in a secure and efficient manner. After the exiting MCSP sends a `StorageProviderExit` transaction to the Moca Chain, its status will turn to `STATUS_GRACEFUL_EXITING`. A successor MCSP can initiate the recovery process by first sending a `ReserveSwapIn` transaction to the Moca Chain, reserving the exiting MCSP's position in the respective **Global Virtual Group (GVG)** or **GVG Family** so that it will be allowed to recover data from other MCSPs. Once the successor SP successfully takes over all data in a GVG or GVG Family, it will send a `CompleteSwapIn` transaction to the Moca Chain, confirming the completion of the data transfer process.

Moca Chain incorporates an effective consensus mechanism to facilitate and validate the graceful exit process. Frequent data challenges are applied to the MCSPs that take over the data to verify the integrity and consistency of the migrated data.

### Forced Exit

An uncooperative MCSP no longer wishes to provide service and refuses to go through the standard graceful exit process. In such a case, Moca Chain governance will force the MCSP to exit, making it enter `STATUS_FORCED_EXITING`. The data recovery process for the successor MCSP is the same as the graceful exit mentioned above. However, a forced exit MCSP will face penalties, and its staked Moca will be locked into the Payment module governance account.


# Moca Chain EVM Compatibility
Source: https://docs.air3.com/technicals/mocachain/evm-compatibility

Moca Chain EVM compatibility — deploy Ethereum smart contracts unchanged on an EVMOS-based L1, supporting LONDON opcodes plus partial SHANGHAI support.

Moca Chain is a blockchain platform developed based on EVMOS (aka Cosmos EVM), which is a trusted Ethereum Virtual Machine (EVM) within the Cosmos ecosystem. Evmos provides EVM compatibility, enabling Moca Chain to run Ethereum smart contracts.

This compatibility means that developers can write and deploy the same smart contracts on Moca Chain and other EVM-compatible blockchains without requiring significant code modifications. Additionally, through EVM, smart contracts can interact with other EVM-compatible blockchains, making the development of multi-chain DApps possible.

As a result

* Cosmos \$MOCA and EVM \$MOCA are the same currency, managed by the same bank keeper module
* Moca uses moca-cosmos-sdk accounts so it only has EVM addresses (e.g. `0x1234...7890`)

Currently, EVM runs the LONDON instruction set, with support for some SHANGHAI opcodes, including

* EIP-3855
* EIP-3860
* EIP-1153
* EIP-5656
* EIP-6780

> *To learn what each EIP entails, check out the [EIP registry](https://eips.ethereum.org/).*

<Warning>
  **Feedback wanted!**

  New EIP supports are constantly assessed for integration so please reach out to us if you require a specific EIP so we can add to our roadmap if necessary.
</Warning>


# How To Get $MOCA
Source: https://docs.air3.com/technicals/mocachain/how-to-get-moca

How to get &#36;MOCA tokens to pay Moca Chain transactions: bridging from Ethereum or Base, exchange listings, and Testnet faucet steps.

\$MOCA is the network token used to pay for transactions on Moca Chain.
Learn more about the [\$MOCA token](/technicals/mocachain/moca-coin).

## Mainnet

### Bridge from Ethereum or Base

You can bridge your existing \$MOCA from Ethereum or Base to Moca Chain with [Stargate](https://stargate.finance), powered by LayerZero. Bridging works in both directions, so you can also move \$MOCA from Moca Chain back to Ethereum or Base.

<Steps>
  <Step title="Connect your wallet">
    Go to [stargate.finance](https://stargate.finance) and connect your wallet.
  </Step>

  <Step title="Choose the route">
    Select \$MOCA on Ethereum or Base as the source, and Moca Chain as the destination.
  </Step>

  <Step title="Confirm the transfer">
    Enter the amount, review the fee, and confirm the transaction in your wallet.
  </Step>

  <Step title="Receive on Moca Chain">
    Your \$MOCA arrives on Moca Chain within a few minutes. You can track the transfer on [LayerZero Scan](https://layerzeroscan.com).
  </Step>
</Steps>

**Fees:** You pay a LayerZero messaging fee in the source chain's gas token: ETH when you bridge from Ethereum or Base, and \$MOCA when you bridge out of Moca Chain. Stargate shows the fee before you confirm. Bridging from Moca Chain to Ethereum costs more than to Base because the fee covers Ethereum gas.

**Daily limits:** Each route has a daily limit that resets at 00:00 UTC. If your transfer doesn't go through, try a smaller amount or try again the next day.

<Note>
  When you bridge out of Moca Chain, some wallets label the amount as ETH on the confirmation screen. The amount is in \$MOCA and includes the bridge fee.
</Note>

To check that you are using the official \$MOCA token, compare the contract address:

| Network | \$MOCA contract |
| - | - |
| Ethereum | `0xF944e35f95E819E752f3cCB5Faf40957d311e8c5` |
| Base | `0x2B11834Ed1FeAEd4b4b3a86A6F571315E25A884D` |
| Moca Chain | Native token (no contract address) |

### Available on Exchanges

Currently \$MOCA is available on various centralized exchanges. For more information please refer to [Coin Gecko](https://www.coingecko.com/en/coins/moca-coin)

## Testnet

Go to the [**Testnet Faucet**](https://faucet.mocachain.org).

1. Verify on Discord (this is done to reduce botting)
2. Then enter your address then click Request

> *Note that you can only request from our faucet once every 24 hours.*

<Tip>If this is insufficient to your use case please reach out to our team for more testnet tokens.</Tip>

<img alt="Moca Faucet" />


# Moca Chain architecture and technical design
Source: https://docs.air3.com/technicals/mocachain/index

Moca Chain technical overview: EVMOS-based Layer 1 with CometBFT consensus, decentralized storage from BNB Greenfield, and cross-chain identity oracles.

> *Moca Chain is a Layer 1 EVM-compatible blockchain purpose-built for decentralized identity, enabling chain-agnostic identity data issuance and verifications.*

<Info>
  **Moca Chain mainnet is live** (EVM chain ID 2288). Add it to your wallet from [ChainList](https://chainlist.org/chain/2288), browse it on the [mainnet explorer](https://scan.mocachain.org), and see [Network information](/technicals/mocachain/network-information) for every endpoint.
</Info>

Moca Chain is built on EVMOS (a Cosmos SDK EVM implementation) and integrates Moca's adaptation of BNB Greenfield's decentralized storage. Oracles and bridges relay identity data to other chains, so Moca Chain becomes the single source of truth for identity while staying interoperable with the rest of Web3.

This means Moca Chain:

* Houses the credential and identity-based smart contracts
* Manages the decentralized storage where credentials live
* Lets users relay proofs across chains

## Sub-second identity flows

CometBFT consensus with 1-second blocks and instant finality. Age checks, KYC gates, and logins commit in a single block, so identity flows feel synchronous to the end user.

## Consumer-scale capacity

800 transactions per block and a 60,000,000 gas limit. The chain is sized for ZK verifier contracts and batched credential issuance at production volume rather than testnet workloads.

## Builder-ready

EVM-compatible with transient storage (EIP-1153) and other Shanghai opcodes. Existing Solidity contracts port over with little to no rewrite, and standard Ethereum tooling (Hardhat, Foundry, Remix, MetaMask) works out of the box. Integration timelines move from quarters to days.

## Decentralized credential storage (MCSP)

The Moca Chain Storage Provider network (MCSP) gives partners S3-compatible decentralized storage, modeled after BNB Greenfield. Issuers retain source records and signing keys, while encrypted credential payloads are stored with independent providers under holder-controlled decryption.

* Payload data is stored by independent Storage Providers
* Object metadata, payments, and permissions are recorded on-chain
* Apps interact via S3-compatible APIs to upload, download, and manage objects
* Replication and integrity proofs protect data availability

## Privacy by construction

Zero-knowledge proofs use Circom circuits and Groth16. Verification Programs configure requested claims and whether a ZK proof is required. Apps can confirm age or eligibility without disclosing the underlying values. Raw source documents remain with the issuer. Encrypted credential payloads may be stored in DStorage, while users control decryption and disclosure.

## Verify once, recognized everywhere

Proofs are relayed off Moca Chain via oracles and bridges. A single verification carries to every chain a partner ships into next, so users do not re-prove the same credential per ecosystem.

## Quick chain facts

| **Field** | **Details** |
| - | - |
| Consensus | CometBFT |
| Framework | Cosmos SDK |
| EVM | Ethereum Compatible. LONDON instruction set. Based on EvmOS v12. |
| Block Time | \~ 1 second |
| Finality | Instant (single-block) |
| Native Token | MOCA |
| Block Rewards | Exponential decay from rewards pool. Not yet implemented. |
| Max Validators | 100 (CometBFT hard limit: 10,000) |
| Chain ID (mainnet) | 2288 (0x8F0); Cosmos chain ID `moca_2288-1` |
| Chain ID (testnet) | 222888 (0x366a8) |
| Max Transactions Per Block | 800 |
| Max Gas Limit | 60,000,000 |
| Validator Key Scheme | ed25519 |

## CometBFT consensus layer

Moca Chain uses CometBFT consensus and is governed by \$MOCA holders who decide the future direction of the ecosystem:

* Community members can submit governance proposals with a minimum deposit
* Proposals enter a voting period
* Proposals must meet minimum participation thresholds
* Approved proposals are executed on-chain automatically

[More on the consensus layer →](/technicals/mocachain/consensus-layer)

## Cosmos SDK with EVM compatibility

Moca Chain combines the Cosmos SDK with EVM functionality based on EVMOS in a single environment:

* Cosmos \$MOCA and EVM \$MOCA are the same currency, managed by the same bank keeper module
* All addresses on chain look like EVM addresses (e.g., 0x1234...7890)
* The EVM runs the LONDON instruction set with selected SHANGHAI opcodes:
  * EIP-3855
  * EIP-3860
  * EIP-1153 (transient storage)
  * EIP-5656
  * EIP-6780

[More on EVM compatibility →](/technicals/mocachain/evm-compatibility)

## Moca Chain Storage Provider network (MCSP)

Moca Chain ships with a built-in decentralized storage layer, the MCSP network, inspired by BNB Greenfield:

* Payload data is stored by independent Storage Providers
* Object metadata, payments, and permissions are recorded on-chain
* Users and apps interact via S3-compatible APIs to upload, download, and manage objects
* Data availability is protected through replication and integrity proofs
* Providers earn storage fees for service, with penalties for misbehavior
* Verifiable, cost-efficient storage for the Moca credential system and broader applications

[More about the MCSP network →](/technicals/mocachain/decentralized-storage)


# Moca Chain CLI
Source: https://docs.air3.com/technicals/mocachain/moca-chain-cli

Use the Moca Chain CLI to manage Cosmos accounts, basic storage operations, and direct interaction with the Moca Chain network from your terminal.

Moca Chain CLI is a command line tool for you to manage your resources directly with the Cosmos and storage layer within Moca Chain.

<Warning>
  ⚠️ Repo not publicly available — please reach out to us if you would like to access this feature.
</Warning>

## CLI Guide

This command-line tool provides **basic storage features** such as:

* Creating buckets
* Uploading and downloading files
* Deleting resources

It also supports related operations for managing **groups, policies, banks, accounts**, and more.

### Command Organization

* Commands are organized into **categories** and implemented as subcommands for clarity.
* To see all command categories, use:
  ```
  moca-cmd -h
  ```

### Configuration File

* Use the `--home` option to set the path for the config file and keystore.
* By default, configuration is saved in the `.moca-cmd` directory under your system’s home directory.
* If you run a command that interacts with Moca Chain and:
  * There’s no `config/config.toml` file in the path
  * You didn’t use the `--config` flag\
    ...the tool will automatically generate a `config/config.toml` file with testnet settings.

### Example: Testnet Configuration

* The config file’s `rpcAddr` and `chainId` should match the Moca Chain network.

### Intelligent Storage Provider Selection

* The tool automatically picks the correct storage provider for each request.
* To upload to a specific provider, set the storage provider’s operator address.
* No need to change the config when working with different storage providers.

### Example Usage

To upload files to different buckets on different storage providers:

```
moca-cmd storage put test moca://bucket1/object1
moca-cmd storage put test moca://bucket2/object
```

Each command uploads to a different bucket/provider, without changing any configuration.

### Operations

<Warning>Detailed operation reference is currently in progress. Run `moca-cmd -h` to explore available commands.</Warning>


# $MOCA Token
Source: https://docs.air3.com/technicals/mocachain/moca-coin

$MOCA is the utility and governance token of Moca Network — powering an identity-driven data economy through the Proof-of-Data alignment model.

\$MOCA is the utility and governance token of the Moca Network, powering an identity-driven data economy. It is used to pay network fees for credential operations such as issuing, updating, and verifying credentials, and it is staked by core network participants to secure the system and enable services.

## Proof-of-Data model

Within Moca's Proof-of-Data model, \$MOCA aligns incentives across the ecosystem:

### Validators

Validators stake \$MOCA to participate in consensus, secure the network, and process transactions. Validators earn rewards and transaction fees, and may be subject to slashing for malicious or negligent behavior (for example double-signing or extended downtime).

### Storage providers (MCSP)

Storage providers (MCSP) stake \$MOCA to back decentralized credential data storage. Staking helps align reliability and integrity, and storage providers may be subject to slashing if they fail to meet availability, reliability, or data integrity requirements.

### Issuers

Issuers stake \$MOCA to register and issue credentials, and can earn revenue as their credentials are verified.

### Verifiers

Verifiers validate credentials and may stake \$MOCA to qualify for subsidy incentives that reduce effective verification costs.

### Governance participants

Governance participants can lock \$MOCA to receive veMOCA, which is used to vote on incentives and guide ecosystem priorities.

As credential adoption grows, demand for \$MOCA scales with real network usage through transaction fees, staking requirements, and governance participation.


# Network Information
Source: https://docs.air3.com/technicals/mocachain/network-information

Moca Chain network information — Mainnet and Testnet chain IDs, RPC endpoints, block explorer URLs, currency symbol, and connection parameters.

## Moca Chain Mainnet

Moca Chain mainnet is live. Add it to your wallet from [ChainList](https://chainlist.org/chain/2288).

| EVM Chain ID | 2288 (0x8F0) |
| - | - |
| Cosmos Chain ID | `moca_2288-1` |
| Native Token | \$MOCA (gas and governance) |
| RPC (EVM) | [https://rpc.mocachain.org](https://rpc.mocachain.org) |
| RPC (CometBFT) | [https://tm-rpc.mocachain.org](https://tm-rpc.mocachain.org) |
| Cosmos LCD (REST) | [https://lcd-api.mocachain.org](https://lcd-api.mocachain.org) |
| Explorer | [https://scan.mocachain.org](https://scan.mocachain.org) |
| Consensus | Proof-of-Stake (CometBFT) |
| Block Time | \~1 second |
| Finality | Instant (single-block) |
| Block Gas Limit | 60,000,000 |
| Block Max Transactions | 800 |
| Block Max Size | 3 MB |
| Unbonding Time | 21 days |
| EVM Compatibility | Fully compatible (Evmos-based), supports Solidity contracts and Ethereum tooling (Metamask, Remix, Foundry) |
| Smart Contract Version | Based on go-ethereum v1.10.26, with additional EIPs (3855, 3860, 1153, 5656, 6780) |
| Cosmos-sdk | v0.50.x |

## Moca Chain Testnet

| EVM Chain ID | 222888 (0x366a8) |
| - | - |
| Cosmos Chain ID | `moca_222888-1` |
| Native Token | \$MOCA (gas and governance) |
| RPC (EVM) | [https://rpc.testnet.mocachain.dev](https://rpc.testnet.mocachain.dev) |
| RPC (CometBFT) | [https://tm-rpc.testnet.mocachain.dev](https://tm-rpc.testnet.mocachain.dev) |
| Cosmos LCD (REST) | [https://api.testnet.mocachain.dev](https://api.testnet.mocachain.dev) |
| Explorer | [https://testnet-scan.mocachain.org](https://testnet-scan.mocachain.org) |
| Faucet | [https://faucet.mocachain.org](https://faucet.mocachain.org) |
| Consensus | Proof-of-Stake (CometBFT) |
| Block Time | \~1 second |
| Finality | Instant (single-block) |
| Block Gas Limit | 60,000,000 |
| Block Max Transactions | 800 |
| Block Max Size | 3 MB |
| Unbonding Time | 21 days |
| EVM Compatibility | Fully compatible (Evmos-based), supports Solidity contracts and Ethereum tooling (Metamask, Remix, Foundry) |
| Smart Contract Version | Based on go-ethereum v1.10.26, with additional EIPs (3855, 3860, 1153, 5656, 6780) |
| Cosmos-sdk | v0.50.x |


# How to run a challenger for Moca Chain
Source: https://docs.air3.com/technicals/mocachain/run-a-challenger

Run a Moca Chain challenger node to audit MCSP storage providers — system requirements, setup, and operational guidance for ensuring data integrity.

<Warning>⚠️ This section may change without prior notice</Warning>
Critical information in this section may be subject to change as the network is in early stages.

<Warning>
  🔒 Repo not publicly available — please reach out to us if you would like to run this code.
</Warning>

## Challenger Information

### Minimum System Requirements

| Component | Minimum Specification |
| - | - |
| Hardware | Desktop or laptop running recent versions of **Mac OS X** or **Linux** |
| CPU | **4 cores** |
| Memory (RAM) | **12 GB** |
| Storage | **1 TB HDD/SSD** |
| Bandwidth | **1 MB/s** |

## Setting up a challenger

### Prerequisite

* Pull the `develop` branch of the `moca-challenger` repository.
* The deployment of `moca-challenger` relies on validator binding initialization. If you want to deploy your own `moca-challenger`, you need to join as a new validator.

### Challenger Introduction

Moca ensures data integrity by regularly issuing challenge events to storage providers to prove that stored data has not been tampered with. This service allows end-users to monitor challenge events in the blockchain and perform verification.

#### Moca-challenger main components

`moca-challenger` includes 7 main goroutines: Monitor, Verifier, Vote Collector, Vote Broadcaster, Vote Collator, Tx Submitter, and Attest Monitor.

* **Monitor:** Polls the Moca blockchain to obtain new blocks, parse challenge events, and add them to the local database.
* **Verifier:** Verifies the integrity of the stored data by comparing root hashes.
* **Vote Broadcaster:** Broadcasts a signed vote on the blockchain for events that failed verification.
* **Vote Collector:** Polls the blockchain for votes broadcast by other Challenger services.
* **Vote Collator:** Collates votes to achieve a 2/3 consensus.
* **Tx Submitter:** Sends a `MsgAttest` to the blockchain after enough consensus votes are received.
* **Attest Monitor:** Polls the blockchain for successfully attested challenges and updates the database.

### Deploy moca-challenger

#### Configuration file

Set your private key, deployment environment, and gas limit. The `private_key` and `bls_private_key` can be obtained as described in the next section.

```json theme={null}
"moca_config": {
    "key_type": "local_private_key",
    "private_key": "your_challenger_private_key",
    "bls_private_key": "your_bls_private_key",
    "rpc_addrs": [ "https://tm-rpc.testnet.mocachain.dev" ],
    ...
},
"db_config": {
    "dialect": "mysql",
    "db_path": "tcp(127.0.0.1:3306)/challenger?charset=utf8&parseTime=True&loc=Local",
    ...
},
"sp_config": {
    "internal_sp_endpoints": [
      "https://gateway.storage-provider-0.testnet.mocachain.dev",
      "https://gateway.storage-provider-1.testnet.mocachain.dev",
      "https://gateway.storage-provider-2.testnet.mocachain.dev"
    ]
}
```

#### Run locally

##### Running MySQL in Docker

```bash theme={null}
docker run -p 3306:3306 --name moca -e MYSQL_ROOT_PASSWORD=moca -d mysql:8
```

##### Create a database

```sql theme={null}
mysql --port=3306 -h127.0.0.1 -uroot -pmoca
CREATE SCHEMA IF NOT EXISTS challenger DEFAULT CHARACTER SET utf8 COLLATE utf8_unicode_ci;
```

##### Get validator BLS key and challenger key

```bash theme={null}
./build/mocad keys export ${BLS_KEY_NAME} --unsafe --unarmored-hex --home=${CLIENT_KEYRING_DIR} --keyring-backend=test
./build/mocad keys export ${CHALLENGER_NAME} --unsafe --unarmored-hex --home=${CLIENT_KEYRING_DIR} --keyring-backend=test
```

##### Compile and launch moca-challenger

Assuming you have a validator running, compile and start the process.

```bash theme={null}
make build
./build/moca-challenger --config-type local --config-path ./config/config.json
```

#### Test and Verification

##### Create your own SP

The process is similar to creating a validator.

1. **Authorization:** Grant spending limits.
2. **Submit a proposal:** Use a JSON template to create a storage provider.

##### Tampering with data stored on SP

1. Create a bucket and upload a file.
2. Find the storage directory on your SP and modify the content of the data chunk file.

```bash theme={null}
./build/moca-cmd --home deployment/localup/ bucket create --primarySP 0x...yourSPAddress moca1
./build/moca-cmd --home deployment/localup/ object put --contentType "application/octet-stream" ./abctest moca://moca1/abctest
```

##### Challenge the data chunk of the object

* **Regular challenge:** Moca automatically generates random data availability challenges. The `moca-challenger` monitors these events. If data has been tampered with, the root hashes will not match, and the challenge will be successful. The validator will vote, and if 2/3 consensus is reached, the SP will be slashed.
* **Manual challenge:** Anyone can submit a transaction to challenge data availability.

##### Data recovery

Data recovery ensures that original data can be restored if lost on SPs.

1. Data is automatically recovered after a successful data challenge.
2. Data is automatically recovered when users find that the data is unreadable.
3. SPs can selectively recover lost data through tools.

When a challenge succeeds, the tampered data chunk file will be restored to the original file after a while.


# How to run a local testnet for Moca Chain
Source: https://docs.air3.com/technicals/mocachain/run-a-local-testnet

Run a local Moca Chain testnet for development — Go and jq prerequisites, native setup, and a single-validator chain to test your AIR Kit integrations.

<Info>
  🔓 The Moca Chain source code is publicly available on GitHub: [mocachain/moca](https://github.com/mocachain/moca).
</Info>

## Validator Information

### Prerequisites

* Git
* Go 1.23+ and jq (native run)
* Docker 24+ and Docker Compose (docker run)
* macOS or Linux

## Setting up Local Testnet

### Clone the Repo

Clone the repository and navigate to the base directory:

```bash theme={null}
git clone https://github.com/mocachain/moca.git

# checkout latest stable tag
git checkout tags/v1.2.1
```

### Deploy Single Node network.

#### 1. Build the binaries

```bash theme={null}
make build

# run ./build

# Otherwise...
# If gcc/ledger is not installed disable ledger support for build
# LEDGER_ENABLED=false make build
```

### 2. Deploy single validator / storage provider.

Start a single validator network with one Storage Provider:

```bash theme={null}
bash deployment/localup/localup.sh all 1 1
```

This initializes, generates genesis, and starts the node(s). Keys and data live under:

* `deployment/localup/.local/validator0`
* `deployment/localup/.local/sp0`

Ports and services:

* CometBFT RPC: `http://127.0.0.1:26657/status`
* EVM RPC: `http://127.0.0.1:8545`
* REST API (LCD): `http://127.0.0.1:1317`
* gRPC: `127.0.0.1:9090`

<Tip>🎉 Your local testnet is now setup for your testing!</Tip>

### 3. Interact with the chain

Here are some examples of how you can interact with the running services above.

```bash theme={null}
# Check node is producing blocks
curl -s localhost:26657/status | jq '.result.sync_info.latest_block_height'

# Show dev account (preloaded by the script)
./build/mocad keys show devaccount -a --keyring-backend test --home deployment/localup/.local/validator0

# Query bank balance of that address (replace ADDR with an address)
./build/mocad query bank balances ADDR --node tcp://127.0.0.1:26657

# Send EVM RPC requests
curl -s -X POST localhost:8545 -H 'content-type: application/json' --data '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}'
```

### 4. Stop/reset

If you need to stop/reset the chain here are the commands below:

```bash theme={null}
# Stop all localup-started nodes
bash deployment/localup/localup.sh stop

# Recreate from scratch (init + genesis + start)
bash deployment/localup/localup.sh all 1 1
```


# How to run a node for Moca Chain
Source: https://docs.air3.com/technicals/mocachain/run-a-node

Run a Moca Chain full node using Docker or Cosmovisor — system requirements, snapshot bootstrap, configuration, and ongoing maintenance for operators.

<Warning>⚠️ This section may change without prior notice</Warning>
Critical information in this section may be subject to change as the network is in early stages.

<Info>
  🔓 The Moca Chain source code is publicly available on GitHub: [mocachain/moca](https://github.com/mocachain/moca).
</Info>

## Network Information

| Network | Chain ID | EVM Chain ID | RPC (CometBFT) |
| - | - | - | - |
| Mainnet | moca\_2288-1 | 2288 | [https://tm-rpc.mocachain.org](https://tm-rpc.mocachain.org) |
| Testnet | moca\_222888-1 | 222888 | [https://tm-rpc.testnet.mocachain.dev](https://tm-rpc.testnet.mocachain.dev) |

## Node Information

### Minimum System Requirements

| Component | Requirement |
| - | - |
| OS | Desktop or laptop running recent versions of **Mac OS X** or **Linux** |
| Storage | **1 TB** free disk space, minimum read/write speed of **100 MB/s** |
| CPU | **4 cores** |
| Memory (RAM) | **12 GB** |
| Network | Broadband connection, upload/download at least **1 MB/s** |

### Recommended System Requirements

| Component | Recommended Specification |
| - | - |
| Processor (CPU) | **16-core CPU** |
| Memory (RAM) | **64 GB** |
| Storage | **3 TB SSD** |
| Network | Stable high-speed internet, minimum **5 MB/s** |

## Setting Up a New Node

### Prerequisites

**For Docker (Option A):**

* Docker
* jq

**For Manual Cosmovisor (Option B):**

* Git
* Go 1.23+
* jq
* macOS or Linux

## 1. Clone the Repo (Option B only)

<Tip>Skip this step if using the Docker image (Option A).</Tip>

Clone the repository and checkout the latest stable version:

```bash theme={null}
git clone https://github.com/mocachain/moca.git
cd moca

# checkout latest stable version
git checkout tags/v1.2.1
```

## 2. Install Cosmovisor

[Cosmovisor](https://docs.cosmos.network/sdk/v0.53/build/tooling/cosmovisor) is a process manager for Cosmos SDK nodes that automatically handles chain upgrades. It is the recommended way to run a Moca Chain node.

### Option A: Official moca-cosmovisor Docker Image (Recommended)

The official Docker image is available on [GitHub Container Registry](https://github.com/mocachain/moca/pkgs/container/mocad). This image comes with the genesis binary preinstalled and runs `mocad` with Cosmovisor.

```bash theme={null}
# Pull the latest image
docker pull ghcr.io/mocachain/mocad:v1.2.1

# For specific architecture
# linux/amd64
docker pull ghcr.io/mocachain/mocad:v1.2.1-amd64

# linux/arm64
docker pull ghcr.io/mocachain/mocad:v1.2.1-arm64
```

### Option B: Manual Cosmovisor Setup

If you prefer to run Cosmovisor manually without Docker, follow these steps.

#### Install Cosmovisor

```bash theme={null}
go install cosmossdk.io/tools/cosmovisor/cmd/cosmovisor@latest
```

#### Build or Download the Binary

You can either build from source or download pre-compiled binaries from [GitHub Releases](https://github.com/mocachain/moca/releases/tag/v1.2.1).

```bash theme={null}
# Option 1: Build from source
make build

# Option 2: Download pre-compiled binary (Linux arm64)
wget https://github.com/mocachain/moca/releases/download/v1.2.1/mocad_linux_arm64.tar.gz
tar -xzf mocad_linux_arm64.tar.gz
chmod +x mocad
mv mocad ./build/mocad
```

#### Setup Cosmovisor Directory Structure

```bash theme={null}
mkdir -p ~/.mocad/cosmovisor/genesis/bin
cp ./build/mocad ~/.mocad/cosmovisor/genesis/bin/mocad
```

## 3. Initialize Node

This will initialize your local moca node home directory `~/.mocad` containing chain data configuration.

### Using Docker (Option A)

<CodeGroup>
  ```bash [Mainnet] theme={null}
  docker run --rm -v ~/.mocad:/root/.mocad ghcr.io/mocachain/mocad:v1.2.1 \
    mocad init mynode --chain-id moca_2288-1 --default-denom amoca
  ```

  ```bash [Testnet] theme={null}
  docker run --rm -v ~/.mocad:/root/.mocad ghcr.io/mocachain/mocad:v1.2.1 \
    mocad init mynode --chain-id moca_222888-1 --default-denom amoca
  ```
</CodeGroup>

### Using Manual Cosmovisor (Option B)

<CodeGroup>
  ```bash [Mainnet] theme={null}
  ~/.mocad/cosmovisor/genesis/bin/mocad init mynode --chain-id moca_2288-1 --default-denom amoca
  ```

  ```bash [Testnet] theme={null}
  ~/.mocad/cosmovisor/genesis/bin/mocad init mynode --chain-id moca_222888-1 --default-denom amoca
  ```
</CodeGroup>

## 4. Pull Live genesis file

Fetch the genesis file for your target network.

<CodeGroup>
  ```bash [Mainnet] theme={null}
  RPC=https://tm-rpc.mocachain.org
  curl -s "$RPC/genesis?key=<YOUR_ACCESS_KEY>" | jq -r '.result.genesis' > ~/.mocad/config/genesis.json
  ```

  ```bash [Testnet] theme={null}
  RPC=https://tm-rpc.testnet.mocachain.dev
  curl -s "$RPC/genesis" | jq -r '.result.genesis' > ~/.mocad/config/genesis.json
  ```
</CodeGroup>

## 5. Add peers

Configure persistent peers so your node can join the p2p network.

<CodeGroup>
  ```bash [Mainnet] theme={null}
  # Mainnet public sentry nodes
  PEERS="d3e1ea4ad789bfc6c259019ae3ca13f05205f364@p2p.sentry-node-0.mocachain.dev:26656,015fda7c14ddd2e74a29a3118e5c28c069219257@p2p.sentry-node-1.mocachain.dev:26656"
  ```

  ```bash [Testnet] theme={null}
  # Discover peers dynamically from the testnet RPC
  PEERS=$(curl -s "$RPC/net_info" | jq -r '.result.peers[] | select(.node_info.id and .remote_ip) | "\(.node_info.id)@\(.remote_ip):26656"' | paste -sd, -)
  ```
</CodeGroup>

```bash theme={null}
# Update config with peers
# Use sed -i '' on macOS, sed -i on Linux
if [[ "$OSTYPE" == "darwin"* ]]; then SED_FLAG=(-i ''); else SED_FLAG=(-i); fi
[ -n "$PEERS" ] && \
  sed "${SED_FLAG[@]}" 's/seeds = ".*"/seeds = ""/' ~/.mocad/config/config.toml && \
  sed "${SED_FLAG[@]}" "s/persistent_peers = \".*\"/persistent_peers = \"$PEERS\"/" ~/.mocad/config/config.toml && \
  sed "${SED_FLAG[@]}" 's/addr_book_strict = true/addr_book_strict = false/' ~/.mocad/config/config.toml
```

Alternatively you can provide your own list of peers.

## 6. Fast sync state

State sync quickly bootstraps your node by trusting a recent block header (light client verification) and downloading a snapshot of the application state at that height, instead of replaying all historical blocks.

```bash theme={null}
# Get current height
HEIGHT=$(($(curl -s "$RPC/block" | jq -r '.result.block.header.height') - 1000))
HASH=$(curl -s "$RPC/block?height=$HEIGHT" | jq -r '.result.block_id.hash')

# Set trusted height and hash to sync from in your node configuration files
# Use sed -i '' on macOS, sed -i on Linux
if [[ "$OSTYPE" == "darwin"* ]]; then SED_FLAG=(-i ''); else SED_FLAG=(-i); fi
sed "${SED_FLAG[@]}" 's/^enable *= *.*/enable = true/' ~/.mocad/config/config.toml
sed "${SED_FLAG[@]}" "s|^rpc_servers *= *.*|rpc_servers = \"$RPC,$RPC\"|" ~/.mocad/config/config.toml
sed "${SED_FLAG[@]}" "s/^trust_height *= *.*/trust_height = $HEIGHT/" ~/.mocad/config/config.toml
sed "${SED_FLAG[@]}" "s/^trust_hash *= *.*/trust_hash = \"$HASH\"/" ~/.mocad/config/config.toml
sed "${SED_FLAG[@]}" 's/^trust_period *= *.*/trust_period = "168h0m0s"/' ~/.mocad/config/config.toml
```

## 7. Run the node

### Using Docker (Option A)

Run the Docker container with a mounted volume for persistent data:

<CodeGroup>
  ```bash [Mainnet] theme={null}
  docker run -d \
    --name mocad \
    -v ~/.mocad:/root/.mocad \
    -p 26656:26656 \
    -p 26657:26657 \
    -p 1317:1317 \
    -p 8545:8545 \
    ghcr.io/mocachain/mocad:v1.2.1
  ```

  ```bash [Testnet] theme={null}
  docker run -d \
    --name mocad \
    -v ~/.mocad:/root/.mocad \
    -p 26656:26656 \
    -p 26657:26657 \
    -p 1317:1317 \
    -p 8545:8545 \
    ghcr.io/mocachain/mocad:v1.2.1
  ```
</CodeGroup>

### Using Manual Cosmovisor (Option B)

`DAEMON_ALLOW_DOWNLOAD_BINARIES=true` enables Cosmovisor to automatically download new binaries during chain upgrades. Without this, the node will halt at the upgrade height and require manual binary replacement. Alternatively, you can pre-stage binaries at `$DAEMON_HOME/cosmovisor/upgrades/<upgrade-name>/bin/mocad`.

<CodeGroup>
  ```bash [Mainnet] theme={null}
  export DAEMON_NAME=mocad
  export DAEMON_HOME=$HOME/.mocad
  export DAEMON_ALLOW_DOWNLOAD_BINARIES=true
  cosmovisor run start --chain-id=moca_2288-1
  ```

  ```bash [Testnet] theme={null}
  export DAEMON_NAME=mocad
  export DAEMON_HOME=$HOME/.mocad
  export DAEMON_ALLOW_DOWNLOAD_BINARIES=true
  cosmovisor run start --chain-id=moca_222888-1
  ```
</CodeGroup>

The node will take some time to fully sync up to the current chain height.

## Verify Syncing

You can verify if state sync is done by curl localhost:26657/status several times and see whether **latest\_block\_height** is increasing in response.

```bash theme={null}
curl -s http://127.0.0.1:26657/status | jq -r ".result.sync_info.latest_block_height"
# Expect block height greater than 0
```


# How to run a storage provider for Moca Chain
Source: https://docs.air3.com/technicals/mocachain/run-a-storage-provider

Run a Moca Chain Storage Provider (MCSP) — hardware requirements, registration, staking, on-chain bonding, and operational setup for storing credential data.

# Running a Storage Provider (MCSP)

<Warning>⚠️ This section may change without prior notice</Warning>
Critical information in this section may be subject to change as the network is in early stages.

<Info>
  🔓 The Moca Storage Provider source code is publicly available on GitHub.
</Info>

## Storage Provider Information

### Recommended System Requirements

| **Component** | **Recommended Specification** | **Minimum Specification** |
| - | - | - |
| Hardware | VPS running recent versions of **macOS**, **Linux**, or **Windows** | VPS running recent versions of **macOS**, **Linux**, or **Windows** |
| CPU | **16 cores** | **8 cores** |
| Memory (RAM) | **64 GB** | **32 GB** |
| Storage | At least **4** **TB** disk space for backend storage + **50 GB+ SQL database** | At least 2 **TB** disk space for backend storage + **50 GB+ SQL database** |
| Bandwidth | **10 MB/s+** upload/download speed | **10 MB/s+** upload/download speed |

## Setting Up Moca Chain Data Storage Provider

### MCSP Compiling and Dependencies

#### Compile MCSP

**Compilation dependencies:**

* **Golang:** MCSP is written in Golang, and you need to install version 1.23+.
* **Buf:** A new way of working with Protocol Buffers. MCSP uses Buf to manage proto files.
* **protoc-gen-gocosmos:** Protocol Buffers for Go with Gadgets. MCSP uses this protobuf compiler to generate `pb.go` files.
* **mockgen:** A mocking framework for the Go programming language that is used in unit tests.
* **jq:** A command-line JSON processor. Users should install `jq` according to their operating system.

```bash theme={null}
# clone source code
git clone https://github.com/mocachain/moca-storage-provider.git
cd moca-storage-provider/

# install dependent tools: buf, protoc-gen-gocosmos and mockgen
make install-tools

# compile sp
make build

# move to build directory
cd build

# execute moca-sp binary file
./moca-sp version
```

#### Note

If you've already executed the `make install-tools` command in your shell, but you failed to `make build` and encountered one of the following error messages:

**Error message 1:**

```
buf: command not found
```

You can execute the following command, assuming you installed Golang in `/usr/local/go/bin`. Other OS are similar.

```bash theme={null}
GO111MODULE=on GOBIN=/usr/local/go/bin go install github.com/bufbuild/buf/cmd/buf@v1.25.0
```

**Error message 2:**

```
Failure: plugin gocosmos: could not find protoc plugin for name gocosmos - please make sure protoc-gen-gocosmos is installed and present on your $PATH
```

You can execute the following command, assuming you installed Golang in `/usr/local/go/bin`. Other OS are similar.

```bash theme={null}
GO111MODULE=on GOBIN=/usr/local/go/bin go install github.com/cosmos/gogoproto/protoc-gen-gocosmos@latest
```

If you want to execute a unit test of sp, you should execute the following command, assuming you installed Golang in `/usr/local/go/bin`. Other OS are similar.

```bash theme={null}
GO111MODULE=on GOBIN=/usr/local/go/bin go install go.uber.org/mock/mockgen@latest
```

> The error messages above are due to users not setting the Go environment correctly. For more info, users can search for GOROOT, GOPATH, and GOBIN.

### MCSP Dependencies

If a user wants to start MCSP in local mode or testnet mode, you must prepare `SPDB`, `BSDB`, and `PieceStore` dependencies.

#### SPDB and BSDB

MCSP uses `SPDB` and `BSDB` to store some metadata such as object info, object integrity hash, etc. These two DBs now use RDBMS to complete corresponding functions.

Users can now use MySQL or MariaDB to store metadata. The following lists the supported RDBMS:

* MySQL
* MariaDB

> More types of databases such as PostgreSQL or NewSQL will be supported in the future.

#### PieceStore

Moca Chain is a decentralized data storage system that uses object storage as the main data storage system. MCSP encapsulates data storage as `PieceStore`, which provides common interfaces to be compatible with multiple data storage systems. Therefore, if a user wants to join MCSP or test the function of MCSP, you must use a data storage system.

The following lists the supported data storage systems:

* **AWS S3:** An object storage that can be used in a production environment.
* **Aliyun OSS:** Fully managed object storage service to store and access any amount of data from anywhere.
* **B2:** Backblaze B2 provides unlimited data storage in the cloud at ⅕th the cost of Amazon S3.
* **MinIO:** An object storage that can be used in a production environment and is compatible with AWS S3.
* **POSIX Filesystem:** A local filesystem is used for experiencing the basic features of MCSP and understanding how MCSP works. The piece data created by MCSP cannot be gotten within the network and can only be used on a single machine.

## Run Local MCSP Network

This guide helps you to set up a local Moca Chain Storage Provider network for testing and other development-related purposes.

### Recommended Prerequisites

The following lists the recommended hardware requirements:

* VPS running recent versions of Mac OS X, Linux, or Windows;
* 16 cores of CPU, 64 GB of memory (RAM);
* At least 100GB disk space for backend storage;
* 10GB+ SQL Database.

### Quickly setup local Moca Chain network

**Build Moca Chain**

```bash theme={null}
git clone https://github.com/mocachain/moca.git
cd moca
make build
```

**Start Moca Chain**

```bash theme={null}
# 1 validator and 4 storage providers
bash ./deployment/localup/localup.sh all 1 2
```

**Export the keys of MCSPs**

```bash theme={null}
bash ./deployment/localup/localup.sh export_sps 1 2
```

These JSON data will be used to set up the local MCSP network, so you'd better save it as a JSON file:

```bash theme={null}
bash ./deployment/localup/localup.sh export_sps 1 2 > sp.json
```

### Setup local MCSP network

**Compile MCSP**

```bash theme={null}
git clone https://github.com/mocachain/moca-storage-provider.git
cd moca-storage-provider
make build
```

**Generate localup env**
Use the following instruction to generate a template config file, `sp.info`, and `db.info` in seven different directories. This command is used for generating the MCSP env for the first time or regenerating the MCSP env.

```bash theme={null}
# This command accepts four args, the first arg is json file path that only supports absolute path, the second arg is db user name,
# the third arg is db password and the fourth arg is db address.
cd moca-storage-provider/
bash ./deployment/localup/localup.sh --generate json_file_path db_username db_password db_address
```

> The json file path accepted for the first arg is generated by the "Quickly setup local Moca Chain network" step.

**View directory structure:**

```
ls deployment/localup/local_env/sp0
├── sp0
│   ├── config.toml # generated template config file
│   ├── db.info # generated db.info is used for config.toml
│   ├── moca-sp0 # moca-sp binary
│   └── sp.info # generated sp.info is used for config.toml
├── sp1
├── ...
```

An example for generating a local sp env:

```bash theme={null}
cd moca-storage-provider/
bash ./deployment/localup/localup.sh --generate /root/sp.json root moca localhost:3306
```

```bash theme={null}
[root@yourmachine sp0]# cat db.info
#!/usr/bin/env bash
USER="root" # database username
PWD="moca" # database password
ADDRESS="localhost:3306" # db endpoint, e.g. "localhost:3306"
DATABASE="sp_0" # database name
```

```bash theme={null}
[root@yourmachine sp0]# cat sp.info
#!/usr/bin/env bash
SP_ENDPOINT="127.0.0.1:9033" # gateway endpoint, e.g. "127.0.0.1:9033"
OPERATOR_ADDRESS="0x14539343413EB47899B0935287ab1111Df891d04" # OperatorAddr is generated in setup local Moca Chain step 3.
OPERATOR_PRIVATE_KEY="ba6e97958d9c43d1ad54923eba99f8d59f54a0c66c78a5dcbc004c5c3ec72f8c" # OperatorPrivKey is generated in setup local Moca Chain step 3.
FUNDING_PRIVATE_KEY="bd9d9e7823cd2dc7bc20f1b6676c3025cdda6cf5a8df9b04597fdff42c29af01" # FundingPrivKey is generated in setup local Moca Chain step 3.
SEAL_PRIVATE_KEY="aacd6b834627fdbc5de2bfdb1db31be0ea810a941854787653814c8040a9dd39" # SealPrivKey is generated in setup local Moca Chain step 3.
APPROVAL_PRIVATE_KEY="32108ed1a47c0af965824f84ac2162c029f347eec6d0988e642330b0ac264c85" # ApprovalPrivKey is generated in setup local Moca Chain step 3.
GC_PRIVATE_KEY="2fad16031b4fd9facb7dacda3da4ca4dd5f005f4166891bf9f7be13e02abb12d" # GcPrivateKey is generated in setup local Moca Chain step 3.
BLS_PRIVATE_KEY="6f349866f18413abb1a78cab947933459042044649686f354e941a646b9ed6e7" # BlsPrivateKey is generated in setup local Moca Chain step 3.
```

### Start Four MCSPs

Make `config.toml` according to `db.info`, `sp.info` and start four MCSPs.

```bash theme={null}
cd moca-storage-provider/
bash ./deployment/localup/localup.sh --reset
bash ./deployment/localup/localup.sh --start
```

The environment directory is as follows:

```
deployment/localup/local_env/
├── sp0
│   ├── config.toml # real config
│   ├── data/ # piecestore data directory
│   ├── db.info
│   ├── moca-sp0
│   ├── moca-sp.log # moca-sp log file
│   ├── log.txt
│   └── sp.info
├── sp1
├── ...
```

### Recompile MCSP

If you want to modify `config.toml` in different MCSP directories or recompile the `moca-sp` binary file, you can use the following commands to reset and start the local MCSP:

```bash theme={null}
cd moca-storage-provider/
bash ./deployment/localup/localup.sh --reset
bash ./deployment/localup/localup.sh --start
```

### One-step (Recommended)

#### Quickly setup local Moca Chain network

Build Moca Chain Image and start Moca Chain network with docker-compose.

```bash theme={null}
git clone https://github.com/mocachain/moca.git
cd moca
# export sp config json file to moca-storage-provider/deployment/dockerup
bash deployment/dockerup/localup.sh backup
```

#### Setup local MCSP network

```bash theme={null}
git clone https://github.com/mocachain/moca-storage-provider.git
cd moca-storage-provider
```

### Operate With MCSP

If you have already started Moca Chain and Moca Chain MCSP successfully locally, you can use `moca-cmd` to operate with MCSP such as `CreateBucket`, `PutObject`, and `GetObject`. Detailed info about `moca-cmd` can be found here.

Next, we provide you a hand-by-hand tutorial to operate with the chain and MCSP.

#### Generate your test account

First, we need to generate a test account and private key:

```bash theme={null}
# this command will generate a test account whose name is testkey, you can change its name
mocad keys add testkey --keyring-backend test

# export the private key of test account
mocad keys export testkey --unarmored-hex --unsafe --keyring-backend test
```

After generating a test account, there are no tokens in this account. We should transfer some \$MOCA:

```bash theme={null}
# transfer 5000 \$MOCA
mocad tx bank send validator0 {generated_test_account_address} 5000000000000000000000amoca --home /{your_moca_path}/moca/deployment/localup/.local/validator0 --keyring-backend test --node http://localhost:26657 -y

# query your account balances
mocad q bank balances {generated_test_account_address} --node http://localhost:26657
```

#### Use cmd to send requests

If you have come to this step, congratulations, you can operate with your own private chain and MCSP.

First, we need to configure `cmd`:

```bash theme={null}
cd moca-cmd/
make build

# generate a keystore file to manage private key information
touch key.txt & echo ${TEST_ACCOUNT_PRIVATE_KEY} > key.txt
touch password.txt & echo "test_sp_function" > password.txt
./build/moca-cmd --home ./ --passwordfile password.txt account import key.txt

# construct config.toml
touch config.toml
```

Write the following content:

```
rpcAddr = "https://tm-rpc.testnet.mocachain.dev:443"
chainId = "moca_222888-1"
```

Second, you can do some operations with MCSP:

**Create bucket**

```bash theme={null}
# list current available SPs
./build/moca-cmd -c ./config.toml --home ./ sp ls

# random choose one SP to create bucket
./build/moca-cmd -c ./config.toml --home ./ bucket create moca://${BUCKET_NAME}

# head bucket info
./build/moca-cmd -c ./config.toml --home ./ bucket head moca://${BUCKET_NAME}

# choose one sp to create bucket, operator_address is shown in sp ls result
./build/moca-cmd -c ./config.toml --home ./ bucket create --primarySP ${operator_address} moca://${BUCKET_NAME}
```

**PutObject & GetObject**

```bash theme={null}
# generate a 17MB random file
dd if=/dev/urandom of=./random_file bs=17M count=1

# put object
./build/moca-cmd -c ./config.toml --home ./ object put --contentType "application/octet-stream" ./random_file moca://${BUCKET_NAME}/random_file

# get object
./build/moca-cmd -c ./config.toml --home ./ object get moca://${BUCKET_NAME}/random_file ./new_random_file
```

> Users can use `md5` to compare your generated file and the downloaded file to see whether it is the same. You can explore other functions of `moca-cmd`.

## Run MCSP Node

This guide helps you set up an MCSP Node. Once you set up the MCSP Node successfully, you can follow the "Join SP Network" guide to make it online.

### Prerequisites

#### Recommended Hardware

The following lists the recommended hardware requirements:

* VPS running recent versions of Mac OS X, Linux, or Windows;
* 16 cores of CPU, 64 GB of memory (RAM);
* 1 Gbps network connection with upload/download speeds of 10MB/s+;
* At least 1 TB disk space for backend storage;
* 50GB+ SQL database;
* Piece Store: AWS S3, MinIO (Beta);
* 6 `mocad` accounts with enough \$MOCA.
  > **IMPORTANT:** Each storage provider will hold 7 different accounts serving different purposes.

#### Wallet Preparation

* **Operator Account:** Used to edit the information of the StorageProvider. Please make sure it has enough Moca to pay the gas fee of `EditStorageProvider` and `UpdateStorageProviderStatus` transactions.
* **Funding Account:** Used to deposit staking tokens and receive earnings. It is important to ensure that there is enough money in this account, and the MCSP must submit a deposit as a guarantee. At least 500+ Moca are required for staking. You should use this address to send a `CreateStorageProvider` proposal on-chain. Besides the 500 Moca for staking, the funding address should have enough tokens for creating VGF to store more data, so we suggest depositing at least 510 Moca into this account.
* **Seal Account:** Used to seal the user's object. Please make sure it has enough Moca to pay the gas fee of the `SealObject` transaction. We suggest depositing 10 Moca into this account.
* **Approval Account:** Used to approve user's requests. This account does not require holding \$MOCA.
* **GC Account:** It is a special address for sp and is used by sp to clean up local expired or unwanted storage. Please make sure it has enough \$MOCA because it's going to keep sending transactions up the chain.
* **Maintenance Account:** It is used for MCSP self-testing while in maintenance mode. This account for creating buckets and objects will be allow-listed by the Chain, while other users' create requests will fail.
* **Bls Account:** Used to create a bls signature when sealing objects to ensure integrity; it does not need to be deposited.

There are six accounts below. You can use the command below to generate these accounts:

```bash theme={null}
mocad keys add operator --keyring-backend test
mocad keys add seal --keyring-backend test
mocad keys add approval --keyring-backend test
mocad keys add gc --keyring-backend test
mocad keys add maintenance --keyring-backend test
mocad keys add bls --keyring-backend test --algo eth_bls
```

and then export these private keys to prepare for SP deployment:

```bash theme={null}
mocad keys export operator --unarmored-hex --unsafe --keyring-backend test
mocad keys export seal --unarmored-hex --unsafe --keyring-backend test
mocad keys export approval --unarmored-hex --unsafe --keyring-backend test
mocad keys export gc --unarmored-hex --unsafe --keyring-backend test
mocad keys export bls --unarmored-hex --unsafe --keyring-backend test
```

> **IMPORTANT:** `FundingAddress` is used to deposit staking tokens and receive earnings. Therefore, users should prepare their own `FundingAddress` public key and private key. And keep the private key of `FundingAddress` in a cold wallet for safety! The private keys of `OperatorAddress`, `SealAddress`, `ApprovalAddress`, `GCAddress`, and `BlsAddress` can be kept in a hot wallet because they are often used to send transactions.

If you want to generate a public key and private key of `FundingAddress` in the `mocad` binary file, you can execute the following commands:

```bash theme={null}
mocad keys add funding --keyring-backend test
mocad keys export funding --unarmored-hex --unsafe --keyring-backend test
```

The `maintenance` account is not needed for MCSP deployment, but you should export it to conduct a self-test:

```bash theme={null}
mocad keys export maintenance --unarmored-hex --unsafe --keyring-backend test
```

> Please keep these seven private keys safe!

Moreover, obtain the `bls` public key and generate a `bls` proof to fill in the proposal of creating a Storage Provider.

**bls\_pub\_key:**

```bash theme={null}
mocad keys show bls --keyring-backend test --output json | jq -r '.pubkey_hex'
```

**bls\_proof:**

```bash theme={null}
# Replace the ${bls_pub_key} with the above bls_pub_key to ensure you sign the correct bls pub key!!!
mocad keys sign "${bls_pub_key}" --from bls --keyring-backend test
```

#### Database Configuration

You should create two databases: `${SpDB.Database}` and `${BsDB.Database}`.

> **IMPORTANT:** `${BsDB.Database}` requires `utf8mb4_unicode_ci` as the character set and collation.

The following example assumes `${SpDB.Database}` as `storage_provider_db` and `${BsDB.Database}` as `block_syncer`.

```sql theme={null}
-- login to mysql and create database
-- the default encoding for the database should be utf8mb4_unicode_ci
mysql> CREATE DATABASE storage_provider_db;
mysql> CREATE DATABASE block_syncer CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

-- check the database encoding format
mysql> show create database block_syncer;
```

> This is the encoding we expect to see.

### Create Storage Provider

#### Compile MCSP

Follow the "Compile MCSP" doc to compile the MCSP binary or you can download the binary from the Moca Chain Storage Provider Release.

#### MCSP Config

##### Generate config template

```bash theme={null}
cd moca-storage-provider/build
# dump default configuration
./build/moca-sp config.dump
```

##### Write config

You can learn about how to write your `config.toml` file here.

> It's recommended to deploy a Kubernetes cluster following this guide. The corresponding config file is here.

#### Run MCSP

```bash theme={null}
# start sp
./moca-sp --config ${config_file_path}
```

## Join MCSP Network

This guide will help you join the MCSP Network: Testnet.

### Prerequisite for Becoming a Testnet MCSP

To ensure the stable provision of data services, Storage Providers must meet specific criteria to join the testnet.

* The MCSP must join the testnet for a minimum of one month.
* The MCSP must store over 1K files across more than 100 buckets on the testnet.
* There were no slash events on the MCSP in the past week.

### How to Join MCSP Network

Moca Chain validators are responsible for selecting storage providers. For each on-chain proposal to add a new storage provider, there is a deposit period for depositing Moca and a voting period for validators to cast votes. Once the proposal passes, the new MCSP can join the network afterwards.

#### Submit Proposal

The MCSP needs to initiate an on-chain proposal that specifies the `Msg` information to be automatically executed after the vote is approved. In this case, the `Msg` is `MsgCreateStorageProvider`. It's worth noting that the deposit tokens need to be greater than the minimum deposit tokens specified on the chain.

```
rpcAddr = "https://tm-rpc.testnet.mocachain.dev:443"
chainId = "moca_222888-1"
```

##### Hot Wallet Manual

You can use the `mocad` command to directly send the transaction for creating a storage provider. To do this, please import the private key of the funding account into the Keystore.

> However, it is not safe to use a hot wallet for Testnet. Instead, you should refer to the Hardware Wallet Manual for instructions on using a hardware wallet.

Command for creating storage provider:

```bash theme={null}
mocad tx sp create-storage-provider ./create_storage_provider.json --from {funding_address} --node ${rpcAddr} --chain-id ${chainId} --keyring-backend test
```

The content for `create_storage_provider.json`, modify it with the correct values as you need:

```json theme={null}
{
  "title": "create storage provider",
  "summary": "use proposal create storage provider",
  "messages": [
    {
      "@type": "/moca.sp.MsgCreateStorageProvider",
      "creator": "0x7b5Fe22B5446f7C62Ea27B8BD71CeF94e03f3dF2",
      "description": {
        "moniker": "sp_one_0",
        "identity": "",
        "website": "http://website",
        "security_contact": "",
        "details": "sp_one_0 detail"
      },
      "sp_address": "0x138b2fa467B83432E2AB97Df560A21E5b947fF3F",
      "funding_address": "0x3b8388788238AE1D2C3aA0fbdE88fE91161f5753",
      "seal_address": "0x2d7dAF0a129B93017072782fF0a8bB6923cde51b",
      "approval_address": "0xC8E82835fc2713f55ce7F762926A1B7e68eF4163",
      "gc_address": "0xcD0A9C31C27C231b3417D57083f87Fc1B5aa8ED0",
      "maintenance_address": "0x3b8388788238AE1D2C3aA0fbdE88fE91161f5753",
      "endpoint": "http://moca-sp-one-0.moca-sp-one:9033",
      "deposit": {
        "denom": "amoca",
        "amount": "100000000000000000000000"
      },
      "read_price": "100.000000000000000000",
      "free_read_quota": "100000000",
      "store_price": "10000.000000000000000000",
      "bls_key": "2a3be31fa821e170ec5c13812fd77e072cf7985361ea72aee01723f3f38582df1a3d7440d2b5517d02901ccf5adb4250bf2e8ead1c7908cae4cfb1348abfd33007ade14bc03b28578ff08ef6cdf20c8d0fb07498caeb6c9c85d48a29da6d45a6169ee49ff754703d233dbfb1bf35ef8aa14128a91227a8b03dab3c8812d865db",
      "bls_proof": "1b535ba8f1e307deea80a5be6919a20cb98c2cc46b78984b3052775a6f5293e9134be6012f68f6cff059cd4483b62a231d7c76bdbc6066ff5058bc5b90511f1e"
    }
  ],
  "metadata": "ipfs://CID",
  "deposit": "10000000000000000000000amoca"
}
```

##### Hardware Wallet Manual

The `mocad` command is not available for connecting with the hardware wallet, so you should use the `mocad-tx-sender` to send transactions. Here are the steps:

**Generate the transaction data:**

```bash theme={null}
mocad tx sp create-storage-provider ./create_storage_provider.json --from {funding_address} --print-eip712-msg-type
```

> **Note:**
>
> * You can get the `gov` module address by this command: `curl -X GET "https://api.testnet.mocachain.dev/cosmos/auth/v1beta1/module_accounts/gov" -H "accept: application/json"`
> * `endpoint` is the URL of your gateway.
> * `read_price` and `store_price` units are wei/bytes/s.
> * `free_read_quota` unit is Bytes.
> * `creator` is the address of the `gov` module.
> * `metadata` is optional.

#### Deposit Moca to Proposal

> **Note:** You can get the minimum deposit for a proposal by the above command. Please make sure that the initial deposit is greater than `min_deposit` when submitting the proposal.

```bash theme={null}
curl -X GET "https://api.testnet.mocachain.dev/cosmos/gov/v1/params/deposit" -H "accept: application/json"
```

You can skip this step if the initial deposit amount is greater than the min deposit required by the proposal. Each proposal needs to deposit enough tokens to enter the voting phase.

```bash theme={null}
mocad tx gov deposit ${proposal_id} 1Moca --from ${funding_address} --keyring-backend test --node ${rpcAddr} --chain-id ${chainId}
```

#### Wait Voting and Check Voting Result

After submitting the proposal successfully, you must wait for the voting to be completed and the proposal to be approved. It will last 1 day on Testnet. Once it has passed and is executed successfully, you can verify that the storage provider has been joined.

> **Warning:** Please ensure that the storage provider service is running before it has been joined.

You can check the on-chain MCSP information to confirm whether the MCSP has been successfully created.

```bash theme={null}
mocad query sp storage-providers --node ${rpcAddr}
```

Alternatively, you can check the proposal to know about its execution status.

```bash theme={null}
mocad query gov proposal ${proposal_id} --node ${rpcAddr}
```

#### Activate MCSP

##### Storage Provider Standard Test

After the proposal has passed, the status of MCSP is `STATUS_IN_MAINTENANCE`. To prevent being slashed due to functional abnormalities, you should first perform a full functional test using the maintenance account. You can refer to the MCSP standard test.

##### Update MCSP status

Once the testing is completed, you need to send a transaction to activate the MCSP to `STATUS_IN_SERVICE`.

```bash theme={null}
mocad tx sp update-status [sp-address] STATUS_IN_SERVICE [flags]
```

#### MCSP address deposit

##### Funding Address

As a new MCSP, you need to deposit a minimum amount of Moca into the funding address. Please note the initial deposit requirement varies in different environments. You can check the `sp.params.min_deposit` value (in wei Moca) from the genesis endpoint response of the Moca Chain testnet. At the time when this doc is written, according to `https://tm-rpc.testnet.mocachain.dev/genesis`, MCSP in testnet requires a minimum of 500 Moca deposited in the funding address.
In addition, to join the network, an MCSP must initiate a proposal using a funding address and have an additional >1 Moca to cover these costs.

##### Operator Address

The MCSP operator address will be used to send "Create Global Virtual Group", "Edit Storage Provider", "Update Storage Provider Status", and other transactions to the Moca Chain. So it requires some Moca deposited for the transaction fee as well. We recommend the MCSP operator address can hold at least 0.1 Moca but not necessarily as much as possible.

### Storage Provider Operations

#### EditStorageProvider

This command is used to edit the information of the MCSP, including endpoint, description, etc.

**Usage:**

```bash theme={null}
mocad tx sp edit-storage-provider [sp-address] [flags]
```

For example, to edit the endpoint:

```bash theme={null}
mocad tx sp edit-storage-provider ${operator_address} --endpoint ${new_endpoint} --from ${operator_address} --keyring-backend test --node ${rpcAddr} --chain-id ${chainId}
```

#### Update MCSP Price

Update the storage provider read, store price and free read quota. If there is no change to a specific value, the current value should also be provided.

* The unit of price is a decimal, which indicates wei Moca per byte per second. E.g. the price is 0.02183945725, which means approximately \$0.018/GB/Month.
* The `free-read-quota` unit is bytes; for 1GB free quota, it should be 1073741824.

**Usage:**

```bash theme={null}
mocad tx sp update-price [sp-address] [read-price] [store-price] [free-read-quota] [flags]
```

**Example:**

```bash theme={null}
mocad tx sp update-price ${operator_address} 0.1469890427 0.02183945725 1073741824 --from ${operator_address} --keyring-backend test --node ${rpcAddr} --chain-id ${chainId}
```

#### Update MCSP Quota

Besides the `update-price` command above, you can also use the `moca-sp` command to update the free read quota for MCSP. The `update.quota` command is used to update the free quota of the MCSP; it will send a transaction to the blockchain to update the free read quota but keep the storage price and read price unchanged.

**Usage:**

```bash theme={null}
./build/moca-sp update.quota [command options] [arguments...]
```

**Example:**

```bash theme={null}
./build/moca-sp update.quota --quota 1073741824 --config ./config.toml
```

#### Recover MCSP Objects

Besides the commands above, you can also use the `moca-sp` command to recover objects for MCSP, whether it is the primary or secondary sp of the object. The `recover.object` command is used to recover an object or objects of the MCSP; it will send a request to other MCSPs to get a replicate of the object(s) you want to recover.

**Usage:**

```bash theme={null}
./build/moca-sp recover.object [command options] [arguments...]
```

**Example:**

```bash theme={null}
./build/moca-sp recover.object --config ./config.toml -b bucket_name -o single_object_name
./build/moca-sp recover.object --config ./config.toml -b bucket_name -l object_name1//_object_name2//object_name3
```

#### Claim MCSP Income

To claim income, a storage provider can use the `settle` command to settle income in global virtual group families or global virtual groups. To find the global virtual group families or global virtual groups to settle, a storage provider can use `query.primary.sp.income` or `query.secondary.sp.income` of `moca-sp` commands.

##### To query the income of a primary sp

**Usage:**

```bash theme={null}
# query sp's income in global virtual group families
moca-sp query.primary.sp.income --config config.toml --sp.id ${sp_id}
```

An example of a response will look like:

```json theme={null}
querying primary sp income details for sp 1query timestamp 1698830787 2023-11-01 17:26:27 +0800 CSTquery results: [{"vgf_id":2,"stream_record":{"account":"primary_sp_virtual_payment_account_address_1","crud_timestamp":1698631653,"netflow_rate":"4643666191","static_balance":"1093710972008743","buffer_balance":"0","lock_balance":"0","frozen_netflow_rate":"0"},"income":"2018422795287337"},...]
```

> The unit of the unsettled income is aMoca. The first element in the query result array above means that sp 1 gets 2018422795287337 wei Moca in `vgf_id` 2.

##### To query the income of a secondary sp

```bash theme={null}
# query sp's income in global virtual groups
moca-sp query.secondary.sp.income --config config.toml --sp.id ${sp_id}
```

An example of a response will look like:

```json theme={null}
querying secondary sp income details for sp 1query timestamp 1698830440 2023-11-01 17:20:40 +0800 CSTquery results: [{"gvg_id":2531,"stream_record":{"account":"secondary_sp_virtual_payment_account_address_1","crud_timestamp":1695347375,"netflow_rate":"22256589564","static_balance":"917684637479280","buffer_balance":"0","lock_balance":"0","frozen_netflow_rate":"0"},"income":"13073138794535490"},...]
```

> The unit of the unsettled income is wei Moca. The first element in the query result array above means that sp 1 gets 13073138794535490 wei Moca in `gvg_id` 2531.

```bash theme={null}
# settle income in global virtual group family or global virtual groups
mocad tx virtualgroup settle [global-virtual-group-family-id] [global-virtual-group-ids] [flags]
```

**Example:**

```bash theme={null}
# query sp's income in global virtual group families
moca-sp query.primary.sp.income --config config.toml --sp.id 1

# query sp's income in global virtual groups
moca-sp query.secondary.sp.income --config config.toml --sp.id 2

# settle income in global virtual group family with id 100
mocad tx virtualgroup settle 100 0 [flags]

# settle income in global virtual groups with id 2 or 3 or 4
mocad tx virtualgroup settle 0 2,3,4 [flags]
```

## Exit MCSP Network

### How to exit Moca Chain network

When an MCSP decides to exit the Moca Chain network, there are three main steps to go through, involving both the exiting MCSP and other MCSPs in the network:

1. Declare the exit
2. Data recovery by successor MCSP(s)
3. Finalize the exit

#### Declare the exit

The exiting MCSP needs to initiate a `StorageProviderExit` transaction to Moca Chain, which will turn its status to `STATUS_GRACEFUL_EXITING`. To exit the network, you can use the following commands based on the desired network:

```
rpcAddr = "https://tm-rpc.testnet.mocachain.dev"
chainId = "moca_222888-1"
```

Command for storage provider to exit:

```bash theme={null}
moca-sp spExit [command options] [arguments...]
```

**Example:**

```bash theme={null}
./build/bin/moca-sp spExit --config ./config.toml
```

#### Data recovery

For MCSPs interested in becoming successors, you need to perform the following data recovery steps:

##### ReserveSwapIn

The prospective successor MCSP needs to determine the Global Virtual group (GVG) and Global Virtual Group Family (VGF) that the exiting MCSP has. This information can be obtained from Moca ChainScan or by using the provided CLI.

**Usage:**

```bash theme={null}
# List the GVG that the exit MCSP acts as a secondary MCSP
./moca-sp query-gvg-by-sp [command options] [arguments...]

# List the GVG Family that the exit SP acts as a primary SP
./moca-sp query-vgf-by-sp [command options] [arguments...]
```

**Example:**

```bash theme={null}
# List the GVG that the exit SP (id=1) acts as a secondary SP
./moca-sp query-gvg-by-sp --config ./config.toml -sp 1

# List the GVG Family that the exit SP (id=1) acts as a primary SP
./moca-sp query-vgf-by-sp --config ./config.toml -sp 1
```

Once the successor MCSP has obtained the necessary information, it needs to reserve the position in the exiting MCSP's GVG Family or GVG.

**Usage:**

```bash theme={null}
# Reserve the exit SP's position in a GVG family or GVG
./moca-sp swapIn [command options] [arguments...]
```

**Example:**

```bash theme={null}
# Reserve the exit SP's (id=1) position in GVG family (id=1)
./moca-sp swapIn --config ./config.toml -f 1 -sp 1

# Reserve the exit SP's (id=1) position in GVG (id=1)
./moca-sp swapIn --config ./config.toml --gid 1 -sp 1
```

##### Data Recovery

The data recovery process is triggered by the successor MCSP using the following commands:
**Usage:**

```bash theme={null}
./moca-sp recover-vgf [command options] [arguments...]
./moca-sp recover-gvg [command options] [arguments...]
```

**Example:**

```bash theme={null}
# To recover the exit SP's data in the VGF (id=1) as a primary SP:
./moca-sp recover-vgf --config /config/config.toml -f 1

# To recover the exit SP's data in the GVG (id=1) as a secondary SP:
./moca-sp swapIn --config ./config.toml --gid 1
```

Once the recovery job is triggered, it will run in the background in the MCSP Manager module. The progress can be queried using the following command:
**Usage:**

```bash theme={null}
./moca-sp query-recover-p [command options] [arguments...]
```

**Example:**

```bash theme={null}
# Query the GVG family (id=1) recovery progress
./moca-sp recover-vgf --config /config/config.toml -f 1

# Query the GVG (id=1) recovery progress
./moca-sp recover-vgf --config /config/config.toml --gid 1
```

##### CompleteSwapIn

Upon completion of the data recovery process and successful verification, the successor MCSP needs to send a `CompleteSwapIn` transaction to the Moca Chain. It will be automatically conducted before the recovery process concludes. This will finalize the recovery process and allow the successor MCSP to take over the position in the GVG Family or GVG.

> **Note:** It is crucial to note that under no circumstances should the `CompleteSwapIn` be triggered manually if the successor MCSP has not completed the data recovery process but acknowledges it. Doing so may result in data availability challenges and potential loss of funds.

#### Finalize the Exit

Once the successor MCSP has completed the data recovery process and taken over the position in the GVG Family or GVG, by checking the GVG statistic of the exiting MCSP, confirm that there are no more GVGs associated with it. Anyone in the Moca Chain network can send a `CompleteStorageProviderExit` transaction to the Moca Chain to finalize its exit from the network. Below shows the CLI triggered by the exiting MCSP itself.

**Usage:**

```bash theme={null}
./moca-sp completeSpExit [command options] [arguments...]
```

**Example:**

```bash theme={null}
./moca-sp completeSpExit --config /config/config.toml
```

## Deploy Piece Store

*Coming soon.*

## MCSP Config

### MCSP Config

This section gives you a complete config of MCSP. `./moca-sp config.dump` will generate a template `config.toml`.

#### App info

These fields are optional.

```toml theme={null}
# optional
Env = ''
# optional
AppID = ''
# optional
Server = []
# optional
GRPCAddress = ''
```

#### Database

To config `[SpDB]`, `[BsDB]`, you have to input the username, db password, db address, and db name in these fields.

#### PieceStore

To config `[PieceStore]` and `[PieceStore.Store]`, you can read the details in this doc.

#### Chain info

* `ChainID` of testnet is `moca_222888-1`.
* `ChainAddress` is the RPC endpoint of Testnet; you can find RPC info here.

#### SpAccount

These private keys are generated during wallet setup.

#### Endpoint

`[Endpoint]` specifies the URL of different services.

**For single-machine host (not recommended):**

```toml theme={null}
[Endpoint]
ApproverEndpoint = ''
ManagerEndpoint = ''
DownloaderEndpoint = ''
ReceiverEndpoint = ''
MetadataEndpoint = ''
UploaderEndpoint = ''
P2PEndpoint = ''
SignerEndpoint = ''
AuthenticatorEndpoint = ''
```

**For K8S cluster:**

```toml theme={null}
[Endpoint]
ApproverEndpoint = 'manager:9333'
ManagerEndpoint = 'manager:9333'
DownloaderEndpoint = 'downloader:9333'
ReceiverEndpoint = 'receiver:9333'
MetadataEndpoint = 'metadata:9333'
UploaderEndpoint = 'uploader:9333'
P2PEndpoint = 'p2p:9333'
SignerEndpoint = 'signer:9333'
AuthenticatorEndpoint = 'localhost:9333'
```

#### P2P

> **Note:** We don't use P2P service in Testnet, so users can ignore P2P items.

* `P2PPrivateKey` and `node_id` are generated by `./moca-sp p2p.create.key -n 1`.
* `P2PAntAddress` is your load balance address. If you don't have a load balance address, you should have a public IP and use it in `P2PAddress`. It consists of `ip:port`.
* `P2PBootstrap` can be left empty.

#### Gateway

```toml theme={null}
[Gateway]
DomainName = 'region.sp-name.com'
```

> The correct configuration should not include the protocol prefix `https://`.

#### BlockSyncer

Here is the `block_syncer` config. The configuration of `BsDBWriteAddress` can be the same as the `BSDB.Address` module here. To enhance performance, you can set up the write database address here and the corresponding read database address in `BSDB`.

```toml theme={null}
Modules = ['epoch','bucket','object','payment','group','permission','storage_provider','prefix_tree', 'virtual_group','sp_exit_events','object_id_map','general']
Workers = 50
BsDBWriteAddress = 'localhost:3306'
```

#### FundingPrivateKey

There is no need to write `FundingPrivateKey` in `config.toml`. It should be kept in a cold wallet for safety.

#### Rcmgr

ResourceManager manages resources within the MCSP system, tracking and accounting for usage across the stack, from internal components to applications. It also allows for resource usage to be limited based on user-configurable policies. The config schema is shown below:

```protobuf theme={null}
message GfSpLimit {
  int64 memory = 1;
  int32 tasks = 2;
  int32 tasks_high_priority = 3;
  int32 tasks_medium_priority = 4;
  int32 tasks_low_priority = 5;
  int32 fd = 6;
  int32 conns = 7;
  int32 conns_inbound = 8;
  int32 conns_outbound = 9;
}

message GfSpLimiter {
  GfSpLimit system = 1;
  GfSpLimit transient = 2;
  map<string, GfSpLimit> service_limit = 3;
}
```

#### Quota

Here is the quota config. The configuration of `MonthlyFreeQuota` defines the free quota for each month. It will be reduced when the charge quota is exhausted.

```toml theme={null}
[Quota]
MonthlyFreeQuota = 0
```

#### MCSP Probe

It contains two probes: `liveness` and `readiness` probe. If users want to check whether MCSP is healthy and ready, they can refer to the Kubernetes docs to learn related concepts. For detailed MCSP probe info, users can refer to the MCSP probe documentation.

### MCSP Testnet Recommended Config

*Coming soon.*


# How to run a validator node for Moca Chain
Source: https://docs.air3.com/technicals/mocachain/run-a-validator

Run a Moca Chain validator node — hardware requirements, staking, key management, CometBFT configuration, and steps to join the validator set.

# Running a Validator

<Warning>⚠️ This section may change without prior notice</Warning>
Critical information in this section may be subject to change as the network is in early stages.

<Info>
  🔓 The Moca Chain source code is publicly available on GitHub.
</Info>

## Validator Information

### Minimum System Requirements

| **Component** | **Recommended Specification** | **Minimum Specification** |
| - | - | - |
| Hardware | Desktop or laptop running recent versions of **Mac OS X** or **Linux** | Desktop or laptop running recent versions of **Mac OS X** or **Linux** |
| CPU | **16 cores** | **8 cores** |
| Memory (RAM) | **128 GB** | **64 GB** |
| Storage | **4 TB NVMe SSD** | **2 TB NVMe SSD** |
| Bandwidth | **5 MB/s+**  | **1 MB/s+**  |

Number of \$MOCA to be staked: Refer to the latest network parameters for current staking requirements.

Slashing details: Refer to the latest network parameters for current slashing conditions.

## Setting up Validator Node

### Install Fullnode

Follow the instructions [here to set up a full node](./run-a-node).

### Prepare validator, validator BLS, relayer, and challenger accounts

**Warning**

The current key generation and storage procedures are not very secure. It is highly recommended to implement a more robust method, particularly when dealing with keys like the validator operator key.

For enhanced security and best practices, the usage of the Cold Wallet and MPC Wallet is strongly encouraged.

```bash theme={null}
mocad keys add validator --keyring-backend test
mocad keys add validator_bls --keyring-backend test --algo eth_bls
mocad keys add validator_relayer --keyring-backend test
mocad keys add validator_challenger --keyring-backend test

```

**Tip**

Alternatively, if you choose a different **\$KEY\_HOME** location and you are not using the suggested default **\~/.mocad**, you may start the full node by using below script, where **\$KEY\_HOME** is your selected directory.

```bash theme={null}
mocad keys add validator --keyring-backend test --home ${KEY_HOME}
mocad keys add validator_bls --keyring-backend test --algo eth_bls --home ${KEY_HOME}
mocad keys add validator_relayer --keyring-backend test --home ${KEY_HOME}
mocad keys add validator_challenger --keyring-backend test --home ${KEY_HOME}

```

### Obtain validator, validator BLS, relayer, and challenger account addresses

**Note**

Ensure you choose the correct –keyring-backend and that –home is set correctly if you saved the files in a custom folder in step 2.

**Note:** For the `MsgCreateValidator` proposal, the delegator and validator addresses must be the same account.

```bash theme={null}
VALIDATOR_ADDR=$(mocad keys show validator -a --keyring-backend test)
DELEGATOR_ADDR=$VALIDATOR_ADDR
RELAYER_ADDR=$(mocad keys show validator_relayer -a --keyring-backend test)
CHALLENGER_ADDR=$(mocad keys show validator_challenger -a --keyring-backend test)
VALIDATOR_BLS=$(mocad keys show validator_bls --keyring-backend test --output json | jq -r '.pubkey_hex')
VALIDATOR_BLS_PROOF=$(mocad keys sign ${VALIDATOR_BLS} --keyring-backend test --from validator_bls)
VALIDATOR_NODE_PUB_KEY=$(cat ~/.mocad/config/priv_validator_key.json | jq -r '.pub_key.value')

```

**Warning**

The file **\~/.mocad/config/priv\_validator\_key.json** contains your validator's consensus key. This key is used to sign blocks. Keep it secure — if compromised, your validator can be slashed.

Ensure your validator account is funded with sufficient \$MOCA before proceeding.

### Authorize Governance Module to allow Delegation

Generic Authorization

```bash theme={null}
VALIDATOR_ADDR=$(mocad keys show validator -a --keyring-backend test)
DELEGATOR_ADDR=$VALIDATOR_ADDR
GOV_ADDR=0x7b5Fe22B5446f7C62Ea27B8BD71CeF94e03f3dF2
mocad tx authz grant ${GOV_ADDR} generic --msg-type=/cosmos.staking.v1beta1.MsgDelegate --keyring-backend test --chain-id "moca_222888-1" --from ${DELEGATOR_ADDR} --node "https://tm-rpc.testnet.mocachain.dev:443" -b sync --gas "200000000" --fees "100000000000000000000amoca" --yes
```

OR Limited Authorization

```bash theme={null}
VALIDATOR_ADDR=$(mocad keys show validator -a --keyring-backend test)
DELEGATOR_ADDR=$VALIDATOR_ADDR
GOV_ADDR=0x7b5Fe22B5446f7C62Ea27B8BD71CeF94e03f3dF2
mocad tx authz grant ${GOV_ADDR} delegate --allowed-validators=${VALIDATOR_ADDR} --spend-limit=10000000000000000000000amoca  --keyring-backend test --chain-id "moca_222888-1" --from ${DELEGATOR_ADDR} --node "https://tm-rpc.testnet.mocachain.dev:443" -b sync --gas "2000000" --fees "1000000000000000000amoca" --yes
```

### Submit a Create Validator Proposal

Replace the values in the following JSON and save it as **create\_validator\_proposal.json**:

**\$**: A custom human-readable name for this node.

**\$**: The consensus key generated in step 1 (stored in **\$/.mocad/config/priv\_validator\_key.json** by default).

**\$**: The operator address created in step 2.

**\$**: The delegator address created in step 2.

**\$**: The BLS key created in step 2.

**\$**: The BLS proof created in step2.

**\$**: The relayer address created in step 2.

**\$**: The challenger address created in step 2.

```json theme={null}
{
  "messages": [
    {
      "@type": "/cosmos.staking.v1beta1.MsgCreateValidator",
      "description": {
        "moniker": "${MONIKER_NAME}",
        "identity": "",
        "website": "https://${MONIKER_NAME}",
        "security_contact": "",
        "details": "${MONIKER_NAME} details"
      },
      "commission": {
        "rate": "0.070000000000000000",
        "max_rate": "1.000000000000000000",
        "max_change_rate": "0.010000000000000000"
      },
      "min_self_delegation": "1",
      "delegator_address": "${DELEGATOR_ADDR}",
      "validator_address": "${VALIDATOR_ADDR}",
      "pubkey": {
        "@type": "/cosmos.crypto.ed25519.PubKey",
        "key": "${VALIDATOR_NODE_PUB_KEY}"
      },
      "value": {
        "denom": "amoca",
        "amount": "10000000000000000000000"
      },
      "from": "0x7b5Fe22B5446f7C62Ea27B8BD71CeF94e03f3dF2",
      "relayer_address": "${RELAYER_ADDR}",
      "challenger_address": "${CHALLENGER_ADDR}",
      "bls_key": "${VALIDATOR_BLS}",
      "bls_proof": "${VALIDATOR_BLS_PROOF}"
    }
  ],
  "metadata": "",
  "title": "Create ${MONIKER_NAME} Validator",
  "summary": "create ${MONIKER_NAME} validator",
  "deposit": "10000000000000000000000amoca"
}
```

You can also use the gen\_validator\_proposal.sh script to create：

```bash theme={null}
# !/bin/bash

MONIKER_NAME="validator-lsl"
# create accounts
echo "Creating validator, validator BLS, relayer, and challenger accounts..."
mocad keys add validator --keyring-backend test
mocad keys add validator_bls --keyring-backend test --algo eth_bls
mocad keys add validator_relayer --keyring-backend test
mocad keys add validator_challenger --keyring-backend test
# get accounts and private key
echo "Obtaining addresses and keys..."
VALIDATOR_ADDR=$(mocad keys show validator -a --keyring-backend test)
DELEGATOR_ADDR=$VALIDATOR_ADDR
RELAYER_ADDR=$(mocad keys show validator_relayer -a --keyring-backend test)
CHALLENGER_ADDR=$(mocad keys show validator_challenger -a --keyring-backend test)
VALIDATOR_BLS=$(mocad keys show validator_bls --keyring-backend test --output json | jq -r '.pubkey_hex')
VALIDATOR_BLS_PROOF=$(mocad keys sign ${VALIDATOR_BLS} --keyring-backend test --from validator_bls)
VALIDATOR_NODE_PUB_KEY=$(cat ~/.mocad/config/priv_validator_key.json | jq -r '.pub_key.value')
# grant staking authz to governance module
echo "Granting staking authz to governance module..."
GOV_ADDR=0x7b5Fe22B5446f7C62Ea27B8BD71CeF94e03f3dF2
mocad tx authz grant ${GOV_ADDR} generic --msg-type=/cosmos.staking.v1beta1.MsgDelegate --keyring-backend test --chain-id "moca_222888-1" --from ${DELEGATOR_ADDR} --node "https://tm-rpc.testnet.mocachain.dev:443" -b sync --gas "200000000" --fees "100000000000000000000amoca" --yes
# generate the JSON file
echo "Generating create_validator_proposal.json..."
cat <<EOF > proposal.json
{
"messages": [
{
"@type": "/cosmos.staking.v1beta1.MsgCreateValidator",
"description": {
"moniker": "${MONIKER_NAME}",
"identity": "",
"website": "https://${MONIKER_NAME}",
"security_contact": "",
"details": "${MONIKER_NAME} details"
},
"commission": {
"rate": "0.070000000000000000",
"max_rate": "1.000000000000000000",
"max_change_rate": "0.010000000000000000"
},
"min_self_delegation": "1",
"delegator_address": "${DELEGATOR_ADDR}",
"validator_address": "${VALIDATOR_ADDR}",
"pubkey": {
"@type": "/cosmos.crypto.ed25519.PubKey",
"key": "${VALIDATOR_NODE_PUB_KEY}"
},
"value": {
"denom": "amoca",
"amount": "10000000000000000000000"
},
"from": "0x7b5Fe22B5446f7C62Ea27B8BD71CeF94e03f3dF2",
"relayer_address": "${RELAYER_ADDR}",
"challenger_address": "${CHALLENGER_ADDR}",
"bls_key": "${VALIDATOR_BLS}",
"bls_proof": "${VALIDATOR_BLS_PROOF}"
}
],
"metadata": "",
"title": "Create ${MONIKER_NAME} Validator",
"summary": "create ${MONIKER_NAME} validator",
"deposit": "10000000000000000000000amoca"
}
EOF
echo "proposal.json has been created."

```

Run the script

```bash theme={null}
bash gen_validator_proposal.sh

```

and you will see the output:

```bash theme={null}
VALIDATOR_ADDR: 0x400b809ec90B8666c671b7ceC82033Dd6186D8c8
DELEGATOR_ADDR: 0x400b809ec90B8666c671b7ceC82033Dd6186D8c8
RELAYER_ADDR: 0xf7B8eeC1E7eb13827a9738A39f965f06DdfE4A90
CHALLENGER_ADDR: 0x5cc8eC44a7Cc8F5BcdF6Eb9301D9632828C20651
VALIDATOR_BLS: 18726fbcace099dce4cee158410bdc94e1b19f6531dd5ccf5327dd5384ef3422037862be14e324d7b8e4175fa0c86d053974a320ee92681560aa947c310d63c827dd73092bf57da29b34f2e4844a55aee4f803f009efff1ce7edc797e16fcf31008f67eba9fabad94876d65d135458fa1c814562cf1da8e1574c68ad4cbda887
VALIDATOR_BLS_PROOF: 0e5361e641ecc43b30fa2d921d39e5793d6def5638a5e6badb08827867a9a396134f0000ca9e20eebc51e62ab58c99c8576c2f384f103a55cfc568c2e98dc375
VALIDATOR_NODE_PUB_KEY: uk+p1GR1/Iy5B9rkKRe6lmRta1bnkFTM3HLd+8wpZL4=

```

### Submit the governance proposal. Ensure the validator account has enough \$MOCA.

**Info**

If you are utilizing the Cold Wallet or MPC wallet, please proceed to next step

```bash theme={null}
VALIDATOR_ADDR=$(mocad keys show validator -a --keyring-backend test)
DELEGATOR_ADDR=$VALIDATOR_ADDR
mocad tx gov submit-proposal ./proposal.json --keyring-backend test --chain-id "moca_222888-1" --from ${DELEGATOR_ADDR} --node "https://tm-rpc.testnet.mocachain.dev:443" -b sync --gas "600000" --fees "100000000000000000000amoca" --yes

```

You can see the following output:

```bash theme={null}
code: 0
codespace: ""
data: 1A080000000000008A7A
events: []
gas_used: "0"
gas_wanted: "0"
height: "0"
info: ""
logs: []
raw_log: '[]'
timestamp: ""
tx: null
txhash: 94BFFAA9792A9C94BC1A925C433F5CA13CB1526C8E85D83D9D462ACF766E8475

```

Find the proposal ID:

```bash theme={null}
mocad q tx BB845EA77C5051A8885FCEB6FAF06E279305D9DE7B03DBA8915D1A1E2804B3AF --node "https://tm-rpc.testnet.mocachain.dev:443" --output json | jq '.logs[] | .events[] | select(.type == "submit_proposal") | .attributes[] | select(.key == "proposal_id") | .value | tonumber'

```

```bash theme={null}
3

```

Query proposal status

```bash theme={null}
curl -s https://api.testnet.mocachain.dev/cosmos/gov/v1/proposals/3 | jq

```

Output:

```bash theme={null}
{
"proposal": {
"id": "3",
"messages": [
{
"@type": "/cosmos.staking.v1beta1.MsgCreateValidator",
"description": {
"moniker": "validator-lsl",
"identity": "",
"website": "https://validator-lsl",
"security_contact": "",
"details": "validator-lsl details"
},
"commission": {
"rate": "0.070000000000000000",
"max_rate": "1.000000000000000000",
"max_change_rate": "0.010000000000000000"
},
"min_self_delegation": "1",
"delegator_address": "0x0E47f44E8e5aaaFFB2D93f8Ec003470C76a70f1a",
"validator_address": "0x0E47f44E8e5aaaFFB2D93f8Ec003470C76a70f1a",
"pubkey": {
"@type": "/cosmos.crypto.ed25519.PubKey",
"key": "NgpQL9w9C36mRn5TRuEooCs7WSnfeSWTawUhleiAzJQ="
},
"value": {
"denom": "amoca",
"amount": "10000000000000000000000"
},
"from": "0x7b5Fe22B5446f7C62Ea27B8BD71CeF94e03f3dF2",
"relayer_address": "0x2663170D78C7F2975abdd230Fa29Abf2E599dFf3",
"challenger_address": "0xc1E3825A64e3fBeeb0F0dE301B9A5cf6A0b93555",
"bls_key": "19788627475911af79040fb2cc06b3e2c55d294040aa2ea0cf82b0be34263fcd1546cadd9ef7cef43c0b8ace373b202f564d44f954ac1525a85694ea1cba8958093abea4bd8c042530d1028bd53030292983f3fe52a81ae262cdf23e056470a009d43f34369193f197c409533726cd62ce049a63ee80577718df85fec4874b31",
"bls_proof": "256d6283d5eb2e989f7dcb37f9c87db714a626af5bd40efc98d807c6c9acab3828f432091f3923b2b680e2c8479f60d896557586d916d5e06609eae5859912c0"
}
],
"status": "PROPOSAL_STATUS_VOTING_PERIOD",
"final_tally_result": {
"yes_count": "0",
"abstain_count": "0",
"no_count": "0",
"no_with_veto_count": "0"
},
"submit_time": "2024-11-18T10:13:17.955988297Z",
"deposit_end_time": "2024-11-19T10:13:17.955988297Z",
"total_deposit": [
{
"denom": "amoca",
"amount": "10000000000000000000000"
}
],
"voting_start_time": "2024-11-18T10:13:17.955988297Z",
"voting_end_time": "2024-11-19T10:13:17.955988297Z",
"metadata": "",
"title": "Create validator-lsl Validator",
"summary": "create validator-lsl validator",
"proposer": "0x73C4fCB7Dc03f30C2d8662d1ba146b387C3d063a",
"failed_reason": ""
}
}

```

You can find the proposal status is PROPOSAL\_STATUS\_VOTING\_PERIOD

### Wait for the voting until the Proposal is passed.

After submitting the proposal successfully, you must wait for the voting to be completed and the proposal to be approved. The voting period varies by network. Once it has passed and is successfully executed, you can verify that the node has become a validator.

Please announce your proposal ID to the existing validators, as they must vote in favor of it for it to pass.

**For existing validators** — run the following to vote on the proposal:

```bash theme={null}
mocad tx gov vote <PROPOSAL_ID> yes \
  --from validator \
  --keyring-backend test \
  --chain-id "<CHAIN_ID>" \
  --node "<NODE_URL>" \
  --gas 200000 \
  --gas-prices "10000000000amoca" \
  -y
```

**Warning**

Please ensure that the validator node is running before it is selected and if the validator is also responsible for running relayer and/or running challenger, then please ensure all these services are running as expected before selection.

### Query all validators

```bash theme={null}
mocad query staking validators --node "https://tm-rpc.testnet.mocachain.dev:443"

```

You will see the following output:

```yaml theme={null}
...
- bls_key: Hq27eaPq9K9bQWOO8KDrB9Q9HtxujkTO1Bmx9peUexwUs9mAZQ9wVXzSs9Lqg5EK1C+JE1owNcgzy1ZM76BAdhnsRWnXOyNnGzzBHyMpsBauWEEs0eMg47TADYx5UWzQGk+cNiohUL6k36xL/48s4uuXf1nDxWB/WHnMkbqlIxw=
challenger_address: 0x77C22b475bb76297BCEcad72aB4C9BAa9215dE57
commission:
commission_rates:
max_change_rate: "0.010000000000000000"
max_rate: "1.000000000000000000"
rate: "0.070000000000000000"
update_time: "2024-09-27T03:18:14.385577987Z"
consensus_pubkey:
"@type": /cosmos.crypto.ed25519.PubKey
key: bIV4oNvEblriuduP9dBK2fKVeEj4bAAgRdSY+JJz6oM=
delegator_shares: "10000000000000000000000.000000000000000000"
description:
details: my-validator details
identity: ""
moniker: my-validator
security_contact: ""
website: https://my-validator
jailed: false
min_self_delegation: "1"
operator_address: 0xD4d6B184E53a5625d7B842245E8E46842912F151
relayer_address: 0xa6bFd1EB8657bE66f7B9AcA7d27dB804214e2Af2
self_del_address: 0x0FD3375177f9B118142738Fd732D242465A18a70
status: BOND_STATUS_BONDED
tokens: "10000000000000000000000"
unbonding_height: "0"
unbonding_ids: []
unbonding_on_hold_ref_count: "0"
unbonding_time: "1970-01-01T00:00:00Z"
...

```

### One-step

For ease of execution, we have encapsulated the above process into a script.

### Prepare validator, validator BLS, relayer, and challenger accounts

```bash theme={null}
./scripts/create_validator_proposal.sh generate ~/.mocad

```

This will print the generated **validator\_address** (which is also used as the delegator address).

```bash theme={null}
===== generate ====
add keys...
show keys...
generated validator proposal file...
create_validator_proposal.json has been generated successfully at ../scripts/proposal.json.
VALIDATOR_ADDR: 0xD4d6B184E53a5625d7B842245E8E46842912F151

```

You need to ensure that the validator address is funded with sufficient Moca to be used for the subsequent proposal submission. Check the balance:

```bash theme={null}
bash scripts/create_validator_proposal.sh balance ~/.mocad

```

### Submit a Create Validator Proposal

```bash theme={null}
./scripts/create_validator_proposal.sh create ~/.mocad

```

### Wait for the Proposal to pass

Alternatively, you can also check the proposal status with the following command:

```bash theme={null}
bash scripts/create_validator_proposal.sh query_proposal ~/.mocad

```

```bash theme={null}
.....
"status": "PROPOSAL_STATUS_PASSED",
"final_tally_result": {
"yes_count": "40000000000000000000000000",
"abstain_count": "0",
"no_count": "0",
"no_with_veto_count": "0"
},
....

```


# Why Moca Chain?
Source: https://docs.air3.com/technicals/mocachain/why-mocachain

What differentiates Moca Chain — sub-second identity flows, consumer-scale capacity, EVM compatibility, MCSP storage, ZK privacy, and cross-chain proofs.

> *Moca Chain is a Layer 1 EVM-compatible blockchain purpose-built for decentralized identity, enabling chain-agnostic identity data issuance and verifications.*

## Sub-second identity flows

CometBFT consensus, 1-second blocks, instant finality. Age checks, KYC gates, and logins commit in a single block, so identity flows feel synchronous to the end user.

## Consumer-scale capacity

800 transactions per block and a 60,000,000 gas limit. Moca Chain handles ZK verifier contracts and batched credential issuance at full production volume, not just testnet workloads.

## Builder-ready

Moca Chain is fully EVM-compatible and supports transient storage (EIP-1153) along with other Shanghai opcodes. Existing Solidity contracts port over with little to no rewrite, and standard Ethereum tooling (Hardhat, Foundry, Remix, MetaMask) works as is. Integration moves from quarters to days.

## Decentralized credential storage (MCSP)

Moca Chain stores credentials in the Moca Chain Storage Provider network (MCSP), a decentralized storage layer with S3-compatible APIs:

* Data availability tracks chain uptime
* Storage is distributed across independent providers for resilience
* Confirm provider locations and regional commitments for your data residency requirements
* Issuers retain source records and signing keys, while encrypted credential payloads are stored with independent providers under holder-controlled decryption

## Privacy by construction

Privacy is built into the protocol:

* **Zero-knowledge proofs:** Verify claims without exposing data (e.g., prove you are over 18 without sharing your birthday). Moca Chain currently uses Circom circuits with Groth16.
* **Program-controlled disclosure:** Verification Programs define requested claims and optional ZK proofs. Users approve what they disclose.
* **Encrypted credential storage:** Raw source documents remain with the issuer. Encrypted credential payloads may be stored in DStorage, while users control decryption and disclosure.
* **zkTLS:** Enables secure onboarding from web sources while keeping information encrypted and user-authorized.

## Verify once, recognized everywhere

Proofs are relayed off Moca Chain via oracles and bridges. A single verification carries to every chain a partner ships into next, so users do not re-prove the same credential per ecosystem.

## Next steps

* [Technical Architecture](/technicals/mocachain/architecture)
* [Connect to Moca Chain](/technicals/mocachain/connect-to-mocachain)
* [Run a Node](/technicals/mocachain/run-a-node)