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

# TypeScript SDK

> Core TypeScript client for the Cred Protocol evaluation API

## Installation

```bash theme={null}
npm install @cred-protocol/sdk
```

## Quick Start

```typescript theme={null}
import { CredClient } from '@cred-protocol/sdk'

const cred = new CredClient({ apiKey: process.env.CRED_API_KEY })

const result = await cred.evaluate({
  walletAddress: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045',
  policy: 'standard',
})

console.log(result.trustScore)  // 75
console.log(result.trustTier)   // "verified"
console.log(result.allPassed)   // true
```

## Configuration

```typescript theme={null}
const cred = new CredClient({
  apiKey: 'cred_sk_...',       // Required
  baseUrl: 'https://...',      // Optional, defaults to production
})
```

## Evaluate Options

### Using a Policy Template

The simplest way to evaluate — pick a template that matches your use case:

```typescript theme={null}
const result = await cred.evaluate({
  walletAddress: '0x...',
  policy: 'standard',       // "basic", "standard", "strict", "financial", "reputation", "quick"
})
```

### Using Custom Gates

For full control, specify individual gates:

```typescript theme={null}
const result = await cred.evaluate({
  walletAddress: '0x...',
  gates: ['human', 'verified', 'established'],
  operator: 'WEIGHTED',
  weights: { human: 0.4, verified: 0.35, established: 0.25 },
  compositeThreshold: 60,
})
```

### With Dynamic Pricing

Compute trust-based pricing for your API:

```typescript theme={null}
const result = await cred.evaluate({
  walletAddress: '0x...',
  policy: 'reputation',
  includePricing: true,
  basePriceUsdc: 0.01,       // Your full price
})

console.log(result.priceMultiplier)    // 0.25 (verified tier)
console.log(result.suggestedPriceUsdc) // 0.0025
```

### With Reputation Data

```typescript theme={null}
const result = await cred.evaluate({
  walletAddress: '0x...',
  policy: 'standard',
  includeReputation: true,    // Enabled by default
})

if (result.reputation) {
  console.log(result.reputation.settlementRate)    // 0.95
  console.log(result.reputation.totalEvaluations)  // 47
  console.log(result.reputation.riskFlags)          // []
}
```

## Response Types

### TrustResult

The `evaluate()` method returns a `TrustResult`:

| Field                | Type                       | Description                                              |
| -------------------- | -------------------------- | -------------------------------------------------------- |
| `walletAddress`      | `string`                   | The evaluated wallet                                     |
| `trustScore`         | `number`                   | 0–100 composite score                                    |
| `trustTier`          | `TrustTier`                | `trusted`, `verified`, `limited`, `untrusted`, `blocked` |
| `confidence`         | `number`                   | 0.0–1.0 data confidence                                  |
| `allPassed`          | `boolean`                  | Whether all gates passed                                 |
| `gateResults`        | `GateScoreBreakdown[]`     | Per-gate breakdown                                       |
| `priceMultiplier`    | `number \| null`           | Dynamic pricing multiplier                               |
| `suggestedPriceUsdc` | `number \| null`           | Computed price                                           |
| `reputation`         | `WalletReputation \| null` | Behavioral history                                       |
| `cached`             | `boolean`                  | Whether this was a cache hit                             |
| `requestId`          | `string`                   | Unique request ID for debugging                          |
| `challenge`          | `object \| null`           | 402 challenge body (if gates failed)                     |
| `raw`                | `EvaluationResponse`       | Full API response                                        |

### GateScoreBreakdown

| Field      | Type             | Description                       |
| ---------- | ---------------- | --------------------------------- |
| `gateId`   | `string`         | Gate identifier (e.g., `"human"`) |
| `gateName` | `string`         | Human-readable name               |
| `passed`   | `boolean`        | Whether this gate passed          |
| `score`    | `number \| null` | 0–100 gate score                  |
| `provider` | `string`         | `"cred"` or third-party name      |

## Error Handling

```typescript theme={null}
import { CredClient, CredAPIError } from '@cred-protocol/sdk'

try {
  const result = await cred.evaluate({ walletAddress: '0x...', policy: 'standard' })
} catch (err) {
  if (err instanceof CredAPIError) {
    console.log(err.status) // 401, 429, etc.
    console.log(err.body)   // Error details
  }
}
```

| Status | Meaning                                        |
| ------ | ---------------------------------------------- |
| `400`  | Bad request — unknown policy or missing fields |
| `401`  | Invalid or missing API key                     |
| `429`  | Rate limit exceeded                            |
| `502`  | Upstream gate provider error                   |

## Framework Middleware

The core SDK is used by all framework middleware packages. If you're using Hono, Express, Next.js, or FastAPI, see the dedicated middleware guides — they handle wallet extraction, 402 challenges, and trust headers automatically.

<CardGroup cols={2}>
  <Card title="Hono" href="/sdks/hono">Drop-in Hono middleware</Card>
  <Card title="Express" href="/sdks/express">Express middleware</Card>
  <Card title="Next.js" href="/sdks/nextjs">Next.js edge middleware</Card>
  <Card title="Python" href="/sdks/python">Python + FastAPI</Card>
</CardGroup>