SDK 레퍼런스

@stablechain/sdk의 전체 표면. 단계별 안내는 SDK 빠른 시작을 참조하세요.

설치

npm install @stablechain/sdk viem

added 2 packages, audited 3 packages in 2s

viem >= 2.0.0은 피어 의존성입니다.

`createStable(config)`

StableClient를 생성합니다. StableClient에 나열된 메서드를 가진 객체를 반환합니다.

import { createStable, Network } from "@stablechain/sdk";
 
const stable = createStable({ network: Network.Mainnet, account });

StableClient { transfer, quoteBridge, bridge, quoteSwap, swap }

`StableConfig`

필드	타입	기본값	설명
`network`	`Network`	`Network.Mainnet`	대상 네트워크.
`rpc`	`string`	`network`의 공개 RPC	RPC 재정의.
`account`	`viem.Account`		서버 측 서명자 (예: `privateKeyToAccount`).
`transport`	`viem.Transport`		브라우저 지갑 트랜스포트 (예: `custom(window.ethereum)`).
`walletClient`	`viem.WalletClient`		사전 구축된 지갑 클라이언트. `account` 및 `transport`보다 우선합니다.

account, transport, walletClient 중 하나를 제공하세요.

`StableClient`

`transfer(params)`

Stable에서 네이티브 USDT0 또는 임의의 ERC-20을 전송합니다. 지갑을 Stable 체인으로 전환하고, 누락된 경우 온체인에서 토큰 소수 자릿수를 가져오며, 영수증을 기다립니다.

const { txHash } = await stable.transfer({
  from: "0xYourAddress",
  to: "0xRecipient",
  amount: 10,
});

{ txHash: "0x8f3a...2d41" }

파라미터	타입	설명
`from`	`string`	발신자 주소.
`to`	`string`	수신자 주소.
`amount`	`number`	사람이 읽을 수 있는 금액.
`token`	`string?`	ERC-20 컨트랙트 주소. 네이티브 USDT0의 경우 생략.
`tokenDecimals`	`number?`	소수 자릿수. 생략 시 온체인에서 가져옵니다.

OperationResult ({ txHash, toAmount? })를 반환합니다.

`quoteBridge(params)`

브리지를 미리 봅니다. 읽기 전용 — 서명도, 가스도 없습니다.

const quote = await stable.quoteBridge({
  fromChain: Chain.Ethereum,
  toChain: Chain.Stable,
  fromToken: "0x6C96dE32CEa08842dcc4058c14d3aaAD7Fa41dee",
  toToken: "0x779Ded0c9e1022225f8E0630b35a9b54bE713736",
  amount: 100,
});

{ toAmount: 99.94 }

BridgeQuote를 반환합니다.

`bridge(params)`

토큰을 크로스체인으로 브리지합니다. SDK가 경로를 선택합니다: USDT0 → USDT0에는 LayerZero, 그 외 모든 경우에는 LI.FI를 사용합니다. 내부 견적 호출을 건너뛰려면 사전에 가져온 quote를 전달하세요.

const { txHash } = await stable.bridge({ ...bridgeParams, quote });

{ txHash: "0xabcd...7890" }

파라미터	타입	설명
`fromChain`	`Chain`	소스 체인.
`toChain`	`Chain`	대상 체인.
`fromToken`	`string`	소스 토큰 컨트랙트 주소.
`toToken`	`string`	대상 토큰 컨트랙트 주소.
`amount`	`number`	사람이 읽을 수 있는 금액.
`fromDecimals`	`number?`	소스 토큰 소수 자릿수. 기본값은 `6`.
`recipient`	`string?`	대상 주소. 기본값은 서명자.
`quote`	`BridgeQuote?`	사전에 가져온 견적. 내부 견적 호출을 건너뜁니다.

`quoteSwap(params)`

Stable에서 LI.FI 스왑 견적을 가져옵니다. 사전 구축된 트랜잭션 요청과 승인 주소를 반환합니다.

const quote = await stable.quoteSwap({
  fromToken: "0x8a2B28364102Bea189D99A475C494330Ef2bDD0B",
  toToken: "0x779Ded0c9e1022225f8E0630b35a9b54bE713736",
  amount: 100,
  fromDecimals: 6,
});

{ toAmount: 99.81, fromAmount: 100000000n, fromToken: "0x8a2B...", approvalAddress: "0x...", transactionRequest: { ... } }

`swap(params)`

LI.FI를 통해 Stable에서 토큰을 스왑합니다. ERC-20 승인을 자동으로 처리하고 필요한 경우 지갑의 체인을 전환합니다.

const { txHash, toAmount } = await stable.swap({ ...swapParams, quote });

{ txHash: "0xabcd...", toAmount: 99.81 }

파라미터	타입	기본값	설명
`fromToken`	`string`		소스 토큰 주소.
`toToken`	`string`		대상 토큰 주소.
`amount`	`number`		사람이 읽을 수 있는 금액.
`fromDecimals`	`number?`	`6`	소스 토큰 소수 자릿수.
`toAddress`	`string?`	서명자	수신자 주소.
`quote`	`SwapQuote?`		사전에 가져온 견적. LI.FI 호출을 건너뜁니다.

열거형

`Network`

값	체인 ID
`Network.Mainnet`	988
`Network.Testnet`	2201

`Chain`

quoteBridge와 bridge에서 사용됩니다. 각 항목에는 해당하는 CHAIN_CONFIGS 항목이 있습니다.

열거형	네트워크	체인 ID
`Chain.Sepolia`	Ethereum Sepolia	11155111
`Chain.StableTestnet`	Stable Testnet	2201
`Chain.Stable`	Stable Mainnet	988
`Chain.Ethereum`	Ethereum	1
`Chain.Arbitrum`	Arbitrum One	42161
`Chain.Ink`	Ink	57073
`Chain.Bera`	Berachain	80094
`Chain.MegaETH`	MegaETH	4326
`Chain.Base`	Base	8453
`Chain.BSC`	BNB Smart Chain	56
`Chain.HyperEVM`	HyperEVM	999

`CHAIN_CONFIGS`

Chain 열거형을 키로 하는 Partial<Record<Chain, ChainConfig>>입니다. 각 항목은 id, rpc, usdt, decimals를 노출합니다. 지원되는 체인의 정식 USDT 주소를 하드코딩하지 않고 필요할 때 사용하세요.

import { CHAIN_CONFIGS, Chain } from "@stablechain/sdk";
 
console.log(CHAIN_CONFIGS[Chain.Stable]);

{ id: 988, rpc: "https://rpc.stable.xyz", usdt: "0x779Ded0c9e1022225f8E0630b35a9b54bE713736", decimals: 6 }

오류

모든 SDK 오류는 viem의 BaseError를 확장하는 StableError를 확장합니다. 오류는 구조화된 메타데이터를 포함하므로 error.name 또는 instanceof로 분기할 수 있습니다.

클래스	발생 시점	유용한 필드
`StableValidationError`	파라미터가 검증에 실패할 때 (잘못된 주소, 유한하지 않은 금액, 지원되지 않는 체인).	`field`, `value`
`StableQuoteError`	LI.FI에 대한 견적 요청이 실패할 때.	`provider`, `httpStatus`, `providerCode`, `body`
`StableTransactionError`	온체인 단계가 실패할 때: 체인 전환, 승인, 전송 또는 되돌리기.	`phase`, `txHash`, `chainId`, `revertReason`
`StableNetworkError`	기본 HTTP/RPC 호출이 실패할 때.	`url`

import { StableTransactionError } from "@stablechain/sdk";
 
try {
  await stable.transfer({ from, to, amount: 1 });
} catch (err) {
  if (err instanceof StableTransactionError && err.phase === "switch_chain") {
    // user rejected the chain switch
  }
  throw err;
}

StableTransactionError: transfer: wallet rejected or failed to switch to chain 988
  Phase: switch_chain
  Chain ID: 988

다음 추천 항목

SDK 빠른 시작 — SDK를 설치하고 테스트넷에서 첫 전송을 실행합니다.
viem과 함께 사용하기 — 개인 키, 브라우저 지갑, 사전 구축된 서명자 간 전환.
wagmi와 함께 사용하기 — 훅을 사용하여 React 앱에 SDK를 연결합니다.