ThetanutsWalletOpenAPI

Integration notes

A hosted authentication and encrypted-storage service for the central wallet and registered independent applications. Ranger is the first embedded client.

Central wallet

The user dashboard at https://wallet.thetanuts.finance is its own tenant and WebAuthn RP. It can create, import, switch, export and passkey-protect EOAs in one central keyring. It cannot read legacy keys from another origin. Users must explicitly import a recovery key.

Ranger can use the central keyring through the opt-in popup connector at /connect. The popup requires explicit address sharing and independently decodes each supported Base transaction. It returns the address and transaction hash only. The pilot supports USDC approval to the fixed OptionBook and canonical Ranger orders; ETH is required for gas. Dapp paymaster construction and bundler code remain in the dapp; remote approval for its 7702 and user-operation signatures is a later capability.

Service boundary

The browser generates and imports EOA keys, evaluates WebAuthn PRF, encrypts vaults, decrypts keys and signs transactions. The server stores encrypted vault records, public WebAuthn verification data, and short-lived authentication and revision metadata. The server does not receive PRF outputs, private keys or recovery keys. This service is not a transaction signer or a smart-account service.

The service protects encrypted data at rest. An unlocked wallet trusts the client application's scripts. The API's separate origin does not protect a key from malicious code inside the client page.

Register an embedded client

Registration is an operator-reviewed configuration change. Each embedded application needs an exact HTTPS origin, a host-scoped WebAuthn RP ID and a separate tenant namespace. Ranger uses origin https://ranger.thetanuts.finance and RP ID ranger.thetanuts.finance. The API origin is https://wallet.thetanuts.finance. No wildcard origins, shared parent-domain RP, iframe login or public self-registration is supported. An embedded client must be configured in both service and copied client modules before it is enabled. A central connector client also needs a reviewed exact origin and transaction policy.

Client requirements

  1. Use discoverable passkeys with required user verification. Verify actual PRF output before calling a wallet encrypted.
  2. Serialize only the specified WebAuthn fields. Never upload PublicKeyCredential.toJSON() or unfiltered extension results: these can include the PRF encryption secret.
  3. Use the version 2 encrypted envelope, fresh IVs, context-bound AES-GCM and per-passkey root-key wrapping. Derive the EOA address again after decryption.
  4. Keep session tokens and decrypted keys in memory. Locking must invalidate signers, pending prompts and pending transactions. Never log credentials, keys, PRF output, ciphertext bodies or authentication tokens.
  5. Use credentials: omit and the exact-origin CORS contract. Every write needs an expected revision and fresh assertion bound to the payload digest. Read back and decrypt before reporting a save complete.
  6. Import wallets additively. Keep a legacy plaintext source until the encrypted record is committed and read back successfully. Preserve unreadable storage.
  7. Pin executable dependencies and enforce a restrictive CSP. Do not add analytics or arbitrary third-party code to a page that holds keys.
  8. Require users to save each EOA private key separately. A synced passkey is not a universal recovery guarantee. Provide an external-wallet fallback if PRF is unavailable.

Independent applications

Each embedded subDAO owns a reviewed copy of the client modules and its site configuration. Vaults and credentials are separate across RPs. Users may explicitly import the same EOA key into another application, including an exported Odette key. The service does not share wallets automatically across sites. The central connector keeps the key and transaction confirmation at the wallet origin. The connector does not work around WebAuthn RP rules.

Testing and rollout

Use the exact registered HTTPS origin for passkey tests. The shared thetanuts.finance/dev/ origin is not registered and cannot test Ranger's RP. Never use localhost for this integration. Test real mobile and desktop passkeys, a second device, unsupported PRF, cancellation, recovery, race conditions and both direct and paymaster signing. Deployment and new enrollment are separately controlled. Enrollment is disabled by default.

Protocol API: version 1. Encrypted envelope: version 2. Do not reinterpret unknown versions. See the API contract and current limitations.