@capxul/sdk 0.1.0-alpha.3 → 0.1.0-alpha.4

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # @capxul/sdk
 
+## 0.1.0-alpha.4
+
+### Minor Changes
+
+- Post-alpha hardening — WAVE 1 + WAVE 2 cumulative
+
+  **WAVE 1 (merged 2026-05-03 12:44Z):**
+  - S2 story 1: wire onboarding readback hooks (#469) — `me.update`, `accounts.retrieve`, `accounts.update`, `useAccount`, `useSafe`
+  - S3 phase 1: Ink reference CLI scaffold + `auth+me` end-to-end against live alpha-3 Convex (#470). Stickiness gate (D3) fired.
+  - S5: split `CapxulProvider` into public single-input `BrowserCapxulConfig` + test-only `CapxulTestProvider` from `@capxul/sdk-react/proof` (#473). Q1 lock honored. 7 type-level provider-shape guards including `@ts-expect-error` against test-provider leaking to public barrel.
+
+  **WAVE 2 (merged 2026-05-03 12:54-13:16Z):**
+  - S3 phase 2: per-domain CLI commands closing #458 (#476) — `account retrieve/update`, `safe retrieve`, `payment retrieve`, `withdrawal retrieve/list`. 12/12 agent-driver tests pass.
+  - S2 story 2: `capxul.tokenTransfers.*` non-canonical SDK namespace (#479) — Option A per #477 (canon-aligned `transfers.*` shape deferred to alpha.5+ pending backend canon work). New `useTokenTransfers` + `useTokenTransfer` hooks; new `getByTxLogIndex` backend query. Hook proof matrix length unchanged at 41 (non-canonical hooks deliberately excluded).
+
+  **S1 (#456) closed no-op** — alpha publish infrastructure (tsup, lazy-DX, transport state machine, npm metadata, READMEs, CHANGELOG, changesets, OIDC release workflow) physically merged into `api-first` via PRs #449-#452 earlier the same day; the slice merge produced 0 file changes per clean-room probe.
+
+  **Friction issues filed for alpha.4+ polish:**
+  - #474 — `me.get` returns `NOT_IMPLEMENTED` when `config.data` is undefined; should be `NOT_AUTHENTICATED`.
+  - #475 — `@capxul/sdk/headless` slim entry point excludes xstate flow machines + brand constructors (1.6 MB → much smaller).
+  - #477 / #478 — `transfers.*` / `balanceLedger.*` / `treasury` canon-shape alignment with indexer feed.
+  - #471 — Vercel-capxul-web preview-deploy systemic failure on api-first base (separate from epic).
+
 ## 0.1.0-alpha.3
 
 ### Patch Changes

package/dist/{client-CwcnMbGv.d.cts → client-CXRKtbfn.d.cts}

@@ -2,7 +2,7 @@ import { Account as Account$1 } from 'viem';
 import { AnyStateMachine } from 'xstate';
 import { A as AccountId, S as SafeId, c as KycProfileId, b as ExternalAccountId, f as SubAccountId, d as OrganizationId, a as ApiKeyId, X as TimestampIso, D as DocumentId, O as OperationId, P as PaymentId, g as TransferId, k as WithdrawalId, W as WebhookEndpointId, j as WebhookEventId, M as MemberId, K as KybProfileId, V as VirtualAccountId, i as VirtualCardId } from './next-action-DkrwXYay.cjs';
 import { d as CapxulResult, C as CapxulError } from './errors-GgKrSUKp.cjs';
-import { A as Account, U as UserIdentifier, a as AccountLookupResult, S as Safe, i as KycProfile, E as ExternalAccount, L as List, v as SubAccount, B as BalanceLedgerEntry, b as ApiKey, D as Document, O as Operation, l as OperationStatus, k as Money, C as CreatePaymentResult, o as Payment, F as TransferEndpoint, f as CreateTransferResult, y as Transfer, g as CreateWithdrawalResult, _ as Withdrawal, Y as WebhookEndpoint, Z as WebhookEvent, n as Organization, J as Treasury, M as Member, K as KybProfile, V as VirtualAccount, Q as VirtualCard } from './types-z4VLz9rS.cjs';
+import { A as Account, U as UserIdentifier, a as AccountLookupResult, S as Safe, i as KycProfile, E as ExternalAccount, L as List, v as SubAccount, B as BalanceLedgerEntry, b as ApiKey, D as Document, O as Operation, l as OperationStatus, k as Money, C as CreatePaymentResult, o as Payment, F as TransferEndpoint, f as CreateTransferResult, y as Transfer, g as CreateWithdrawalResult, _ as Withdrawal, Y as WebhookEndpoint, Z as WebhookEvent, n as Organization, J as Treasury, M as Member, K as KybProfile, V as VirtualAccount, Q as VirtualCard } from './types-DVWojoy4.cjs';
 import * as types from '@repo/api-contract/gen/types';
 
 /**
@@ -53,10 +53,10 @@ type AccountCreateExternalAccountInput = {
     readonly panToken?: string;
     readonly last4?: string;
 };
-type RetrieveCodes$d = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "NOT_FOUND";
+type RetrieveCodes$e = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "NOT_FOUND";
 type LookupCodes = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "INVALID_INPUT";
 type UpdateCodes$1 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "NOT_FOUND" | "INVALID_INPUT";
-type ListCodes$a = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "INVALID_INPUT";
+type ListCodes$b = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "INVALID_INPUT";
 type SafeRetrieveCodes$1 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "NOT_FOUND" | "SAFE_NOT_READY";
 type RemoveCodes$5 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "NOT_FOUND";
 type AccountSafesClient = {
@@ -64,32 +64,32 @@ type AccountSafesClient = {
 };
 type AccountKycProfilesClient = {
     readonly create: (input: AccountCreateKycProfileInput) => Promise<CapxulResult<KycProfile, UpdateCodes$1>>;
-    readonly retrieve: (kycProfileId: KycProfileId) => Promise<CapxulResult<KycProfile, RetrieveCodes$d>>;
+    readonly retrieve: (kycProfileId: KycProfileId) => Promise<CapxulResult<KycProfile, RetrieveCodes$e>>;
 };
 type AccountExternalAccountsClient = {
     readonly create: (input: AccountCreateExternalAccountInput) => Promise<CapxulResult<ExternalAccount, UpdateCodes$1>>;
     readonly list: (input: {
         readonly accountId: AccountId;
-    } & AccountListInput) => Promise<CapxulResult<List<ExternalAccount>, ListCodes$a>>;
-    readonly retrieve: (externalAccountId: ExternalAccountId) => Promise<CapxulResult<ExternalAccount, RetrieveCodes$d>>;
+    } & AccountListInput) => Promise<CapxulResult<List<ExternalAccount>, ListCodes$b>>;
+    readonly retrieve: (externalAccountId: ExternalAccountId) => Promise<CapxulResult<ExternalAccount, RetrieveCodes$e>>;
     readonly remove: (externalAccountId: ExternalAccountId) => Promise<CapxulResult<void, RemoveCodes$5>>;
 };
 type AccountSubAccountsClient = {
     readonly create: (input: AccountCreateSubAccountInput) => Promise<CapxulResult<SubAccount, UpdateCodes$1>>;
     readonly list: (input: {
         readonly accountId: AccountId;
-    } & AccountListInput) => Promise<CapxulResult<List<SubAccount>, ListCodes$a>>;
-    readonly retrieve: (subAccountId: SubAccountId) => Promise<CapxulResult<SubAccount, RetrieveCodes$d>>;
+    } & AccountListInput) => Promise<CapxulResult<List<SubAccount>, ListCodes$b>>;
+    readonly retrieve: (subAccountId: SubAccountId) => Promise<CapxulResult<SubAccount, RetrieveCodes$e>>;
     readonly remove: (subAccountId: SubAccountId) => Promise<CapxulResult<void, RemoveCodes$5>>;
 };
 type AccountBalanceLedgerClient = {
     readonly list: (input: {
         readonly accountId: AccountId;
-    } & AccountListInput) => Promise<CapxulResult<List<BalanceLedgerEntry>, ListCodes$a>>;
-    readonly retrieve: (entryId: string) => Promise<CapxulResult<BalanceLedgerEntry, RetrieveCodes$d>>;
+    } & AccountListInput) => Promise<CapxulResult<List<BalanceLedgerEntry>, ListCodes$b>>;
+    readonly retrieve: (entryId: string) => Promise<CapxulResult<BalanceLedgerEntry, RetrieveCodes$e>>;
 };
 type AccountsClient = {
-    readonly retrieve: (accountId: AccountId) => Promise<CapxulResult<Account, RetrieveCodes$d>>;
+    readonly retrieve: (accountId: AccountId) => Promise<CapxulResult<Account, RetrieveCodes$e>>;
     readonly lookup: (input: AccountLookupInput) => Promise<CapxulResult<AccountLookupResult, LookupCodes>>;
     readonly update: (input: {
         readonly accountId: AccountId;
@@ -125,9 +125,9 @@ type ApiKeysListInput = {
 };
 type ApiKeysRevokeInput = ApiKeysRetrieveInput;
 type CreateCodes$8 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "INVALID_INPUT" | "RATE_LIMITED" | "NETWORK_ERROR";
-type RetrieveCodes$c = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "NOT_FOUND";
-type ListCodes$9 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "INVALID_INPUT";
-type RevokeCodes = RetrieveCodes$c;
+type RetrieveCodes$d = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "NOT_FOUND";
+type ListCodes$a = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "INVALID_INPUT";
+type RevokeCodes = RetrieveCodes$d;
 /**
  * Shape returned by `organizations.apiKeys.create` — the one-time
  * secret `value` is included here and omitted from every subsequent
@@ -138,8 +138,8 @@ type ApiKeyCreateResult = ApiKey & {
 };
 type ApiKeysClient = {
     readonly create: (input: ApiKeysCreateInput) => Promise<CapxulResult<ApiKeyCreateResult, CreateCodes$8>>;
-    readonly retrieve: (input: ApiKeysRetrieveInput) => Promise<CapxulResult<ApiKey, RetrieveCodes$c>>;
-    readonly list: (input: ApiKeysListInput) => Promise<CapxulResult<List<ApiKey>, ListCodes$9>>;
+    readonly retrieve: (input: ApiKeysRetrieveInput) => Promise<CapxulResult<ApiKey, RetrieveCodes$d>>;
+    readonly list: (input: ApiKeysListInput) => Promise<CapxulResult<List<ApiKey>, ListCodes$a>>;
     readonly revoke: (input: ApiKeysRevokeInput) => Promise<CapxulResult<ApiKey, RevokeCodes>>;
 };
 
@@ -260,19 +260,19 @@ type OrgDocumentsCancelInput = {
     readonly documentId: DocumentId;
 };
 type CreateCodes$7 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "INVALID_INPUT" | "IDEMPOTENCY_CONFLICT" | "RATE_LIMITED" | "NETWORK_ERROR";
-type RetrieveCodes$b = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "NOT_FOUND";
-type ListCodes$8 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "INVALID_INPUT";
+type RetrieveCodes$c = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "NOT_FOUND";
+type ListCodes$9 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "INVALID_INPUT";
 type CancelCodes$1 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "NOT_FOUND" | "OPERATION_CANCELED";
 type DocumentsClient = {
     readonly create: (input: DocumentsCreateInput) => Promise<CapxulResult<Document, CreateCodes$7>>;
-    readonly retrieve: (documentId: DocumentId) => Promise<CapxulResult<Document, RetrieveCodes$b>>;
-    readonly list: (input?: DocumentsListInput) => Promise<CapxulResult<List<Document>, ListCodes$8>>;
+    readonly retrieve: (documentId: DocumentId) => Promise<CapxulResult<Document, RetrieveCodes$c>>;
+    readonly list: (input?: DocumentsListInput) => Promise<CapxulResult<List<Document>, ListCodes$9>>;
     readonly cancel: (documentId: DocumentId) => Promise<CapxulResult<Document, CancelCodes$1>>;
 };
 type OrgDocumentsClient = {
     readonly create: (input: OrgDocumentsCreateInput) => Promise<CapxulResult<Document, CreateCodes$7>>;
-    readonly retrieve: (input: OrgDocumentsRetrieveInput) => Promise<CapxulResult<Document, RetrieveCodes$b>>;
-    readonly list: (input: OrgDocumentsListInput) => Promise<CapxulResult<List<Document>, ListCodes$8>>;
+    readonly retrieve: (input: OrgDocumentsRetrieveInput) => Promise<CapxulResult<Document, RetrieveCodes$c>>;
+    readonly list: (input: OrgDocumentsListInput) => Promise<CapxulResult<List<Document>, ListCodes$9>>;
     readonly cancel: (input: OrgDocumentsCancelInput) => Promise<CapxulResult<Document, CancelCodes$1>>;
 };
 
@@ -286,10 +286,10 @@ type OrgDocumentsClient = {
  * ID without scoping.
  */
 
-type RetrieveCodes$a = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "NOT_FOUND";
-type RemoveCodes$4 = RetrieveCodes$a;
+type RetrieveCodes$b = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "NOT_FOUND";
+type RemoveCodes$4 = RetrieveCodes$b;
 type ExternalAccountsClient = {
-    readonly retrieve: (externalAccountId: ExternalAccountId) => Promise<CapxulResult<ExternalAccount, RetrieveCodes$a>>;
+    readonly retrieve: (externalAccountId: ExternalAccountId) => Promise<CapxulResult<ExternalAccount, RetrieveCodes$b>>;
     readonly remove: (externalAccountId: ExternalAccountId) => Promise<CapxulResult<void, RemoveCodes$4>>;
 };
 
@@ -329,10 +329,10 @@ type OperationsWaitInput = {
     readonly timeoutSeconds?: number;
     readonly pollIntervalMs?: number;
 };
-type RetrieveCodes$9 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "NOT_FOUND";
-type WaitCodes = RetrieveCodes$9 | "OPERATION_TIMEOUT";
+type RetrieveCodes$a = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "NOT_FOUND";
+type WaitCodes = RetrieveCodes$a | "OPERATION_TIMEOUT";
 type OperationsClient = {
-    readonly retrieve: (operationId: OperationId) => Promise<CapxulResult<Operation, RetrieveCodes$9>>;
+    readonly retrieve: (operationId: OperationId) => Promise<CapxulResult<Operation, RetrieveCodes$a>>;
     readonly wait: (operationId: OperationId, input?: OperationsWaitInput) => Promise<CapxulResult<Operation, WaitCodes>>;
 };
 
@@ -393,17 +393,17 @@ type OrgPaymentsListInput = {
 };
 type CreateCodes$6 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "INVALID_INPUT" | "INVALID_RECIPIENT" | "INSUFFICIENT_BALANCE" | "IDEMPOTENCY_CONFLICT" | "RATE_LIMITED" | "NETWORK_ERROR";
 type OrgCreateCodes = CreateCodes$6 | "POLICY_DENIED" | "SAFE_NOT_READY";
-type RetrieveCodes$8 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "NOT_FOUND";
-type ListCodes$7 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "INVALID_INPUT";
+type RetrieveCodes$9 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "NOT_FOUND";
+type ListCodes$8 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "INVALID_INPUT";
 type PaymentsClient = {
     readonly create: (input: PaymentsCreateInput) => Promise<CapxulResult<CreatePaymentResult, CreateCodes$6>>;
-    readonly retrieve: (paymentId: PaymentId) => Promise<CapxulResult<Payment, RetrieveCodes$8>>;
-    readonly list: (input?: PaymentsListInput) => Promise<CapxulResult<List<Payment>, ListCodes$7>>;
+    readonly retrieve: (paymentId: PaymentId) => Promise<CapxulResult<Payment, RetrieveCodes$9>>;
+    readonly list: (input?: PaymentsListInput) => Promise<CapxulResult<List<Payment>, ListCodes$8>>;
 };
 type OrgPaymentsClient = {
     readonly create: (input: OrgPaymentsCreateInput) => Promise<CapxulResult<CreatePaymentResult, OrgCreateCodes>>;
-    readonly retrieve: (input: OrgPaymentsRetrieveInput) => Promise<CapxulResult<Payment, RetrieveCodes$8>>;
-    readonly list: (input: OrgPaymentsListInput) => Promise<CapxulResult<List<Payment>, ListCodes$7>>;
+    readonly retrieve: (input: OrgPaymentsRetrieveInput) => Promise<CapxulResult<Payment, RetrieveCodes$9>>;
+    readonly list: (input: OrgPaymentsListInput) => Promise<CapxulResult<List<Payment>, ListCodes$8>>;
 };
 
 /**
@@ -452,34 +452,56 @@ type OrgTransfersCancelInput = {
     readonly transferId: TransferId;
 };
 type CreateCodes$5 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "INVALID_INPUT" | "INSUFFICIENT_BALANCE" | "IDEMPOTENCY_CONFLICT" | "RATE_LIMITED" | "NETWORK_ERROR";
-type RetrieveCodes$7 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "NOT_FOUND";
-type ListCodes$6 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "INVALID_INPUT";
+type RetrieveCodes$8 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "NOT_FOUND";
+type ListCodes$7 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "INVALID_INPUT";
 type ConfirmCodes = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "NOT_FOUND" | "QUOTE_EXPIRED" | "QUOTE_NOT_FOUND";
 type CancelCodes = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "NOT_FOUND" | "OPERATION_CANCELED";
 type TransfersClient = {
     readonly create: (input: TransfersCreateInput) => Promise<CapxulResult<CreateTransferResult, CreateCodes$5>>;
-    readonly retrieve: (transferId: TransferId) => Promise<CapxulResult<Transfer, RetrieveCodes$7>>;
-    readonly list: (input?: TransfersListInput) => Promise<CapxulResult<List<Transfer>, ListCodes$6>>;
+    readonly retrieve: (transferId: TransferId) => Promise<CapxulResult<Transfer, RetrieveCodes$8>>;
+    readonly list: (input?: TransfersListInput) => Promise<CapxulResult<List<Transfer>, ListCodes$7>>;
     readonly confirm: (input: TransfersConfirmInput) => Promise<CapxulResult<Transfer, ConfirmCodes>>;
     readonly cancel: (transferId: TransferId) => Promise<CapxulResult<Transfer, CancelCodes>>;
 };
 type OrgTransfersClient = {
     readonly create: (input: OrgTransfersCreateInput) => Promise<CapxulResult<CreateTransferResult, CreateCodes$5>>;
-    readonly retrieve: (input: OrgTransfersRetrieveInput) => Promise<CapxulResult<Transfer, RetrieveCodes$7>>;
-    readonly list: (input: OrgTransfersListInput) => Promise<CapxulResult<List<Transfer>, ListCodes$6>>;
+    readonly retrieve: (input: OrgTransfersRetrieveInput) => Promise<CapxulResult<Transfer, RetrieveCodes$8>>;
+    readonly list: (input: OrgTransfersListInput) => Promise<CapxulResult<List<Transfer>, ListCodes$7>>;
     readonly confirm: (input: OrgTransfersConfirmInput) => Promise<CapxulResult<Transfer, ConfirmCodes>>;
     readonly cancel: (input: OrgTransfersCancelInput) => Promise<CapxulResult<Transfer, CancelCodes>>;
 };
 
 /**
  * Withdrawals domain — funds exit Capxul via an `external_account` per
- * sdk-surface.md §1a + §4.52.
+ * sdk-surface.md §1a + §4.52 + withdrawal-orchestration.mdx (slice 1
+ * of Withdrawals v1, #440).
+ *
+ * Slice 1 NOTE — transitional input shape:
+ * Until the `external_accounts` resource lands (slice 1.x or v2), the
+ * destination input includes a `kind` field so the backend + SDK can
+ * route to the chain_wallet rail without a real external_accounts
+ * lookup. When the resource lands, `kind` becomes optional / ignored
+ * and the kind is inferred from the resolved row.
+ *
+ * Slice 1 NOTE — chain_wallet rail integration:
+ * For evm destinations, the `externalAccountId` is treated as the
+ * destination address (must start with `0x`) so the chain_wallet rail
+ * can call `transferAsOwner` directly. For solana / starknet the SDK
+ * accepts the create call but does NOT execute the rail submission —
+ * the row stays in `processing` until external_accounts lands. The
+ * caller can transition it via `markFailed` if needed.
  */
 
 type WithdrawalsCreateInput = {
     readonly amount: Money;
     readonly destination: {
         readonly externalAccountId: ExternalAccountId;
+        /**
+         * Slice 1 transitional field. Required until the
+         * `external_accounts` resource lands; will become optional / ignored
+         * when the resource is the source of truth for kind.
+         */
+        readonly kind: "evm" | "solana" | "starknet" | "bank" | "momo" | "card_payout";
     };
     readonly source?: {
         readonly subAccountId: SubAccountId;
@@ -505,17 +527,17 @@ type OrgWithdrawalsListInput = {
     readonly cursor?: string;
 };
 type CreateCodes$4 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "INVALID_INPUT" | "INSUFFICIENT_BALANCE" | "IDEMPOTENCY_CONFLICT" | "KYC_REQUIRED" | "POLICY_DENIED" | "RATE_LIMITED" | "NETWORK_ERROR";
-type RetrieveCodes$6 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "NOT_FOUND";
-type ListCodes$5 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "INVALID_INPUT";
+type RetrieveCodes$7 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "NOT_FOUND";
+type ListCodes$6 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "INVALID_INPUT";
 type WithdrawalsClient = {
     readonly create: (input: WithdrawalsCreateInput) => Promise<CapxulResult<CreateWithdrawalResult, CreateCodes$4>>;
-    readonly retrieve: (withdrawalId: WithdrawalId) => Promise<CapxulResult<Withdrawal, RetrieveCodes$6>>;
-    readonly list: (input?: WithdrawalsListInput) => Promise<CapxulResult<List<Withdrawal>, ListCodes$5>>;
+    readonly retrieve: (withdrawalId: WithdrawalId) => Promise<CapxulResult<Withdrawal, RetrieveCodes$7>>;
+    readonly list: (input?: WithdrawalsListInput) => Promise<CapxulResult<List<Withdrawal>, ListCodes$6>>;
 };
 type OrgWithdrawalsClient = {
     readonly create: (input: OrgWithdrawalsCreateInput) => Promise<CapxulResult<CreateWithdrawalResult, CreateCodes$4>>;
-    readonly retrieve: (input: OrgWithdrawalsRetrieveInput) => Promise<CapxulResult<Withdrawal, RetrieveCodes$6>>;
-    readonly list: (input: OrgWithdrawalsListInput) => Promise<CapxulResult<List<Withdrawal>, ListCodes$5>>;
+    readonly retrieve: (input: OrgWithdrawalsRetrieveInput) => Promise<CapxulResult<Withdrawal, RetrieveCodes$7>>;
+    readonly list: (input: OrgWithdrawalsListInput) => Promise<CapxulResult<List<Withdrawal>, ListCodes$6>>;
 };
 
 /**
@@ -541,9 +563,9 @@ type WebhookEndpointsListInput = {
 };
 type WebhookEndpointsRemoveInput = WebhookEndpointsRetrieveInput;
 type CreateCodes$3 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "INVALID_INPUT" | "RATE_LIMITED" | "NETWORK_ERROR";
-type RetrieveCodes$5 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "NOT_FOUND";
-type ListCodes$4 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "INVALID_INPUT";
-type RemoveCodes$3 = RetrieveCodes$5;
+type RetrieveCodes$6 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "NOT_FOUND";
+type ListCodes$5 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "INVALID_INPUT";
+type RemoveCodes$3 = RetrieveCodes$6;
 /**
  * Shape returned by `organizations.webhookEndpoints.create` — the
  * one-time `signingSecret` is included here and omitted from every
@@ -554,8 +576,8 @@ type WebhookEndpointCreateResult = WebhookEndpoint & {
 };
 type WebhookEndpointsClient = {
     readonly create: (input: WebhookEndpointsCreateInput) => Promise<CapxulResult<WebhookEndpointCreateResult, CreateCodes$3>>;
-    readonly retrieve: (input: WebhookEndpointsRetrieveInput) => Promise<CapxulResult<WebhookEndpoint, RetrieveCodes$5>>;
-    readonly list: (input: WebhookEndpointsListInput) => Promise<CapxulResult<List<WebhookEndpoint>, ListCodes$4>>;
+    readonly retrieve: (input: WebhookEndpointsRetrieveInput) => Promise<CapxulResult<WebhookEndpoint, RetrieveCodes$6>>;
+    readonly list: (input: WebhookEndpointsListInput) => Promise<CapxulResult<List<WebhookEndpoint>, ListCodes$5>>;
     readonly remove: (input: WebhookEndpointsRemoveInput) => Promise<CapxulResult<void, RemoveCodes$3>>;
 };
 
@@ -576,11 +598,11 @@ type WebhookEventsListInput = {
     readonly endpointId?: string;
     readonly type?: string;
 };
-type RetrieveCodes$4 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "NOT_FOUND";
-type ListCodes$3 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "INVALID_INPUT";
+type RetrieveCodes$5 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "NOT_FOUND";
+type ListCodes$4 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "INVALID_INPUT";
 type WebhookEventsClient = {
-    readonly retrieve: (input: WebhookEventsRetrieveInput) => Promise<CapxulResult<WebhookEvent, RetrieveCodes$4>>;
-    readonly list: (input: WebhookEventsListInput) => Promise<CapxulResult<List<WebhookEvent>, ListCodes$3>>;
+    readonly retrieve: (input: WebhookEventsRetrieveInput) => Promise<CapxulResult<WebhookEvent, RetrieveCodes$5>>;
+    readonly list: (input: WebhookEventsListInput) => Promise<CapxulResult<List<WebhookEvent>, ListCodes$4>>;
 };
 
 /**
@@ -653,8 +675,8 @@ type OrgCreateExternalAccountInput = {
     readonly last4?: string;
 };
 type CreateCodes$2 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "INVALID_INPUT" | "RATE_LIMITED" | "NETWORK_ERROR";
-type RetrieveCodes$3 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "NOT_FOUND";
-type ListCodes$2 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "INVALID_INPUT";
+type RetrieveCodes$4 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "NOT_FOUND";
+type ListCodes$3 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "INVALID_INPUT";
 type UpdateCodes = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "NOT_FOUND" | "INVALID_INPUT";
 /**
  * Org safe retrieve does NOT surface `SAFE_NOT_READY` — a co-member
@@ -669,7 +691,7 @@ type UpdateCodes = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "NOT_FOUND" | "IN
  */
 type SafeRetrieveCodes = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "NOT_FOUND";
 type TreasuryRetrieveCodes = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "NOT_FOUND" | "SAFE_NOT_READY";
-type RemoveCodes$2 = RetrieveCodes$3;
+type RemoveCodes$2 = RetrieveCodes$4;
 type OrgSafesClient = {
     readonly retrieve: (input: OrgSafeRetrieveInput) => Promise<CapxulResult<Safe, SafeRetrieveCodes>>;
 };
@@ -677,23 +699,23 @@ type OrgTreasuryClient = {
     readonly retrieve: (organizationId: OrganizationId) => Promise<CapxulResult<Treasury, TreasuryRetrieveCodes>>;
 };
 type OrgMembersClient = {
-    readonly list: (input: OrgListInput) => Promise<CapxulResult<List<Member>, ListCodes$2>>;
-    readonly retrieve: (input: OrgMemberRetrieveInput) => Promise<CapxulResult<Member, RetrieveCodes$3>>;
+    readonly list: (input: OrgListInput) => Promise<CapxulResult<List<Member>, ListCodes$3>>;
+    readonly retrieve: (input: OrgMemberRetrieveInput) => Promise<CapxulResult<Member, RetrieveCodes$4>>;
     readonly invite: (input: OrgMemberInviteInput) => Promise<CapxulResult<Member, UpdateCodes>>;
     readonly updateRole: (input: OrgMemberUpdateRoleInput) => Promise<CapxulResult<Member, UpdateCodes>>;
     readonly remove: (input: OrgMemberRemoveInput) => Promise<CapxulResult<void, RemoveCodes$2>>;
 };
 type OrgKybProfileClient = {
     readonly start: (input: OrgKybProfileStartInput) => Promise<CapxulResult<KybProfile, CreateCodes$2>>;
-    readonly retrieve: (input: OrgKybProfileRetrieveInput) => Promise<CapxulResult<KybProfile, RetrieveCodes$3>>;
+    readonly retrieve: (input: OrgKybProfileRetrieveInput) => Promise<CapxulResult<KybProfile, RetrieveCodes$4>>;
 };
 type OrgSubAccountsClient = {
     readonly create: (input: OrgCreateSubAccountInput) => Promise<CapxulResult<SubAccount, UpdateCodes>>;
-    readonly list: (input: OrgListInput) => Promise<CapxulResult<List<SubAccount>, ListCodes$2>>;
+    readonly list: (input: OrgListInput) => Promise<CapxulResult<List<SubAccount>, ListCodes$3>>;
     readonly retrieve: (input: {
         readonly organizationId: OrganizationId;
         readonly subAccountId: SubAccountId;
-    }) => Promise<CapxulResult<SubAccount, RetrieveCodes$3>>;
+    }) => Promise<CapxulResult<SubAccount, RetrieveCodes$4>>;
     readonly remove: (input: {
         readonly organizationId: OrganizationId;
         readonly subAccountId: SubAccountId;
@@ -701,28 +723,28 @@ type OrgSubAccountsClient = {
 };
 type OrgExternalAccountsClient = {
     readonly create: (input: OrgCreateExternalAccountInput) => Promise<CapxulResult<ExternalAccount, UpdateCodes>>;
-    readonly list: (input: OrgListInput) => Promise<CapxulResult<List<ExternalAccount>, ListCodes$2>>;
+    readonly list: (input: OrgListInput) => Promise<CapxulResult<List<ExternalAccount>, ListCodes$3>>;
     readonly retrieve: (input: {
         readonly organizationId: OrganizationId;
         readonly externalAccountId: ExternalAccountId;
-    }) => Promise<CapxulResult<ExternalAccount, RetrieveCodes$3>>;
+    }) => Promise<CapxulResult<ExternalAccount, RetrieveCodes$4>>;
     readonly remove: (input: {
         readonly organizationId: OrganizationId;
         readonly externalAccountId: ExternalAccountId;
     }) => Promise<CapxulResult<void, RemoveCodes$2>>;
 };
 type OrgBalanceLedgerClient = {
-    readonly list: (input: OrgListInput) => Promise<CapxulResult<List<BalanceLedgerEntry>, ListCodes$2>>;
+    readonly list: (input: OrgListInput) => Promise<CapxulResult<List<BalanceLedgerEntry>, ListCodes$3>>;
     readonly retrieve: (input: {
         readonly organizationId: OrganizationId;
         readonly entryId: string;
-    }) => Promise<CapxulResult<BalanceLedgerEntry, RetrieveCodes$3>>;
+    }) => Promise<CapxulResult<BalanceLedgerEntry, RetrieveCodes$4>>;
 };
 type OrgApiKeysClient = ApiKeysClient;
 type OrganizationsClient = {
     readonly create: (input: OrganizationsCreateInput) => Promise<CapxulResult<Organization, CreateCodes$2>>;
-    readonly retrieve: (organizationId: OrganizationId) => Promise<CapxulResult<Organization, RetrieveCodes$3>>;
-    readonly list: (input?: OrganizationsListInput) => Promise<CapxulResult<List<Organization>, ListCodes$2>>;
+    readonly retrieve: (organizationId: OrganizationId) => Promise<CapxulResult<Organization, RetrieveCodes$4>>;
+    readonly list: (input?: OrganizationsListInput) => Promise<CapxulResult<List<Organization>, ListCodes$3>>;
     readonly update: (input: OrganizationsUpdateInput) => Promise<CapxulResult<Organization, UpdateCodes>>;
     readonly safes: OrgSafesClient;
     readonly treasury: OrgTreasuryClient;
@@ -879,13 +901,111 @@ declare function makeHttpTransport(config: BrowserCapxulConfig): HttpTransport;
  * `remove` live at the top level.
  */
 
-type RetrieveCodes$2 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "NOT_FOUND";
-type RemoveCodes$1 = RetrieveCodes$2;
+type RetrieveCodes$3 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "NOT_FOUND";
+type RemoveCodes$1 = RetrieveCodes$3;
 type SubAccountsClient = {
-    readonly retrieve: (subAccountId: SubAccountId) => Promise<CapxulResult<SubAccount, RetrieveCodes$2>>;
+    readonly retrieve: (subAccountId: SubAccountId) => Promise<CapxulResult<SubAccount, RetrieveCodes$3>>;
     readonly remove: (subAccountId: SubAccountId) => Promise<CapxulResult<void, RemoveCodes$1>>;
 };
 
+/**
+ * **NON-CANONICAL surface.**
+ *
+ * `capxul.tokenTransfers.*` exposes the indexer's raw on-chain ERC-20
+ * transfer rows directly to consumers, backed by
+ * `packages/backend/convex/tokenTransfers/queries.ts`. Authorized at
+ * `slice/02-story2-balance` per the conductor's Option-A verdict —
+ * the canonical SDK `transfers.*` namespace assumes a cross-custody
+ * internal-move shape (`Transfer = { source, destination, fx,
+ * operation, ... }`) that has no canon-aligned backing query yet.
+ * Surfacing the on-chain feed under a separate, clearly-marked
+ * non-canonical namespace lets the Ink CLI's activity dashboard
+ * progress without forcing canon synthesis.
+ *
+ * **NOT in `packages/api-contract`.** Do NOT use this surface as the
+ * basis for new canon. When `transfers.*` shape alignment lands
+ * (post-alpha.4 follow-up issue), the canonical `transfers.*` will
+ * subsume this and `tokenTransfers.*` becomes a deprecation alias.
+ *
+ * Stub families that REMAIN deferred at this slice
+ * (per `[DEFERRED-CANON]` markers in
+ * `.claude/worktrees/post-alpha-wire2/.progress.txt`):
+ * - `transfers.{create,retrieve,list,confirm,cancel}` — canon shape mismatch
+ * - `accounts.balanceLedger.{list,retrieve}` — no canon backing query
+ * - `organizations.balanceLedger.*` — no canon backing query
+ * - `organizations.transfers.*` — canon shape mismatch
+ * - `organizations.treasury.retrieve` — backing query has different shape
+ */
+
+/**
+ * Branded id for an on-chain `tokenTransfer` row. Backed by the
+ * Convex document id; the brand prevents accidental swaps with other
+ * SDK ids without leaking the document-id constraint into call sites.
+ *
+ * Returned in `TokenTransfer.id` for clients that want a stable
+ * back-reference; the canonical lookup key is the
+ * `(txHash, logIndex)` composite used by `retrieve`.
+ */
+type TokenTransferId = string & {
+    readonly __capxulTokenTransferIdBrand: "TokenTransferId";
+};
+declare const toTokenTransferId: (raw: string) => TokenTransferId;
+/**
+ * Raw on-chain ERC-20 transfer row. Shape mirrors
+ * `tokenTransfers/queries.ts` `list` / `getByTxLogIndex` output. The
+ * primitive fields (`txHash`, `tokenAddress`, etc.) match
+ * `@repo/api-contract` conventions — `string` for hashes/addresses,
+ * `number` for block + chain ids — so consumers don't need to import
+ * a brand surface that isn't in the SDK's published deps.
+ */
+type TokenTransfer = {
+    readonly id: TokenTransferId;
+    readonly object: "token_transfer";
+    readonly direction: "in" | "out";
+    /** Token-units string ("123456" not "1.23456"). Decimals carried in `tokenDecimals`. */
+    readonly amount: string;
+    readonly tokenSymbol: string;
+    readonly tokenDecimals: number;
+    readonly tokenAddress: string;
+    readonly counterpartyName: string | null;
+    readonly counterpartyAddress: string;
+    readonly description: string;
+    /** Block timestamp in epoch milliseconds. */
+    readonly createdAt: number;
+    readonly txHash: string;
+    readonly blockNumber: number;
+    readonly chainId: number;
+};
+type TokenTransfersListPage = {
+    readonly object: "list";
+    readonly data: readonly TokenTransfer[];
+    readonly page: {
+        readonly hasMore: boolean;
+        /** Block-timestamp cursor (epoch ms) for the next page; null when exhausted. */
+        readonly nextCursor: number | null;
+    };
+    /** Caller's display currency. The backend echoes it so renderers don't need a second round-trip. */
+    readonly displayCurrency: string;
+};
+type TokenTransfersListInput = {
+    readonly limit?: number;
+    /** Block-timestamp cursor (epoch ms) returned in the previous page's `page.nextCursor`. */
+    readonly cursor?: number;
+    readonly direction?: "in" | "out";
+};
+type TokenTransfersRetrieveInput = {
+    readonly txHash: string;
+    readonly logIndex: number;
+    /** Optional chain filter. When omitted, the first index hit wins (single-chain default). */
+    readonly chainId?: number;
+};
+type ListCodes$2 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "INVALID_INPUT";
+type RetrieveCodes$2 = "NOT_AUTHENTICATED" | "PERMISSION_DENIED" | "NOT_FOUND";
+type TokenTransfersClient = {
+    readonly list: (input?: TokenTransfersListInput) => Promise<CapxulResult<TokenTransfersListPage, ListCodes$2>>;
+    readonly retrieve: (input: TokenTransfersRetrieveInput) => Promise<CapxulResult<TokenTransfer, RetrieveCodes$2>>;
+};
+
 /**
  * Virtual accounts domain — International Bank Account Number (IBAN)-
  * bearing receive rails per sdk-surface.md §1a + §4.51.
@@ -1093,6 +1213,13 @@ type CapxulClient = {
     readonly organizations: OrganizationsClient;
     readonly payments: PaymentsClient;
     readonly transfers: TransfersClient;
+    /**
+     * **NON-CANONICAL.** On-chain ERC-20 transfer feed (raw indexer
+     * rows). NOT part of `packages/api-contract`. Slated for
+     * deprecation when canonical `transfers.*` shape alignment lands.
+     * See `core/token-transfers.ts` for the doc-comment contract.
+     */
+    readonly tokenTransfers: TokenTransfersClient;
     readonly withdrawals: WithdrawalsClient;
     readonly documents: DocumentsClient;
     readonly subAccounts: SubAccountsClient;
@@ -1122,4 +1249,4 @@ type CapxulClient = {
  */
 declare function createCapxulClient(config?: CapxulConfig): CapxulClient;
 
-export { type AccountProvisionPersonalInput as A, type BrowserCapxulConfig as B, type CapxulClient as C, type DocumentsClient as D, type ExternalAccountsClient as E, type HttpTransport as H, type LocalPrivateKeySignerProvider as L, type MeClient as M, type OperationsClient as O, type PaymentsClient as P, type Session as S, type TransfersClient as T, type VirtualAccountsClient as V, type WebhookEndpointCreateResult as W, type AccountsClient as a, type ApiKeyCreateResult as b, type ApiKeysClient as c, type AuthClient as d, type AuthSessionStore as e, type CapxulAuthConfig as f, type CapxulConfig as g, type CapxulDataClient as h, type CapxulFlowFactories as i, type CapxulSigningConfig as j, type OrgDocumentsClient as k, type OrgPaymentsClient as l, type OrgSafesClient as m, type OrgTransfersClient as n, type OrgTreasuryClient as o, type OrgWithdrawalsClient as p, type OrganizationsClient as q, type SubAccountsClient as r, type TransportRuntime as s, type TransportState as t, type VirtualCardsClient as u, type WebhookEndpointsClient as v, type WebhookEventsClient as w, type WithdrawalsClient as x, createCapxulClient as y, makeHttpTransport as z };
+export { type AccountProvisionPersonalInput as A, type BrowserCapxulConfig as B, type CapxulClient as C, type DocumentsClient as D, type ExternalAccountsClient as E, type VirtualCardsClient as F, type WebhookEndpointsClient as G, type HttpTransport as H, type WebhookEventsClient as I, type WithdrawalsClient as J, createCapxulClient as K, type LocalPrivateKeySignerProvider as L, type MeClient as M, makeHttpTransport as N, type OperationsClient as O, type PaymentsClient as P, toTokenTransferId as Q, type Session as S, type TokenTransfer as T, type VirtualAccountsClient as V, type WebhookEndpointCreateResult as W, type AccountsClient as a, type ApiKeyCreateResult as b, type ApiKeysClient as c, type AuthClient as d, type AuthSessionStore as e, type CapxulAuthConfig as f, type CapxulConfig as g, type CapxulDataClient as h, type CapxulFlowFactories as i, type CapxulSigningConfig as j, type OrgDocumentsClient as k, type OrgPaymentsClient as l, type OrgSafesClient as m, type OrgTransfersClient as n, type OrgTreasuryClient as o, type OrgWithdrawalsClient as p, type OrganizationsClient as q, type SubAccountsClient as r, type TokenTransferId as s, type TokenTransfersClient as t, type TokenTransfersListInput as u, type TokenTransfersListPage as v, type TokenTransfersRetrieveInput as w, type TransfersClient as x, type TransportRuntime as y, type TransportState as z };