1shot Wallet

1Shot Embedded Wallet (Host integration)

Teach an agent how to embed the 1Shot Wallet Branding Layer from a Host Layer app using @1shotapi/ows-provider.

Host (your dapp)          @1shotapi/ows-provider → OWSProxy
  └── Branding iframe     https://wallet.1shotapi.com/
        └── Signing       https://wallet.1shotapi.com/signer/  (same origin)

Safari create (first-party tab):
  Branding iframe ──window.open──► https://wallet.1shotapi.com/create/
                                     └── Branding iframe + createAccount RPC

Install

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

Minimal setup

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

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();

// EIP-1193
const accounts = await proxy.ethereum.request({ method: "eth_requestAccounts" });

Local / HTTPS notes

• Passkeys require a secure-context ancestor chain. The Host page must be HTTPS (or localhost) when the wallet iframe is HTTPS.
• Dev wallet URL: your ngrok or local Vite origin root (e.g. https://….ngrok-free.app/).
• Production wallet URL: https://wallet.1shotapi.com/ (Signing Layer at /signer/ on the same origin — do not embed /signer/ from the host).
• Safari / iOS WebKit cannot create passkeys inside a cross-origin wallet iframe. The branding layer detects this and opens https://wallet.1shotapi.com/create/ in a new tab (same origin as the wallet). Allow pop-ups from the embedding page so that handoff can complete; no host code changes are required.

Custom RPC — configure

1Shot-specific method registered on the Branding Layer. Call via:

await proxy.rpc("configure", options);

options is a partial merge (safe to call repeatedly):

Returns { ok: true, productName: string } with the resolved product name after merge.

Unknown keys are rejected (Zod .strict()).

See also embedded-wallet README.

Custom RPC — focusWallet / unfocusWallet

Host-controlled shell modes. Callers (not end users) switch between General (multi-chain tabs) and Focused (single chain + asset detail view).

// Lock to one chain + ERC-20 (or other) asset
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 returns { ok: true, mode: "focused", chainId, assetAddress }.
unfocusWallet returns { ok: true, mode: "general" }.

Unlike addAsset, focusWallet does not ask the user for confirmation — hosts may temporarily lock the shell to any asset.

Custom RPC — addAsset

Propose a tracked ERC-20 for the Balances tab. The wallet resolves the token (known catalog, or on-chain getCode + name/symbol/decimals) before showing the confirm modal. Non-ERC-20 addresses are rejected. Always requires user confirmation (Reject / Add). On approval the asset is persisted; on rejection the RPC throws a user-rejected error.

await proxy.rpc("addAsset", {
  chainId: "0x4cef52", // Arc Testnet
  assetAddress: "0x3600000000000000000000000000000000000000", // USDC
});
proxy.showWallet();

Returns { ok: true, chainId, assetAddress } when the user accepts.

Users can also add assets from the Balances tab without a host RPC. The Balances list shows tracked assets for the currently selected network only (USDC is always tracked where listed; USDG on Robinhood).

Custom RPC — createAccount

Used by the first-party /create/ host page (Safari passkey create). Hosts embedding the wallet normally do not call this — the branding layer opens /create/ itself when needed.

const result = await proxy.rpc("createAccount");
// { ok: true, credentialId: string, accounts: EVMAccountAddress[] }

// Optional pre-chosen passkey name (skips the name modal):
await proxy.rpc("createAccount", { accountName: "My Wallet" });

Other Host APIs

Subscribe so in-wallet chain/account changes update host UI without polling:

proxy.ethereum.on("chainChanged", (chainId) => {
  // hex chain id string
});
proxy.ethereum.on("accountsChanged", (accounts) => {
  // EVM address array
});

Analytics (proxy.analytics)

Branding publishes product events over Postmate. OWS types only eventId, timestamp, hostDomain, and name; this wallet attaches rich fields. Narrow on name:

proxy.analytics.on((event) => {
  console.info(event.name, event);
});

proxy.analytics.on("PersonalSign", (event) => {
  // event.durationMs, event.accountAddress, …
});

The same rich payload is POSTed fire-and-forget to POST /wallet/product-events on the 1Shot relayer. The local Host (host/) and marketing wallet playground include a live Analytics panel fed by proxy.analytics.on (filter by name).

Relayer integration (when the host submits txs)

• Default sends: eth_sendTransaction through OWSProxy — the wallet signs delegations and calls relayer_* internally. The host does not implement a relayer JSON-RPC client.
• Delegated execution (Path B): when the host or backend will redeem a user grant via public relayer JSON-RPC, also install the public-relayer skill.
  • B1 direct: grant to: relayer targetAddress → Example 0b in public-relayer/references/examples.md.
  • B2 session key (recommended): grant to: host session account, redelegate to: targetAddress, submit delegation chain → Example 0c.
  • See public-relayer/SKILL.md (Integration paths with 1shot-wallet).
• Status webhooks: optional configure.destinationUrl — the wallet forwards it to the relayer on send. Still no direct relayer client in the host.

EIP-7715 host RPCs: wallet_requestExecutionPermissions, wallet_revokeExecutionPermission (grant consent and on-chain revoke are wallet-driven).

Hard rules

• Never embed the Signing Layer iframe from the Host — always Host → Branding → Signing.
• Prefer the published wallet URL in production; point at a local Branding origin only while developing this repo.
• Theme with configure; do not ask integrators to fork CSS for basic brand colors / product name.
• Use focusWallet / unfocusWallet for host-driven single-asset flows; do not expose mode switching in the wallet UI.
• Use addAsset when the host wants a lasting Balances entry; expect a confirm modal (contrast with focusWallet).