npm package: @phorcefield/liquidity-sdk
Description: Client SDK for the Phorcefield Liquidity Router
Author: Phorcefield Team
Latest version: 1.0.0

# @phorcefield/liquidity-sdk

Client SDK for the Phorcefield Liquidity Router — swap USDC to SUI with multi-chain routing support.

## Install

```bash
npm install @phorcefield/liquidity-sdk
```

## Quick Start

```typescript
import { LiquidityClient } from '@phorcefield/liquidity-sdk';

const client = new LiquidityClient({
  baseUrl: 'https://router.phorcefield.com',
  apiKey: 'your-api-key',
});

// Get a USDC → SUI quote
const quote = await client.getQuote({ fromAmount: '10000000' }); // 10 USDC (6 decimals)

// Create an intent from the quote
const { intent, negotiation } = await client.createIntent({
  quoteId: quote.id,
  userSuiAddress: '0xYOUR_SUI_ADDRESS',
});

// The negotiation contains the payment request — submit the USDC payment on-chain,
// then poll for completion:
const completed = await client.waitForCompletion(intent.id, {
  onStatusChange: (status) => console.log('Status:', status),
});

console.log('Received SUI:', completed.receipt?.settlementAmount);
```

## Multi-Chain Routing

Route USDC from Solana, Base, or Ethereum to SUI in one call:

```typescript
import { LiquidityClient, Chain } from '@phorcefield/liquidity-sdk';

const client = new LiquidityClient({
  baseUrl: 'https://router.phorcefield.com',
  apiKey: 'your-api-key',
});

// Get optimal routes from multi-chain balances
const routes = await client.getRoutes({
  balances: [
    { chain: Chain.SUI, amount: '5000000' },
    { chain: Chain.SOLANA, amount: '20000000' },
  ],
  userSuiAddress: '0xYOUR_SUI_ADDRESS',
});

console.log('Best route:', routes.bestRouteId);
console.log('Routes:', routes.routes);

// Or use executeRoute() to handle the full flow automatically:
const { route, intent } = await client.executeRoute(
  [
    { chain: Chain.SOLANA, amount: '20000000' },
  ],
  '0xYOUR_SUI_ADDRESS',
);
```

## API Reference

### `new LiquidityClient(config)`

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `baseUrl` | `string` | — | Router API URL |
| `apiKey` | `string?` | — | API key for authentication |
| `fetch` | `typeof fetch?` | `globalThis.fetch` | Custom fetch (React Native, testing) |
| `timeoutMs` | `number?` | `15000` | Request timeout in ms |
| `on402` | `(negotiation) => boolean` | — | Callback for 402 Payment Required |

### Methods

| Method | Description |
|--------|-------------|
| `getQuote(params)` | Get a USDC → SUI swap quote |
| `createIntent(params, idempotencyKey?)` | Create a swap intent from a quote |
| `getIntent(id)` | Get intent status by ID |
| `cancelIntent(id)` | Cancel an unpaid intent |
| `waitForCompletion(id, opts?)` | Poll until intent reaches terminal state |
| `getRoutes(params)` | Get ranked multi-chain routes |
| `createCrossChainIntent(params, idempotencyKey?)` | Create intent from a cross-chain route |
| `executeRoute(balances, address, opts?)` | Full flow: route → intent → wait |

### Enums

- `IntentStatus` — `NEW`, `AWAITING_PAYMENT`, `PAID_CONFIRMED`, `BRIDGING`, `SWAPPING`, `SETTLING`, `COMPLETED`, `FAILED`, `EXPIRED`, `CANCELED`
- `Chain` — `SUI`, `SOLANA`, `BASE`, `ETHEREUM`
- `ErrorCode` — Structured error codes for all failure modes

### Error Classes

- `LiquidityApiError` — API error with `statusCode`, `code`, and `details`
- `LiquidityTimeoutError` — Request timeout
- `WaitTimeoutError` — Polling timeout with `intentId` and `lastStatus`

## License

MIT