> ## Documentation Index
> Fetch the complete documentation index at: https://docs.starkfi.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting started

> Integrate StarkFi KYC — email OTP or wallet signature, Didit sessions, and status checks.

<Info>
  Treat StarkFi **KYC as a managed service**: we run verification sessions and decisions on **Didit**, a leading global provider for identity and compliance. You do not need a separate contract, certification path, or second vendor integration for end users who onboard through StarkFi.
</Info>

<Warning>
  The `kyc` product must be enabled on your deployment. Check [`GET /config/products`](/products) with your API key, or contact your account manager.
</Warning>

## Two onboarding paths

You can verify identity before opening a Didit session using **email** or **wallet**:

| Path       | Best for                  | Steps                                              |
| ---------- | ------------------------- | -------------------------------------------------- |
| **Email**  | Web apps with email login | prepare → send OTP → verify OTP → create session   |
| **Wallet** | Crypto-native apps        | wallet challenge → prepare-wallet → create session |

Both paths converge at **create session** and **get status**.

## Email flow

<Steps>
  <Step title="How StarkFi KYC works (Didit)">
    Identity verification is powered by **Didit**, with strong coverage for document checks, **liveness**, **screening**, and fraud signals. Instead of wiring your product directly to Didit dashboards, API keys, and workflows, **StarkFi exposes a single API** for starting sessions, tracking progress, and receiving outcomes.
  </Step>

  <Step title="Shared verification across StarkFi">
    When someone has **already completed verification elsewhere on StarkFi**, that identity can be **recognized across the network**. You are not charged again for a full verification cycle for users who are already approved in the ecosystem.

    <Note>
      Exact reuse rules and commercial pricing depend on your StarkFi agreement. Contact **[support@starkfi.io](mailto:support@starkfi.io)** or your account manager for details.
    </Note>
  </Step>

  <Step title="API sequence (email)">
    ```shellscript theme={null}
    POST /kyc/prepare
    POST /security/email/send-otp
    POST /security/email/verify-otp
    POST /kyc/create/verify_public_kyc
    GET  /kyc/status?email=
    ```

    | Step | Method and path                      | Purpose                                            |
    | ---- | ------------------------------------ | -------------------------------------------------- |
    | 1    | `POST /kyc/prepare`                  | Register the user's email for KYC                  |
    | 2a   | `POST /security/email/send-otp`      | Send the email verification code                   |
    | 2b   | `POST /security/email/verify-otp`    | Confirm the code                                   |
    | 3    | `POST /kyc/create/verify_public_kyc` | Create or resume the Didit session                 |
    | 4    | `GET /kyc/status?email=`             | Read approval state, session URL, and risk signals |

    <Note>
      Use the **same email address** in every step. We recommend **lowercase** addresses.
    </Note>
  </Step>
</Steps>

## Wallet flow

<Steps>
  <Step title="API sequence (wallet)">
    ```shellscript theme={null}
    POST /security/wallet/challenge
    POST /kyc/prepare-wallet
    POST /kyc/create/verify_public_kyc
    GET  /kyc/status?wallet=
    ```

    | Step | Method and path                      | Purpose                                         |
    | ---- | ------------------------------------ | ----------------------------------------------- |
    | 1    | `POST /security/wallet/challenge`    | Get a signable message (expires in 10 min)      |
    | 2    | `POST /kyc/prepare-wallet`           | Prove ownership with `message` + `signed_bytes` |
    | 3    | `POST /kyc/create/verify_public_kyc` | Body: `{ "wallet": "..." }`                     |
    | 4    | `GET /kyc/status?wallet=`            | Poll until approved or declined                 |
  </Step>
</Steps>

See [Wallet challenge](/wallet-challenge) and [Prepare KYC (wallet)](/prepare-wallet) for request bodies and error codes.

## Verify quota

KYC session creation consumes your integration's monthly verify quota. When quota is exceeded, prepare and session endpoints return **429** with status `verify_quota_exceeded`. Contact StarkFi to increase your limit or wait for the 30-day renewal window.

## StarkPay and KYC/KYB

KYC/KYB rules depend on the payment context:

| Context                                   | KYC/KYB                                                                                         |
| ----------------------------------------- | ----------------------------------------------------------------------------------------------- |
| **Checkout (order)**                      | Not required — payments linked to an order via `order_code` or `executor_id: order_transaction` |
| **Financial transaction** (fiat methods)  | Required when you send `payer_email` or `payer_wallet`                                          |
| **Financial transaction** (`crypto` only) | Not required — 100% on-chain crypto never triggers KYC/KYB                                      |

See [StarkPay overview](/starkpay) for the full checkout vs transaction distinction.

***

## Prerequisites

* A valid end-user email or wallet you control for testing.
* A way to open **HTTPS** (browser or in-app web view) when StarkFi returns a hosted Didit URL.
* For email flow: outbound email delivery for OTP codes enabled for your environment.

***

## Common issues

| What you see                | What to check                                                         |
| --------------------------- | --------------------------------------------------------------------- |
| `403 identity_not_verified` | Complete email OTP or wallet prepare before starting the KYC session. |
| `403 user_not_prepared`     | Call prepare (email or wallet) before create session.                 |
| `404 user_not_found` on OTP | Call `POST /kyc/prepare` first for that email.                        |
| `404 method_not_found`      | Use the path segment **`verify_public_kyc`** exactly as shown.        |
| `403 product_disabled`      | KYC product not enabled — see [Products](/products).                  |
| `429 verify_quota_exceeded` | Monthly KYC session quota exhausted.                                  |

***

## Related

* [Prepare KYC (email)](/prepare)
* [Prepare KYC (wallet)](/prepare-wallet)
* [Create KYC session](/create-session-1)
* [Get KYC status](/get-status)