# Buckspay SDK

> Gasless smart-wallet SDK for Stellar (Soroban) USDC payments - web and mobile.

## Docs

- [Get classic account state](https://docs.buckspay.xyz/api-reference/account-state/get-classic-account-state.md): Returns on-chain state for a classic Stellar G-address: whether it exists, whether it has a USDC trustline, and its XLM and USDC balances. Used by the SDK to gate the onboarding flow and to display account state in UI.
- [Get contract account state](https://docs.buckspay.xyz/api-reference/account-state/get-contract-account-state.md): Returns on-chain state for a passkey smart-account or policy session-account (C-address). Same response shape as the classic account endpoint. The SDK routes G-addresses to `/stellar/account/:pk` and C-addresses here.
- [Email OTP -> Stellar key](https://docs.buckspay.xyz/api-reference/auth/email-otp->-stellar-key.md): Signer-proxy endpoint. The BFF (`createSignerProxyRoute({ provider: 'email', ... })`) forwards this request to the facilitator's `/auth/email`. The facilitator verifies the one-time code and returns the user's derived Stellar public key.
- [Social identity -> Stellar key](https://docs.buckspay.xyz/api-reference/auth/social-identity->-stellar-key.md): Signer-proxy endpoint. The BFF (`createSignerProxyRoute({ provider: 'web3auth', ... })`) forwards this request to the facilitator's `/auth/social` with the server-held API key injected. The facilitator verifies the provider identity token, derives or recovers the user's Stellar key, and returns it.
- [Quote a gas-in-token fee](https://docs.buckspay.xyz/api-reference/fee/quote-a-gas-in-token-fee.md): Request a fee quote for paying Soroban gas in a token instead of XLM. The facilitator simulates the calls, prices the XLM fee as a token amount, and returns the quote including the `FeeForwarder` contract address and a ledger-based expiry.
- [API Reference](https://docs.buckspay.xyz/api-reference/index.md): HTTP wire contract for the Buckspay facilitator and BFF relay route.
- [Build onboarding transaction](https://docs.buckspay.xyz/api-reference/onboarding/build-onboarding-transaction.md): Build the sponsor-funded onboarding transaction for a classic G-address: creates the account if needed and establishes the USDC trustline. The facilitator returns the unsigned transaction XDR for the user to sign and submit via `POST /stellar/onboard/submit`.
- [Deploy a passkey smart-account](https://docs.buckspay.xyz/api-reference/onboarding/deploy-a-passkey-smart-account.md): Sponsor-deploy a passkey smart-account (secp256r1 / WebAuthn). The SDK sends the passkey's 65-byte uncompressed public key; the facilitator holds the sponsor secret, enforces the pinned Wasm hash, and returns the deployed contract address.
- [Deploy a policy session-account](https://docs.buckspay.xyz/api-reference/onboarding/deploy-a-policy-session-account.md): Sponsor-deploy a policy-scoped session-account bound to an ed25519 root key. The SDK sends the root public key (G-address); the facilitator holds the sponsor secret, enforces the pinned Wasm hash, and returns the deployed contract address. Requires `deploySessionAccount` support in the relayer.
- [Submit signed onboarding transaction](https://docs.buckspay.xyz/api-reference/onboarding/submit-signed-onboarding-transaction.md): Submit the user-signed onboarding transaction XDR from `POST /stellar/onboard/build`. The facilitator fee-bumps it (so the user does not need XLM for fees) and submits it to Stellar.
- [Relay a signed payment](https://docs.buckspay.xyz/api-reference/relay/relay-a-signed-payment.md): Submit a signed Soroban `SorobanAuthorizationEntry` (base64 XDR) to the facilitator. The facilitator wraps it in a fee-bump transaction, submits it to Stellar, and returns a `Receipt`.
- [Get an EVM swap quote](https://docs.buckspay.xyz/api-reference/swap/get-an-evm-swap-quote.md): Get a gasless EVM token swap quote. Requires the relayer to be configured with a `swapChain` (see `FacilitatorOptions`). Returns a quote ID, expected amounts, and EIP-712 typed data for the swap authorization.
- [Account models](https://docs.buckspay.xyz/concepts/account-models.md): Classic G-addresses vs. passkey smart-contract accounts - when to use each.
- [Facilitator and BFF](https://docs.buckspay.xyz/concepts/facilitator-and-bff.md): The relayer's role in the payment flow, and why your API key must stay server-side behind a same-origin BFF.
- [Gasless on Stellar](https://docs.buckspay.xyz/concepts/gasless-on-stellar.md): How Stellar's native account-abstraction primitives make the payer's XLM balance irrelevant.
- [Networks](https://docs.buckspay.xyz/concepts/networks.md): Testnet vs. pubnet, the mainnet opt-in guard, USDC decimals, and the multi-network rail model.
- [Prepare -> Sign -> Send](https://docs.buckspay.xyz/concepts/prepare-sign-send.md): The three-phase mental model every Buckspay payment follows - and where to insert backend validation.
- [Atomic batch](https://docs.buckspay.xyz/features/atomic-batch.md): Settle multiple transfers all-or-nothing in one Stellar transaction with a single signature.
- [Gas in token](https://docs.buckspay.xyz/features/gas-in-token.md): Let users pay Soroban transaction fees in USDC instead of XLM via the FeeForwarder contract.
- [Gasless modes](https://docs.buckspay.xyz/features/gasless-modes.md): Sponsored vs. token-fee gas abstraction - choose who pays for the transaction fee.
- [Feature coverage](https://docs.buckspay.xyz/features/index.md): Every Buckspay feature mapped to its native Stellar mechanism, SDK surface, runnable example, and guide page.
- [Onboarding](https://docs.buckspay.xyz/features/onboarding.md): Sponsored account creation and trustline setup - the payer needs zero XLM, not even to exist on-chain.
- [Allowlist policy](https://docs.buckspay.xyz/features/sessions/allowlist.md): Restrict a session key to a fixed set of contracts - enforced on-chain in __check_auth.
- [Sessions](https://docs.buckspay.xyz/features/sessions/overview.md): Scoped, expiring session keys that let users pay within fixed on-chain policies without a root prompt per action.
- [Spend limit policy](https://docs.buckspay.xyz/features/sessions/spend-limit.md): Cap a session key's cumulative token spend over a rolling period - enforced on-chain in __check_auth.
- [Swaps](https://docs.buckspay.xyz/features/swaps.md): Optional token-swap surface via the facilitator's swap rail - quoteSwap ships end-to-end; swap enforces a minOut floor.
- [Installation](https://docs.buckspay.xyz/get-started/installation.md): Add Buckspay SDK packages to your project.
- [Quickstart](https://docs.buckspay.xyz/get-started/quickstart.md): Send a gasless USDC transfer on Stellar in under five minutes.
- [Which package do I need?](https://docs.buckspay.xyz/get-started/which-package.md): A one-line guide to every published Buckspay SDK package.
- [Buckspay SDK](https://docs.buckspay.xyz/index.md): Gasless USDC payments on Stellar, in a few lines - on web and mobile.
- [Platforms](https://docs.buckspay.xyz/platforms/index.md): The Buckspay SDK core is platform-agnostic. Each platform binding swaps only the host layer and the signer - the account model, gas engine, and payment flow are identical everywhere.
- [Next.js BFF - @buckspay/nextjs](https://docs.buckspay.xyz/platforms/nextjs-bff.md): App Router route factories that keep the facilitator API key and provider secrets server-side behind same-origin BFF routes.
- [Node / Core - @buckspay/core](https://docs.buckspay.xyz/platforms/node-core.md): Use createBuckspayClient directly - no React. Suitable for server scripts, CLI tools, and backend workers.
- [React Native - @buckspay/react-native](https://docs.buckspay.xyz/platforms/react-native.md): The same BuckspayProvider and hooks on iOS and Android, with nativePasskey (device secure enclave) and secure-storage adapters.
- [Web - @buckspay/react](https://docs.buckspay.xyz/platforms/web-react.md): BuckspayProvider, useWallet, and useStellarPay - React hooks for gasless USDC payments in web apps.
- [Mainnet cutover runbook](https://docs.buckspay.xyz/production/mainnet-cutover.md): The deliberate, reversible, audited procedure to enable Stellar pubnet for the Buckspay SDK and facilitator.
- [Audit prep](https://docs.buckspay.xyz/production/security/audit-prep.md): Scope, release-blocker checklist, and sign-off table for the Buckspay SDK security audit.
- [Contract provenance](https://docs.buckspay.xyz/production/security/contract-provenance.md): Which wasm Buckspay deploys, where it comes from, how to reproduce it, and what that means for the audit scope.
- [Key handling](https://docs.buckspay.xyz/production/security/key-handling.md): Where every key and secret may live, where it must not, and the operational rules that enforce the boundary.
- [Secret rotation runbook](https://docs.buckspay.xyz/production/security/secret-rotation.md): Enumeration and rotation procedure for every burned secret from the .env.bak incident.
- [Threat model](https://docs.buckspay.xyz/production/security/threat-model.md): STRIDE-style analysis of the six security surfaces in the Buckspay SDK.
- [Versioning and migration](https://docs.buckspay.xyz/production/versioning-and-migration.md): How @buckspay/* packages are versioned, what your ^ pin actually resolves, and how to migrate across breaking changes.
- [accounts/src/classic](https://docs.buckspay.xyz/sdk-reference/accounts/src/classic/index.md)
- [accounts/src/oz-contract](https://docs.buckspay.xyz/sdk-reference/accounts/src/oz-contract/index.md)
- [accounts/src/policy-account](https://docs.buckspay.xyz/sdk-reference/accounts/src/policy-account/index.md)
- [accounts/src/policy](https://docs.buckspay.xyz/sdk-reference/accounts/src/policy/index.md)
- [core/src](https://docs.buckspay.xyz/sdk-reference/core/src/index.md)
- [nextjs/src](https://docs.buckspay.xyz/sdk-reference/nextjs/src/index.md)
- [react-native/src](https://docs.buckspay.xyz/sdk-reference/react-native/src/index.md)
- [react/src](https://docs.buckspay.xyz/sdk-reference/react/src/index.md)
- [relayer/src/buckspay-facilitator](https://docs.buckspay.xyz/sdk-reference/relayer/src/buckspay-facilitator/index.md)
- [signers/src/email](https://docs.buckspay.xyz/sdk-reference/signers/src/email/index.md)
- [signers/src/passkey](https://docs.buckspay.xyz/sdk-reference/signers/src/passkey/index.md)
- [signers/src/social](https://docs.buckspay.xyz/sdk-reference/signers/src/social/index.md)
- [signers/src/wallets-kit](https://docs.buckspay.xyz/sdk-reference/signers/src/wallets-kit/index.md)
- [Email OTP](https://docs.buckspay.xyz/signers/email-otp.md): Authenticate users with a one-time code sent to their inbox - no wallet, no seed phrase, no OAuth account required.
- [Native passkey](https://docs.buckspay.xyz/signers/native-passkey.md): iOS and Android WebAuthn via the device secure enclave - the same secp256r1 crypto as the web passkey signer, only the authenticator transport differs.
- [Signers](https://docs.buckspay.xyz/signers/overview.md): Every signer factory returns a BuckspaySigner that plugs into the same client and the same prepare -> sign -> send flow. Only how you obtain the signer differs.
- [Passkey](https://docs.buckspay.xyz/signers/passkey.md): WebAuthn / secp256r1 signing on a smart contract account - the private key never leaves the authenticator.
- [Social login](https://docs.buckspay.xyz/signers/social-login.md): Sign users in with Google, Apple, or Discord via web3auth - the provider secret stays server-side, never in the browser bundle.
- [Wallets Kit](https://docs.buckspay.xyz/signers/wallets-kit.md): Connect Freighter, xBull, or LOBSTR with a single factory - the signer plugs into the same client and payment flow as every other Buckspay signer.

## OpenAPI Specs

- [openapi](https://docs.buckspay.xyz/api-reference/openapi.json)