embedded-wallet

1Shot API's free, permissionless embedded wallet. Includes passkey-based verification and OID4 credential management for shared KYC.

This repo is the OWS Branding Layer for the 1Shot Wallet — a frontend-only static app (React + Vite + Tailwind + shadcn/ui) hosted at wallet.1shotapi.com.

Host Layer (integrator dapp)
  └── This app /            Branding Layer (@1shotapi/ows-wallet-utils)
        └── /signer/        Signing Layer (@1shotapi/ows-signer)

Stack

Path	Content
/	React Branding Layer (Vite bundle)
/signer/	Static @1shotapi/ows-signer ES modules

Production deliverable: a static nginx Docker image (no server-side runtime).

Setup

npm install
cp .env.example .env  # set NGROK_AUTHTOKEN (and optional NGROK_DOMAIN)

Develop

npm run dev           # Branding Layer + ngrok HTTPS tunnel
npm run dev:local     # Branding Layer, local HTTP only
npm run dev:host      # Test Host Layer (setStyle knobs + EIP-1193)

Service	Local URL
Branding (/)	http://localhost:5174/
Signing (/signer/)	http://localhost:5174/signer/
Test host	http://localhost:5173

Passkeys need HTTPS — use the printed ngrok wallet URL as the host iframe source (NGROK_DOMAIN in .env is picked up by dev:host).

Style testing: use the Style (setStyle RPC) panel on the test host (host/), not in-wallet debug UI. See host/README.md.

Host integration

Production iframe URL: https://wallet.1shotapi.com/

npm install @1shotapi/ows-provider

import { OWSProxy } from "@1shotapi/ows-provider";

const proxy = await OWSProxy.create(container, "https://wallet.1shotapi.com/");

await proxy.rpc("setStyle", {
  copy: { productName: "Acme Wallet", tagline: "Powered by 1Shot" },
  theme: { primary: "oklch(0.45 0.18 250)" },
});

proxy.showWallet();

setStyle (custom RPC)

Additive merge of theme CSS variables + copy. Safe to call repeatedly. Schema is Zod-strict (unknown keys rejected). Full field list: skills/oneshot-embedded-wallet/SKILL.md.

Agent skill

Integrators / coding agents:

npx skills add 1Shot-API/embedded-wallet@oneshot-embedded-wallet
# or from a sibling clone:
npx skills add ../embedded-wallet --skill oneshot-embedded-wallet

Source: skills/oneshot-embedded-wallet.

Build

npm run build         # dist/ (branding) + dist/signer
npm run preview       # preview production wallet build

Docker

docker build -t oneshot-wallet .
docker run --rm -p 8080:80 oneshot-wallet
# open http://localhost:8080/
# signer at http://localhost:8080/signer/

Scripts

Script	Purpose
dev / dev:local	Dev server (± ngrok)
dev:host	Test Host Layer
build	Typecheck + Vite build + copy signer from node_modules
clean	Remove dist/
lint	tsc --noEmit

Refactor roadmap

See roadmap.md (ShadCN + customization phases).

Status

Functional Branding Layer (passkey unlock, EIP-1193, signing consent, recovery, credentials) with Phase 0–1 style foundations (setStyle + StyleProvider + shell). ShadCN UI migration in progress.