@phorcefield/liquidity-sdk

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

Install

npm install @phorcefield/liquidity-sdk

Quick Start

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:

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