Quickstart

Quickstart: 1Shot Wallet

Embed a non-custodial, permissionless passkey wallet with @1shotapi/ows-provider — no API keys, EIP-1193 support, and built-in gas abstraction.

Recommended first step: load the skill

For best results, install and use the 1shot-wallet skill before implementing this quickstart. It includes proven defaults for OWSProxy setup, configure theming, EIP-1193 integration, and the Host → Branding → Signing architecture.

Install skill

npx skills add 1Shot-API/skills/1shot-wallet -y

Why 1Shot Wallet

1Shot Wallet is free and permissionless. Embed https://wallet.1shotapi.com/ with @1shotapi/ows-provider — no developer account, no API keys, no signup. Users unlock the same passkey-backed account across different apps without installing a browser extension. Gas abstraction is built in, so users can pay for gas in supported stablecoins — see Supported Networks for the available chains and fee tokens.

The wallet is built around the WebAuthn PRF extension: signing happens client-side in an isolated Signing iframe (implemented in pure javascript with no dependencies), so 1Shot Wallet will never charge for MAUs or signing operations.

Integrate 1Shot Wallet

Install the Host Layer packages, create an OWSProxy pointed at the hosted Branding Layer, then connect via EIP-1193. Always embed Host → Branding → Signing — never point your host at /signer/ directly.

Install packages

npm install @1shotapi/ows-provider @1shotapi/ows-types viem

import { OWSProxy } from "@1shotapi/ows-provider";
import { createWalletClient, custom } from "viem";
import { mainnet } from "viem/chains";

const WALLET_URL = "https://wallet.1shotapi.com/";

const container = document.getElementById("wallet-container")!;
const proxy = await OWSProxy.create(container, WALLET_URL);

// Optional: theme / copy before showing the flyout
await proxy.rpc("configure", {
  copy: { productName: "Acme Wallet", tagline: "Powered by 1Shot" },
  theme: { primary: "oklch(0.45 0.18 250)" },
});

proxy.showWallet();

// Use proxy.ethereum as a standard EIP-1193 provider with viem
const walletClient = createWalletClient({
  chain: mainnet,
  transport: custom(proxy.ethereum),
});

const [address] = await walletClient.requestAddresses();
const signature = await walletClient.signMessage({
  account: address,
  message: "Hello from 1Shot Wallet",
});

For the full Host API surface — configure, credentials, showWallet/hideWallet, and local HTTPS notes — use the 1shot-wallet skill (install command above) or read /.well-known/skills/1shot-wallet/SKILL.md.

Focus mode

By default the wallet opens in General mode (network selector + tabs). Use Focus mode when your app should lock the shell to a single chain and asset — for example a checkout or token detail flow — without asking the user to confirm. That keeps the experience on-task and conserves attention: users see only the asset that matters for the current step in your app, not the fully featured multi-chain wallet.

// Lock to one chain + asset (no user confirmation)
await proxy.rpc("focusWallet", {
  chainId: "0x4cef52", // Arc Testnet
  assetAddress: "0x3600000000000000000000000000000000000000", // USDC
});
proxy.showWallet();

// Restore general mode (keeps the current chain)
await proxy.rpc("unfocusWallet");

focusWallet switches the active chain, sets the focused asset, and opens the Asset Details shell. unfocusWallet clears focus and returns to the network selector + tabs. Try both in the playground.

Test and customize in the playground

Open the wallet playground to try EIP-1193 flows (connect, sign, send), preview branding in Design mode, and explore OID4 credential demos before shipping your integration.

When you are ready to add gas abstraction, continue with the Gas Abstraction quickstart.

USDC bridging

The wallet ships built-in Circle CCTP V2 bridging for native USDC. Users can bridge from Asset Details, or your Host can open the same flow with the bridge RPC — gasless source burns via the Public Relayer, destination mint via Circle Forwarding Service.

// Open bridge — user picks amount, source, and destination
await proxy.rpc("bridge", {});

// Or pre-fill params (decimal EVM chain IDs)
await proxy.rpc("bridge", {
  amount: "10.50",
  sourceChainId: 8453,
  destinationChainId: 42161,
});

See Embedded Wallet: USDC Bridging for fees, customization, webhooks, and playground testing.

Branding Customization

Brand the embedded wallet from your Host with proxy.rpc("configure", options) — theme colors, product name and tagline, consent modal copy, feature flags, and dark mode. Options are partially merged, so you can call configure again when your app theme changes.

The marketing site homepage and wallet page embeds, plus the playground Design mode, all use the same API. See Embedded Wallet: Customization for the full theme, copy, and features reference.

Analytics & Observability

The Branding Layer publishes product telemetry to your Host over proxy.analytics when users create accounts, sign, send transactions, issue or present credentials, or grant delegations. Subscribe after OWSProxy.create() and forward events to GA4, Segment, PostHog, or your own backend — including on-chain fields such as wallet addresses and transaction hashes when your analytics stack needs them.

The 1Shot marketing site uses the same client-side pattern on the homepage, wallet page, and playground. See Embedded Wallet: Analytics for the full subscribe → forward → GA4 portal setup procedure.