SDK reference

@crackpay/miniapp-sdk, version 0.3.1. MIT licensed, ESM, with its own types.

npm install @crackpay/miniapp-sdk

Entry point	For	Peer dependency
@crackpay/miniapp-sdk	The provider, constants and error helpers	none
@crackpay/miniapp-sdk/viem	connectCrackPay() with viem clients	viem ≥ 2.21
@crackpay/miniapp-sdk/react	useCrackPay()	react ≥ 18

@crackpay/miniapp-sdk

getCrackPayProvider(options?)

function getCrackPayProvider(options?: CrackPayOptions): Promise<MiniAppProvider | null>;

Resolves with the wallet provider inside CrackPay and with null anywhere else. Never prompts. Resolves immediately with null when the page is not in a frame, and within timeoutMs otherwise. The connection is made once per page; later calls return the same promise.

type CrackPayOptions = {
  /** CrackPay hosts to accept. Default: CRACKPAY_ORIGINS. */
  hostOrigins?: readonly string[];
  /** How long to wait for CrackPay to answer. Default: 3000 ms. */
  timeoutMs?: number;
};

getCrackPayUser(provider)

function getCrackPayUser(provider: MiniAppProvider): Promise<CrackPayUser>;

type CrackPayUser = {
  account: `0x${string}`;
  /** CrackPay handle without the "@", or null. */
  handle: string | null;
};

The user's account and handle. Never prompts. Since 0.2.0.

isFramed()

function isFramed(): boolean;

Whether the page is in a frame. Synchronous. false means certainly not in CrackPay.

MiniAppProvider

interface MiniAppProvider {
  readonly isCrackPay: true;
  request(args: { method: string; params?: unknown }): Promise<unknown>;
  on(event: string, listener: (data: unknown) => void): void;
  removeListener(event: string, listener: (data: unknown) => void): void;
}

To use it with viem: custom(provider as unknown as EIP1193Provider). Supported methods: Provider methods.

Constants

Export	Value
CRACKPAY_ORIGINS	["https://www.crackpay.xyz", "https://crackpay.xyz", "https://crackpay.vercel.app"]
arcMainnet	{ id: 5042, hexId: "0x13b2", name: "Arc", rpcUrl, explorerUrl, faucetUrl: null, testnet: false }
arcTestnet	{ id: 5042002, hexId: "0x4cef52", name: "Arc Testnet", rpcUrl, explorerUrl, faucetUrl, testnet: true }
ARC_CHAINS	[arcMainnet, arcTestnet]
tokensByChain	{ [chainId]: { USDC, EURC } } for both networks
tokens	Deprecated: testnet tokens only. Use getTokens(chainId).
NATIVE_USDC_DECIMALS	18
WALLET_INFO	{ name: "CrackPay", icon, rdns: "app.crackpay" }
PROTOCOL_VERSION	1

getArcChain(chainId)

function getArcChain(chainId: number | string): ArcChainInfo | null;

The Arc network for a chain ID, as a number or the hex string eth_chainId returns. null for any other chain.

getTokens(chainId)

function getTokens(chainId: number | string): { USDC: Token; EURC: Token } | null;

USDC and EURC on that network, each { symbol, address, decimals: 6 }. EURC's address differs between mainnet and testnet, so never hardcode it.

Errors

Export	Description
ErrorCode	Named codes. See Error codes.
errorCode(error)	The numeric code, looking through one level of cause (viem and wagmi wrap errors)
isUserRejection(error)	true when the user cancelled
ProviderRpcError	What provider.request rejects with; has a numeric code

installCrackPayProvider({ hostOrigins, timeoutMs? })

The lower-level function behind getCrackPayProvider, with hostOrigins required. Prefer getCrackPayProvider.

@crackpay/miniapp-sdk/viem

connectCrackPay(options?)

function connectCrackPay(options?: CrackPayOptions & { rpcUrl?: string }): Promise<CrackPayConnection | null>;

type CrackPayConnection = {
  provider: MiniAppProvider;
  account: Address;
  handle: string | null;
  /** The Arc network CrackPay is on, read from eth_chainId. */
  chain: ArcChainInfo;
  /** Sends through CrackPay, on `chain`. */
  walletClient: WalletClient;
  /** Reads from Arc over HTTP. */
  publicClient: PublicClient;
};

Returns null outside CrackPay. When writing, pass account and chain: walletClient.chain.

@crackpay/miniapp-sdk/react

useCrackPay(options?)

function useCrackPay(options?: CrackPayOptions): CrackPayState;

type CrackPayState =
  | { status: "connecting" }
  | { status: "connected"; provider: MiniAppProvider; account: `0x${string}`; handle: string | null }
  | { status: "unavailable" }
  | { status: "error"; error: unknown };

Connects on mount. Pass a stable options object or none.

Script tag

For pages without a bundler:

<script src="https://www.crackpay.xyz/miniapp-sdk.js"></script>

window.crackpay
ready	Promise<MiniAppProvider | null>, as getCrackPayProvider()
version	1

The script trusts the origin it was loaded from. A self-hosted copy needs data-host-origins="https://www.crackpay.xyz" on the tag.

Changelog

Version
0.3.1	Trusts https://www.crackpay.xyz
0.3.0	Arc mainnet: arcMainnet, ARC_CHAINS, getArcChain, tokensByChain, getTokens; chain on connectCrackPay; tokens deprecated
0.2.0	getCrackPayUser; handle on connectCrackPay and useCrackPay
0.1.0	First release