> For the complete documentation index, see [llms.txt](https://docs.yield.fi/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.yield.fi/earn-with-yieldfi/integration-sdk/getting-started/configuration.md).

# Configuration

The YieldFi SDK can be configured with various options to customize its behavior. This guide covers all available configuration options.

### Basic Configuration

The minimum required configuration is the `gatewayUrl`:

```typescript
import { YieldFiSDK } from "yieldfi-sdk";

const sdk = await YieldFiSDK.create({
  gatewayUrl: "https://gw.yield.fi",
});
```

### Configuration Options

#### `gatewayUrl` (Required)

The base URL of the YieldFi gateway service.

```typescript
const sdk = await YieldFiSDK.create({
  gatewayUrl: "https://gw.yield.fi", // Production
  // gatewayUrl: "https://gw-staging.yield.fi", // Staging
});
```

#### `partnerId` (Optional)

Partner identifier for tracking and analytics. Used for partner transaction attribution.

```typescript
const sdk = await YieldFiSDK.create({
  gatewayUrl: "https://gw.yield.fi",
  partnerId: "my-partner-id",
});
```

#### `timeout` (Optional)

Request timeout in milliseconds. Default: `60000` (60 seconds).

```typescript
const sdk = await YieldFiSDK.create({
  gatewayUrl: "https://gw.yield.fi",
  timeout: 30000, // 30 seconds
});
```

#### `retryAttempts` (Optional)

Number of retry attempts for failed requests. Default: `3`.

```typescript
const sdk = await YieldFiSDK.create({
  gatewayUrl: "https://gw.yield.fi",
  retryAttempts: 5, // Retry up to 5 times
});
```

#### `retryDelay` (Optional)

Delay between retry attempts in milliseconds. Default: `1000` (1 second).

```typescript
const sdk = await YieldFiSDK.create({
  gatewayUrl: "https://gw.yield.fi",
  retryDelay: 2000, // Wait 2 seconds between retries
});
```

#### `debug` (Optional)

Enable debug logging. Default: `false`.

```typescript
const sdk = await YieldFiSDK.create({
  gatewayUrl: "https://gw.yield.fi",
  debug: true, // Enable debug logs
});
```

#### `environment` (Optional)

Environment identifier. Options: `'development'`, `'production'`, or `'test'`. Default: `'production'`.

```typescript
const sdk = await YieldFiSDK.create({
  gatewayUrl: "https://gw.yield.fi",
  environment: "development", // or "production" or "test"
});
```

### Complete Configuration Example

Here's an example with all configuration options:

```typescript
const sdk = await YieldFiSDK.create({
  gatewayUrl: "https://gw.yield.fi",
  partnerId: "my-partner-id",
  timeout: 30000,
  retryAttempts: 3,
  retryDelay: 1000,
  debug: process.env.NODE_ENV === "development",
  environment: process.env.NODE_ENV === "production" ? "production" : "development",
});
```

### Environment-Based Configuration

A common pattern is to configure the SDK based on your environment:

```typescript
const getSDKConfig = () => {
  const isDevelopment = process.env.NODE_ENV === "development";
  const isProduction = process.env.NODE_ENV === "production";

  return {
    gatewayUrl: isDevelopment
      ? "http://localhost:3000"
      : isProduction
      ? "https://gw.yield.fi"
      : "https://gw-staging.yield.fi",
    partnerId: process.env.REACT_APP_PARTNER_ID,
    timeout: 60000,
    retryAttempts: 3,
    retryDelay: 1000,
    debug: isDevelopment,
    environment: isProduction ? "production" : "development",
  };
};

const sdk = await YieldFiSDK.create(getSDKConfig());
```

### Using the Factory Function

Alternatively, you can use the factory function:

```typescript
import { createYieldFiSDK } from "yieldfi-sdk";

const sdk = await createYieldFiSDK({
  gatewayUrl: "https://gw.yield.fi",
  partnerId: "my-partner-id",
});
```

### Configuration Schema

The SDK uses Zod for configuration validation. Invalid configurations will throw a `ConfigurationError`:

```typescript
import { ConfigurationError } from "yieldfi-sdk";

try {
  const sdk = await YieldFiSDK.create({
    gatewayUrl: "", // Invalid: empty URL
  });
} catch (error) {
  if (error instanceof ConfigurationError) {
    console.error("Invalid configuration:", error.message);
    console.error("Details:", error.details);
  }
}
```

### Next Steps

* Authentication Guide - Learn about authentication flows
* API Reference - Explore available APIs