Conduitdocs

API surface

SDK Reference

Full reference for @conduit/sdk. Every method, every parameter, every return type. Types are derived directly from packages/sdk/src/types.ts.

ConduitClient

Main entry point. All payment operations go through this class.

Constructor

new ConduitClient(config: ConduitClientConfig)
interface ConduitClientConfig {
  // Browser wallet signer (ethers Signer or viem WalletClient).
  // Required for browser flows. Mutually exclusive with privateKey.
  signer?: SignerLike;

  // Server private key. Mutually exclusive with signer.
  // Required for server-side flows.
  privateKey?: string;

  // Circle App Kit Key — required for cross-currency payments.
  // Get one at console.circle.com → Keys → Kit Key
  kitKey?: string;

  // "arc-testnet" in v1
  network?: "arc-testnet";

  // Override the app URL for link generation
  appUrl?: string;
}

Static factory: fromBrowserProvider()

ConduitClient.fromBrowserProvider(
  provider: ethers.BrowserProvider,
  kitKey: string,
  appUrl?: string
): ConduitClient

Create a client from an EIP-1193 browser wallet (wagmi, MetaMask, etc.). Wraps the provider so wallet popups work correctly.

pay()

conduit.pay(options: PayOptions): Promise<PaymentReceipt>
interface PayOptions {
  // Recipient wallet address
  recipient: Address;           // "0x..."

  // Amount to deliver to recipient (6-decimal bigint)
  amount: bigint;

  // Currency the recipient should receive
  currency: Currency;           // "USDC" | "EURC"

  // Currency the payer holds (defaults to recipient currency)
  // Set to trigger a cross-currency swap
  payerToken?: Currency;
}

Same-currency (e.g. USDC → USDC): single on-chain transaction via ConduitRouter.execute().

Cross-currency (e.g. USDC → EURC): Circle StableFX swap → then ConduitRouter.execute(). Requires kitKey.

createLink()

conduit.createLink(options: CreateLinkOptions): Promise<{
  declarationId: Bytes32;
  paymentUrl: string;
  txHash: string;
}>
interface CreateLinkOptions {
  // Amount to request (0n = open amount, payer chooses)
  amount: bigint;

  // Currency you want to receive
  currency: Currency;

  // Recipient address (defaults to signer address)
  recipient?: Address;

  // Human-readable label (not stored on-chain in v1)
  label?: string;
}

Registers a payment declaration on the DeclarationRegistry contract and returns a shareable URL. The declaration is live immediately after the transaction confirms.

fulfill()

conduit.fulfill(
  declaration: PaymentDeclaration,
  options?: FulfillOptions
): Promise<PaymentReceipt>
interface FulfillOptions {
  // Currency the payer holds — must match the declaration's currency.
  payerToken?: Currency;
}

Executes a payment for a resolved declaration. Same-currency only — the payer's currency must match what the declaration asks for, or this throws. For a cross-currency payment against a declaration, resolve it with parse()/resolveDeclaration() and call pay() instead.

parse()

conduit.parse(url: string): Promise<PaymentDeclaration>

Resolve a PaymentDeclaration from a Conduit payment URL. Extracts the declaration ID and fetches on-chain data.

quote()

conduit.quote(options: {
  payerToken: Currency;
  recipientToken: Currency;
  amount: bigint;
}): Promise<Quote>
interface Quote {
  payerToken: Address;
  recipientToken: Address;
  payerAmount: bigint;    // what payer sends (6 decimals)
  recipientAmount: bigint; // what recipient gets (6 decimals)
  rate: number;           // exchange rate (display only)
  expiresAt: number;      // unix timestamp
}

Same-currency quotes return the exact on-chain amount including the protocol fee. Cross-currency quotes return 0n for payerAmount — the live rate is determined by Circle StableFX at execution time.

deactivateLink()

conduit.deactivateLink(declarationId: Bytes32): Promise<string> // txHash

Cancels a payment declaration. Only callable by the address that created it. A deactivated declaration can no longer be fulfilled.

getBalance()

conduit.getBalance(wallet: Address, currency: Currency): Promise<bigint>

Returns the token balance of a wallet in 6-decimal units.

getHistory()

conduit.getHistory(
  wallet: Address,
  options?: GetHistoryOptions
): Promise<PaymentReceipt[]>
interface GetHistoryOptions {
  limit?: number;   // default: 50
  offset?: number;  // default: 0
}

Returns all settled payments where wallet was the payer or recipient, sorted by block number descending.

getReceipt()

conduit.getReceipt(receiptId: Bytes32): Promise<PaymentReceipt | null>

Look up a single settled payment by its on-chain receipt ID.

getDeclarations()

conduit.getDeclarations(wallet: Address): Promise<PaymentDeclaration[]>

Returns all payment declarations registered by a wallet address.

Core types

type Address  = `0x${string}`;
type Bytes32  = `0x${string}`;
type Currency = "USDC" | "EURC";

interface PaymentDeclaration {
  declarationId: Bytes32;
  recipient: Address;
  recipientToken: Address;   // ERC-20 address
  currency: Currency;
  amount: bigint;            // 0n = open amount
  registeredAt: number;      // unix timestamp
  active: boolean;
  paymentUrl: string;        // https://app.conduit.xyz/pay/<id>
}

interface PaymentReceipt {
  receiptId: Bytes32;
  payer: Address;
  recipient: Address;
  payerToken: Address;
  recipientToken: Address;
  payerAmount: bigint;       // what payer sent (6 decimals)
  recipientAmount: bigint;   // what recipient received (6 decimals)
  declarationId: Bytes32;    // zero if ad-hoc payment
  settledAt: number;         // unix timestamp
  txHash: `0x${string}`;
  explorerUrl: string;       // https://testnet.arcscan.app/tx/...
}

Constants

import {
  ARC_TESTNET,
  CONDUIT_PAYMENT_HEADER,  // "conduit-payment"
  CONDUIT_WELL_KNOWN_PATH, // "/.well-known/conduit"
} from "@conduit/sdk";

// ARC_TESTNET shape:
{
  chainId: 5042002,
  rpc: "https://rpc.testnet.arc.network",
  ws: "wss://rpc.testnet.arc.network",
  explorer: "https://testnet.arcscan.app",
  tokens: { USDC: "0x...", EURC: "0x..." },
  contracts: {
    conduitRouter: "0x...",
    declarationRegistry: "0x...",
    stableFXAdapter: "0x...",
    atomicSettler: "0x...",
    cctpAdapter: "0x...",
    cctpTokenMessenger: "0x...",
    cctpMessageTransmitter: "0x...",
    permit2: "0x...",
  },
}

Next steps