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

# JavaScript SDK

> SDK and CLI for verification gates, reusable proof, and agent permissions.

Verify a user or agent once. Check that result on your server. The SDK keeps headers and paths for `api.proofable.me` correct.

## Browser vs server

| Layer | Use |
| - | - |
| Browser | **Hosted Verify** or **`VerifyGate`** for interactive checks ([Hosted sign-in](https://docs.proofable.me/verification/hosted.md)) |
| Server | **`gateCheck`** for the final decision; advanced: **`verifyFromApp`**, access keys |

One check needs no gate. Send the person to Hosted Verify and read the returned proof ID. Reach for **`defineGate`** + **`gateCheck`** when the decision needs several checks, a price, or a schedule.

Keep **`npk_*`** and other secrets out of browser bundles. If the browser needs a call the SDK does not expose there, **proxy through your backend**. [API overview](https://docs.proofable.me/api/overview.md).

## Install

```bash theme={"system"}
npm install @proofable/sdk
```

Upgrading from an earlier package? [The migration guide](https://docs.proofable.me/migrate.md) has the rename map and the one-path upgrade.

## Hosted URL (browser default)

```javascript theme={"system"}
import { getHostedCheckoutUrl } from '@proofable/sdk';

window.location.assign(
  getHostedCheckoutUrl({
    verifiers: ['proof-of-human'],
    returnUrl: 'https://app.example.com/callback',
  }),
);
```

`getHostedCheckoutUrl` takes one recipe per URL: `intent: 'login'`, a published `gateId`, or direct `verifiers` / `preset`. [Gates in the SDK](https://docs.proofable.me/sdks/gates.md) lists the shared options.

For agents, `getHostedAgentCreateUrl` runs agent identity and owner approval in the right order. [Agents in the SDK](https://docs.proofable.me/sdks/agents.md).

## Client configuration

```javascript theme={"system"}
const client = new ProofableClient({
  // Optional: API base URL (default: https://api.proofable.me)
  apiUrl: 'https://api.proofable.me',
  // Optional: request timeout (ms)
  timeout: 30000,
});
```

Other options: `apiKey` (server key, sent as `Authorization: Bearer`), `appId`, `billingWallet`, `appLinkQHash`, `paymentSignature`, `extraHeaders`, `identityChainId` (the signing chain, Base by default; onchain anchoring stays a per-proof opt-in), and `enableLogging`. Keep `apiKey` and any secret server-side only.

## App attribution (`appId`)

`appId` is a public attribution ID for server and app flows such as `verifyFromApp`. Inline `gateCheck`, `gateCheck({ gateId })`, and published listing checkout work without it.

```javascript theme={"system"}
const client = new ProofableClient({
  apiUrl: 'https://api.proofable.me',
  appId: 'acme-web',
});
```

## Verification options

Pass these under `options` on `client.verify(...)`:

| Option | When to use |
| - | - |
| `privacyLevel: 'public' \| 'private'` | Control who can read the proof. Default `private` |
| `enableIpfs: true` | Pin proof data to IPFS (public proofs only) |
| `storeOriginalContent: true` | Keep the original content with the proof |
| `targetChains: [...]` | Anchor/publish to specific chains |
| `publishToHub: true` | Record the proof on the hub chain. Offchain by default. Does not change who can see the proof. |
| `publicDisplay: true` | List a public proof for discovery. Leave it off for an unlisted, link-only proof |
| `meta`, `verifierOptions` | App metadata and per-verifier options |

`client.verify()` always creates a new proof. Reuse is set by the `strategy` prop on [`VerifyGate`](../widgets/verifygate) (`reuse-or-create` default, `fresh`, `reuse`). [Verification patterns](https://docs.proofable.me/sdks/verifications.md) covers privacy and widget options.

## Optional: `client.verify()` (signs in the browser)

Use only when you intentionally keep signing in **your** page (wallet extension or injected provider):

```javascript theme={"system"}
import { ProofableClient } from '@proofable/sdk';

const client = new ProofableClient({ apiUrl: 'https://api.proofable.me' });
const provider = window.ethereum; // EVM injected provider

const res = await client.verify({
  verifier: 'ownership-basic',
  content: 'Hello Proofable',
  wallet: provider,
});

const qHash = res.qHash;
const record = await client.getProof(qHash);
```

## Advanced: manual signing (full control)

When you assemble `verifierIds` / `data` yourself, then sign the standardized string. The example below is EVM. For non-EVM, pass the provider explicitly and include `chain` as a CAIP-2 value. See [CAIP-380 Portable Proof](https://docs.proofable.me/learn/standards/caip-380.md).

```javascript theme={"system"}
import { ProofableClient, standardizeVerificationRequest, signMessage } from '@proofable/sdk';

const provider = window.ethereum; // EVM injected provider
const client = new ProofableClient({ apiUrl: 'https://api.proofable.me' });
const [walletAddress] = await provider.request({ method: 'eth_requestAccounts' });
const signedTimestamp = Date.now();
const body = {
  verifierIds: ['ownership-basic'],
  data: {
    owner: walletAddress,
    content: 'Hello Proofable',
    reference: { type: 'url', id: 'https://example.com' }
  },
  walletAddress,
  signedTimestamp,
};

const standardized = await standardizeVerificationRequest(body, {
  apiUrl: 'https://api.proofable.me',
});

const signature = await signMessage({
  provider,
  walletAddress,
  message: standardized.signerString
});

const res = await client.verify({
  ...body,
  signature,
  options: { privacyLevel: 'private' }
});
```

## Link a wallet with Hosted Verify

For typical UX, use Hosted Verify so wallet selection and secondary signing stay on Proofable. Direct mode is for integrations that already control the secondary wallet and provider.

```javascript theme={"system"}
const walletLinkData = await client.createWalletLinkData({
  primaryWalletAddress: '0x0000000000000000000000000000000000000001',
  secondaryWalletAddress: '0x0000000000000000000000000000000000000002',
  wallet: window.ethereum, // EVM provider; pass explicit provider + chain for non-EVM
  relationshipType: 'linked',
  label: 'my-wallet'
});

const res = await client.verify({
  verifier: 'wallet-link',
  data: walletLinkData
});
```

## Gate checks from your servers

```javascript theme={"system"}
import { defineGate } from '@proofable/sdk';

const gate = defineGate([{ verifierId: 'proof-of-human' }]);
const result = await client.gateCheck({
  gate,
  subject: { accountId: user.accountAddress },
});

if (!result.satisfied) {
  throw new Error('Access denied');
}
```

> [!WARNING]
>
> `gateCheck` uses public and unlisted proofs by default. Private proofs count when that user is signed in. For strict live checks, create a fresh proof and wait for `verified` status.

`defineGate()` normalizes requirements locally and makes no request. `result.proofs` lists matching proof references and `result.missing` lists checks that still need verification. Publish a listing with a `gateId` only when you need managed checkout and fulfillment. `gateCheck` versus `checkGate`, private-proof checks, and checkout calls are in [Gates in the SDK](https://docs.proofable.me/sdks/gates.md).

## Polling

`pollProofStatus()` retries transient errors and backs off on `429`.

## Advanced: private proof operations

```javascript theme={"system"}
// EVM examples. For non-EVM, pass an explicit wallet/provider and CAIP-2 chain options.

// Private proof by qHash
const privateData = await client.getPrivateProof(qHash, window.ethereum);

// Private proofs by wallet/DID (requires owner signature)
const privateProofs = await client.getPrivateProofsByWallet(
  'YOUR_WALLET_OR_DID',
  { limit: 50, offset: 0 },
  window.ethereum
);

// Revoke your proof
await client.revokeOwnProof(qHash, window.ethereum);
```

## Catalog and health

List the live verifier ids or fetch the full catalog with metadata and access levels.

```javascript theme={"system"}
const ids = await client.getVerifiers();        // ['ownership-basic', 'token-holding', ...]
const catalog = await client.getVerifierCatalog(); // full metadata + access levels
const ok = await client.isHealthy();             // true / false
```

## Public proofs by wallet

```javascript theme={"system"}
const proofs = await client.getProofsByWallet('0x...', { limit: 50 });
```

## React widgets

[Widgets overview](https://docs.proofable.me/widgets/overview.md).

```javascript theme={"system"}
import { VerifyGate, ProofBadge } from '@proofable/sdk/widgets';
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.