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

# Quickstart — Up and Running with Vouch SDK in 5 Minutes

> Install vouch-sdk, provision an API key, and make your first identity verification and fraud assessment call in under five minutes.

This guide walks you through everything you need to make your first Vouch API calls — from installing the package to handling a real fraud assessment response. By the end you will have a working integration you can build on.

<Steps>
  <Step title="Install the SDK">
    Add `vouch-sdk` to your project using your preferred package manager.

    <CodeGroup>
      ```bash npm theme={null}
      npm install vouch-sdk
      ```

      ```bash pnpm theme={null}
      pnpm add vouch-sdk
      ```

      ```bash yarn theme={null}
      yarn add vouch-sdk
      ```
    </CodeGroup>

    The package targets ESM and ships with full TypeScript type definitions — no `@types/vouch-sdk` package required.
  </Step>

  <Step title="Get your API key">
    Every request to Vouch requires an API key. To get one:

    1. Sign up for a Vouch developer account at the [Vouch dashboard](https://vouch-fmql.onrender.com).
    2. Navigate to **Settings → API Keys** and click **Generate new key**.
    3. Copy the key — it will only be shown once.

    Store the key as an environment variable so it never appears in your source code.

    ```bash .env theme={null}
    VOUCH_API_KEY=vouch_live_8f9a2b3c...
    ```

    <Warning>
      Never hard-code your API key in your source files or commit it to version control. If you are building a client-side application, proxy all Vouch calls through a server-side function so the key stays out of the browser bundle.
    </Warning>
  </Step>

  <Step title="Initialize the SDK">
    Import the default export from `vouch-sdk` and create a client instance, passing your API key from the environment.

    ```typescript theme={null}
    import Vouch from 'vouch-sdk';

    const vouch = new Vouch(process.env.VOUCH_API_KEY!);
    ```

    The constructor accepts the API key as its first argument and an optional `options` object as its second. The SDK stores the key and attaches it as the `x-api-key` header on every outbound request — you never need to manage authentication manually.

    ```typescript theme={null}
    // With optional URL overrides
    const vouch = new Vouch(process.env.VOUCH_API_KEY!, {
      apiUrl: 'https://staging.example.com/v1',       // override API base URL
      verifyUrl: 'https://your-custom-modal.example.com', // override KYC modal URL
    });
    ```

    <Tip>
      The SDK reads the `VOUCH_API_URL` environment variable automatically at start-up. Set it to override the default base URL (`https://vouch-fmql.onrender.com/v1`) without changing any code — for example when pointing at a local proxy or a staging environment: `VOUCH_API_URL=https://staging.example.com/v1`. You can also pass `options.apiUrl` to the constructor for the same effect.
    </Tip>
  </Step>

  <Step title="Run your first identity check">
    Call `vouch.identity.verify` with the ID your platform uses to identify the user. Vouch opens a guided KYC modal that walks the user through document capture and liveness detection — you just handle the result.

    ```typescript theme={null}
    async function verifyUser(userId: string) {
      try {
        const result = await vouch.identity.verify(userId);

        if (result.status === 'verified') {
          console.log('User verified:', result.data.id);
          // Grant access, update your database, etc.
        } else {
          console.warn('Verification incomplete:', result.status);
        }
      } catch (error) {
        console.error('Identity check failed:', error);
      }
    }

    verifyUser('user-12345');
    ```

    The `verify` method returns a promise that resolves once the user completes (or exits) the KYC flow. The `result.status` field reflects the outcome: `verified`, `pending`, or `failed`.
  </Step>

  <Step title="Assess fraud risk">
    Before processing a transaction, pass the relevant signals to `vouch.fraud.assess`. The AI engine returns a `flag` of `GREEN`, `AMBER`, or `RED` that you can use to gate your business logic.

    ```typescript theme={null}
    async function checkFraudRisk(platformUserId: string, transactionAmount: number) {
      const assessment = await vouch.fraud.assess({
        platformUserId,
        transactionAmount,
      });

      switch (assessment.flag) {
        case 'GREEN':
          // Proceed with the transaction
          console.log('Low risk — proceeding:', assessment.score);
          break;

        case 'AMBER':
          // Require additional verification before proceeding
          console.warn('Elevated risk — requesting step-up auth:', assessment.triggeredSignals);
          break;

        case 'RED':
          // Block the transaction and alert your trust & safety team
          console.error('High risk — transaction blocked:', assessment.triggeredSignals);
          break;
      }
    }

    checkFraudRisk('user-12345', 2500);
    ```

    The `assessment.triggeredSignals` array lists the specific factors that influenced the score, so you can surface actionable context in your internal tooling or user-facing messages.
  </Step>
</Steps>

## Next steps

Now that your integration is working, explore the rest of the SDK.

<CardGroup cols={3}>
  <Card title="Identity" icon="id-card" href="/docs/sdk/identity">
    Learn about direct document uploads and how to retrieve verification results asynchronously.
  </Card>

  <Card title="Fraud Detection" icon="shield-halved" href="/docs/sdk/fraud">
    See the full list of signals you can pass to `fraud.assess` and how to tune thresholds.
  </Card>

  <Card title="Escrow" icon="vault" href="/docs/sdk/escrow">
    Create milestone-based escrow accounts and manage the full release lifecycle.
  </Card>
</CardGroup>