Skip to main content

Advanced Embedded Wallet Features

Beyond core auth and Send/Swap/Receive, 1Claw offers treasury primitives for fintech-style products: tracked deposits, off-chain ledgers, hierarchical orgs, and enterprise custody options.

Deposit destinations​

Unique inbound addresses for attributing deposits and firing webhooks when funds arrive.

const { data } = await client.depositDestinations.create({
  chain: "ethereum",
  label: "Invoice #1042",
  treasury_wallet_id: walletUuid, // optional; reuse existing wallet address
  auto_credit_account_id: internalAccountUuid, // optional
});
// data.address, data.id, data.status
EndpointDescription
POST /v1/deposit-destinationsCreate destination
GET /v1/deposit-destinationsList (?chain=, ?status=)
GET /v1/deposit-destinations/{id}Detail + deposit events
PATCH /v1/deposit-destinations/{id}Update status (active, paused, archived)

Human-only. Background monitor records deposit_events and emits wallet.transfer.received webhooks on confirmation.

Use case: Per-checkout deposit address in a marketplace; auto-credit an internal account when confirmed.

Internal accounts (ledger)​

Gas-free instant transfers between named accounts within the same org — double-entry bookkeeping without on-chain fees.

const { data: account } = await client.internalAccounts.create({
  name: "USD Float",
  description: "Platform liquidity",
});

await client.internalAccounts.transfer({
  from_account_id: fromId,
  to_account_id: toId,
  asset: "USDC",
  amount: "100.00",
  memo: "Payout batch 7",
});

Pass an Idempotency-Key header on the HTTP request for safe retries (recommended for production):

curl -X POST "https://api.1claw.xyz/v1/internal-transfers" \
  -H "Authorization: Bearer $USER_JWT" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "from_account_id": "'"$FROM"'",
    "to_account_id": "'"$TO"'",
    "asset": "USDC",
    "amount": "100.00"
  }'

Allowed assets: USD, USDC, USDT, ETH, EUR (allowlist enforced).

EndpointDescription
POST /v1/internal-accountsCreate account
GET /v1/internal-accountsList with balances
POST /v1/internal-transfersTransfer (caller must own from_account)
GET /v1/internal-accounts/{id}/ledgerPaginated history

Pair with deposit destinations (auto_credit_account_id) for "deposit → ledger credit → user withdrawal" flows.

Sub-organizations​

Enterprise hierarchical isolation — each end-user or business unit gets its own sub-org with separate vaults, agents, and policies under a parent org.

await client.subOrgs.create({
  name: "Acme Corp — Tenant 42",
  description: "Isolated resources",
  billing_model: "user_pays",
});

await client.subOrgs.addUser(subOrgId, { user_id: userUuid });
await client.subOrgs.generateWallets(subOrgId, { chains: ["ethereum"] });

Enable per-user isolation at provision time:

await platform.platform.upsertUser({
  email: "user@example.com",
  external_subject: "tenant:42",
  create_sub_org: true,
});

See Multi-tenant Platform API.

CMEK and MPC custody​

Treasury keys in __treasury-keys use org envelope encryption (AES-256-GCM DEKs wrapped by KMS KEKs). Paid tiers add stronger custody:

MPC (vault-level)​

ModeTier defaultBehavior
XOR 2-of-2 client custodyPro / TeamServer share + client share on read
Shamir 2-of-3 multi-HSMBusiness / EnterpriseGCP + AWS + Azure; no client share required

Enable on a vault: POST /v1/vaults/{id}/mpc with { custody_mode, providers? }.

Details: MPC.

CMEK (Business / Enterprise)​

Customer-managed AES-256-GCM layer — your key never leaves your environment; only SHA-256 fingerprint stored server-side.

  • POST /v1/vaults/{id}/cmek — enable
  • POST /v1/vaults/{id}/cmek-rotate — batch re-wrap with X-CMEK-Old-Key / X-CMEK-New-Key

Details: CMEK.

Treasury vault specifics

__treasury-keys MPC mode is auto-selected from billing tier at first wallet generation. CMEK applies when enabled on the underlying vault infrastructure your org uses for treasury storage.

TEE signing (agents, not treasury sends)​

Human treasury sends execute in Vault with HSM-backed keys. Optional TEE routing applies to agent Intents API traffic via Shroud (intents_require_tee, execution_require_tee) — not the standard embedded-wallet send path.

Attestation: GET https://shroud.1claw.xyz/v1/shroud/attestation

See Security overview and Trust model comparison.

Portfolio aggregation​

Unified balance view across treasury wallets, agent signing keys, and smart accounts:

const { data } = await client.portfolio.get({
  chains: "ethereum,solana",
  include_tokens: true,
});

Useful for dashboard-style apps serving power users with both embedded wallets and agents.

Roadmap and v0.53.1 notes​

Wallet access policies (live API)​

Role-based grants for send, swap, balance view, and export are available via:

  • POST/GET/DELETE /v1/treasury/wallets/access-policies
  • Dashboard: Settings → Wallet Access

See Wallet access policies. Runtime enforcement on every treasury send/swap path is part of the v0.53.1 parity sprint — spend policies remain the primary cap for embedded end-user sends today.

Credential recovery (org admin)​

Org owners can configure MFA/passkey recovery escape hatches (domain/credential_recovery.rs). Approve + delayed execute flow; requires org owner/admin. No end-user self-service API yet — watch Changelog 2026.

Shamir org KEK (Business+)​

Business/Enterprise orgs can configure Shamir-split org KEKs for multi-HSM custody. Reconstruct forwards to Shroud TEE when configured. Operator runbook: internal docs.

Migration from other wallet providers​

Last updated on