@faktoryfun/pillar-sdk

Client SDK for smart-wallet-as-a-service: let an external builder (fak.fun, SkullCo.in, Dataing.io, DeOrganized, bitcoincredit.services, …) create passkey smart wallets and trade from them, from their own app, without running any signing keys or relay infrastructure.

The SDK is the client half. Everything privileged — contract deployment, the deployer key, gas payment/sponsorship, nonce management, second-layer indexing — stays on the hosted relay (faktory-dao, backed by the Juice node's SecondLayer subscriptions). The SDK holds no secrets.

┌─ builder's app (browser, on their domain) ─┐      ┌─ relay (faktory-dao) ───────────┐
│ @faktoryfun/pillar-sdk                                 │      │ /api/smart-wallet/*             │
│  • createPasskey  (WebAuthn, rpId)          │ ───▶ │  deploy + onboard (deployer     │
│  • deployWallet / waitForWallet             │      │  key, pays gas)                 │
│  • swapThroughWallet (passkey signs,        │      │  execute (gas-sponsored swap    │
│    relay broadcasts)                        │      │  through the smart wallet)      │
└─────────────────────────────────────────────┘      └─────────────────────────────────┘

The WebAuthn signature only verifies on-chain when the page origin matches the wallet's baked-in rpId (e.g. fak.fun). So the SDK must run on the builder's own domain — a user signs on the builder's site, the SDK relays the signature, the relay broadcasts.

This is not self-serve — you onboard with us first

Because of that rpId binding, installing the SDK alone will not work for your app. A passkey created on your domain can only sign for a smart wallet whose contract has your rpId hash baked in. Today the relay only deploys wallets for our own domains (fak.fun, fakfun.com) — so any signature from another origin is rejected on-chain.

To go live, we onboard you server-side:

1. Add your rpId to the relay's template selection (on top of ours), so it deploys smart wallets that verify signatures from your domain.
2. Whitelist an extension for your use case, if you need on-chain actions beyond swaps (e.g. an inscribe/registry extension specific to your app).
3. Hand you a production API key (the SDK's default key is a public, rate-limited demo key — see Auth).

Until then you can read the docs, install the package, and see it working on our live app (below) — but sigs from your own domain won't broadcast.

Live demo

Try it live:

https://fak.fun/m/markets/demo-sdk/SP1Z92MPDQEWZXW36VX71Q25HKF5K2EPCJ304F275.tokensoft-token-v4k68639zxz

It's a clone of that token's market page whose Buy/Sell widget routes through this SDK (swapThroughWallet) using your connected passkey smart wallet. It's an unlisted reference route (not linked anywhere in the app) that shows the exact calls you'd make — the rest of the fak.fun app talks to the relay directly. The URL pattern is fak.fun/m/markets/demo-sdk/<contract>.

How this differs from Privy / Turnkey

Privy and Turnkey are signing/auth providers — they manage keys and offer email + embedded-wallet onboarding. Pillar is smart-wallet-as-a-service on Stacks. The differences that matter:

• No third-party key custody — the passkey is the key. Privy/Turnkey custody a private key on the user's behalf (a secp256k1 key) that the user's WebAuthn merely unlocks — a third party still holds a key, a second layer between your user and the chain. Pillar removes that layer entirely: Stacks Clarity verifies the WebAuthn signature directly on-chain, so there is no separately-held private key and no provider in the middle — only the user's own device passkey. Cheaper and more trustless.
• No lock-in, no privileges we hold. Your users' smart wallets are fully owned by the users on the Stacks chain. We're a plug-and-play facilitator — but you can exit the Pillar SDK entirely and keep servicing those same wallets, because we hold no privilege over them. Our role is limited to deploying each wallet, verifying it's byte-identical to an on-chain verified template, and binding the user's public WebAuthn key as its owner. No admin key, no backdoor, no custody.
• We broadcast — they don't. Privy/Turnkey stop at producing a signature; you still have to build, relay, and broadcast the transaction yourself. Pillar takes the passkey signature and broadcasts it to Stacks end-to-end, returns the confirmed success, and sponsors the STX gas — so you, the builder, never touch gas. The ~20 sat sBTC that covers it is charged to the user's smart wallet on-chain, baked into the call.
• Flat monthly, never per-signature. They meter you per signature. Because we verify on-chain, we charge a flat monthly for the infra — signatures aren't taxed.
• Passkey-only onboarding, by design. We deliberately do not offer email/embedded-wallet login (it's easy to build — we choose secure passkey signing instead). If you need email/embedded onboarding, that's Privy/Turnkey's lane; Pillar is for passkey smart wallets + on-chain execution. Pair it with Leather/Xverse for crypto-native users.

Getting access & pricing

Start with a free consultation — we scope your use case, give you architecture/integration guidance, and build a free proof-of-concept for your flow. Full pricing at https://www.pillarwallets.xyz/pricing:

| Plan | Price | Includes | | --- | --- | --- | | Consult | Free | Use-case consultation, wallet architecture & integration guidance, SDK + docs access, free POC | | Starter | $99/mo | 10k signatures/mo, $0 per signature (never metered), custom wallet policies + passkey auth, real-time balances & tx notifications | | Scale | $499/mo | Everything in Starter, 100k signatures/mo, higher onboarding allowance, priority support | | Enterprise | Custom | Custom smart-wallet contract (one-time build), full hardening (RV fuzzing, stxer sims, Clarinet tests), unlimited signatures + dedicated relayer/indexer, SLAs |

We verify signatures on-chain, so we charge a flat monthly for the infra we run — never a per-action tax. Per-action gas (swaps, transfers, …) is not billed by us: the STX fee is sponsored, and the ~20 sat sBTC that covers it is baked into the contract call via the gas-input contract — charged to the end user on-chain, automatically. The only cost we bill you (at cost) is the one-time wallet deployment, ~0.1 STX per smart wallet.

Install

npm install @faktoryfun/pillar-sdk

Browser with WebAuthn required for passkey create/sign; Node 18+ for the relay calls (global fetch).

Quick start — create / deploy / onboard a wallet

import { PillarClient, createWallet } from "@faktoryfun/pillar-sdk";

const client = new PillarClient({
  builder: "fakfun",          // selects rpId + canonical wallet template
  apiKey: process.env.PILLAR_API_KEY, // optional — omit to use the public demo key
});

const { passkey, wallet } = await createWallet(client, {
  walletName: "rafshi",                 // 3–20 chars, starts with a letter
  userName: "[email protected]",
  passcode: process.env.FREE_DEPLOY_PASSCODE, // free-deploy gate (else 402)
  waitUntil: "deployed",                // optional: poll until onboarded
});

// passkey.pubkey       -> 33-byte compressed P-256 owner key (persist this)
// passkey.credentialId -> needed later to sign (swap)
// wallet.contractAddress -> e.g. SP….rafshi-wallet

Swap from the smart wallet

The passkey signs a SIP-018 faktory-execute challenge; the relay gas-sponsors and broadcasts. Routes through the fak.fun core contract with the pool as input.

import { swapThroughWallet, OPCODE_BUY } from "@faktoryfun/pillar-sdk";

const res = await swapThroughWallet(client, {
  walletContract: wallet.contractAddress,
  credentialId: passkey.credentialId,
  ownerPubkey: passkey.pubkey,
  poolContract: "SP….pepe-pool",
  amount: 1_000_000,            // micro-units of the input asset
  opcode: OPCODE_BUY,           // 0x00 buy, 0x01 sell
  sip010Contract: "SP….pepe",
  sip010Name: "pepe",
  minAmountOut: 900_000,        // recommended: relay adds an output post-condition
  tokenContract: "SP….pepe",
  tokenAssetName: "pepe",
});
// res.txid -> broadcast tx id

Two paths, by who pays gas

• swapThroughWallet (WebAuthn, we relay): the passkey signs off-chain, our relay broadcasts and sponsors the STX fee. The wallet call passes the gas-station contract, so the wallet pays us ~20 sat sBTC per tx to cover it. This is the gasless path we run end-to-end.
• buildWalletExecuteCall (owner via Leather/Xverse, self-gassed — we don't relay): for when the wallet owner triggers an action on their own smart wallet using their normal L/X wallet — a standard Stacks transaction, not a passkey signature — and pays their own STX. It's a pure helper returning the stx_callContract params (contract = the smart wallet, functionArgs with sig-auth: none + gas: none, post-conditions) for your frontend to sign via @stacks/connect. No signing, no network, no gas from us.

Builders

A builder is one tenant: an rpId + a canonical wallet template. Passkeys are scoped to rpId, so a builder's wallets only sign on that builder's domain.

| id | rpId | canonical wallet | deployable | | --------------- | ------------------------ | ------------------------ | ---------- | | fakfun | fak.fun | …​.fakfun-wallet-v7 | ✅ | | deorgmedia | deorganized.com | …​.pillar-deorg-wallet | ⏳ (soon) | | skullco | skullco.in | — | ⏳ (soon) | | stxbuzz | stx.buzz | — | ⏳ (soon) | | bitcoincredit | bitcoincredit.services | — | ⏳ (soon) |

Only fakfun is deployable today: the relay ships the fak.fun v7 template unconditionally, so a non-fak.fun passkey would not verify against it. Per-builder template selection is coming server-side; deployWallet throws early for non-deployable builders until then. The ⏳ rows are planned tenants shown as examples — not all are in the built-in BUILDERS registry yet.

Pass a full BuilderConfig object instead of an id for a custom tenant.

Auth

Every request sends an x-api-key header. If you don't pass apiKey, the SDK falls back to a public, rate-limited demo key (PUBLIC_DEMO_KEY) so you can call the relay while evaluating, without provisioning a key first.

This only removes the API-key step — it does not make your own app work end-to-end. Wallets are bound to an rpId that's verified on-chain, so signatures from your domain only broadcast once we've deployed your domain-bound wallets (see onboarding). Pass your own key for production limits.

Relay endpoints this SDK uses

| Method | Path | Purpose | | ------ | ------------------------------------------ | ----------------------------- | | POST | /api/smart-wallet/v2/deploy | deploy + background onboard | | GET | /api/smart-wallet/{pubkey}?by=pubkey | look up wallet (or /{name}) | | GET | /api/smart-wallet/check-name?name= | name availability | | POST | /api/smart-wallet/v2/execute | swap through the smart wallet |

Status / roadmap

• ✅ create / deploy / onboard wallet
• ✅ swap through the smart wallet (faktory-execute) + EOA core-call helper
• ⏳ per-builder template selection (server-side) — unlocks non-fak.fun builders
• ⏳ inscribe surface — sign content with the passkey and relay it through the wallet's extension-call → inscribe extension (extension currently caps at buff 2048; the >2KB article path is a separate decision)