# API Reference: Account Model The `Account` model in the Quicksilver SDK transforms raw account data into an "active record" object, encapsulating both data and behavior. Instead of merely being a data structure, an `Account` object provides fluent methods to interact with the Quicksilver Engine, enabling operations like delegating sub-accounts, initiating transactions, managing limits, and handling KYC verification directly on the object. This design promotes a more intuitive, type-safe, and object-oriented approach to building agent commerce applications. ## `Account` Class ```typescript class Account { readonly id: string; data: AccountData; // Internal representation, access via getters constructor(data: AccountData, http: HttpClient); // Getters get name(): string; get accountType(): string; get parentId(): string | null; get meta(): Record; get limits(): { daily?: number | null; per_transaction?: number | null; total?: number | null }; get createdAt(): string; get updatedAt(): string; get children(): string[]; get executedAt(): string | null; // From TransactionData, not directly applicable to AccountData without type reconciliation or specific resource. Rechecking: only in Transaction. Removing from Account. // Methods delegate(options: { name: string, limits: { daily: number } }): Promise; transaction(details: Omit): Transaction; purchase(product: Product, options: Record): Promise; refresh(): Promise; getChildren(): Promise; updateLimits(limits: { daily?: number; per_transaction?: number; total?: number }): Promise; getBalance(): Promise<{ amount: number; currency: string }>; isVerified(): boolean; isRootAccount(): boolean; canTransact(): boolean; canDelegate(): boolean; submitKYC(kycData: { document_type: string; document_number: string; document_file?: File | Blob }): Promise; verify(verifiedBy: string): Promise; rejectVerification(reason: string): Promise; getVerificationStatus(): { status: 'unverified' | 'pending' | 'verified' | 'rejected'; verified_at?: string | null; kyc_data?: { document_type?: string; document_number?: string; verified_by?: string; } | null; }; } ``` ## Constructor ### `new Account(data, http)` * **`data`**: `AccountData` - The raw data representing an account as returned by the API. * **`http`**: `HttpClient` - The HTTP client instance used for API requests. **Description**: Initializes a new `Account` instance. This constructor is typically called internally by the `QuicksilverClient` or `AccountsResource` when fetching or creating an account. ## Properties (Getters) `Account` objects expose their underlying data through convenient getters, ensuring type safety and encapsulation. * ### `id: string` * **Description**: The unique identifier of the account. * ### `name: string` * **Description**: The human-readable name of the account. * ### `accountType: string` * **Description**: The type of the account (e.g., 'Human', 'AgentMain', 'AgentDelegated'). * ### `parentId: string | null` * **Description**: The ID of the parent account if this is a delegated sub-account, otherwise `null`. * ### `meta: Record` * **Description**: A key-value store for arbitrary metadata associated with the account. * ### `limits: { daily?: number | null; per_transaction?: number | null; total?: number | null }` * **Description**: Configurable financial limits applied to the account (e.g., daily spending, per-transaction cap, total limit). * ### `createdAt: string` * **Description**: The ISO 8601 timestamp when the account was created. * ### `updatedAt: string` * **Description**: The ISO 8601 timestamp when the account was last updated. * ### `children: string[]` * **Description**: A list of IDs of direct child accounts (delegated sub-agents). ## Methods `Account` objects provide methods that reflect the real-world actions and queries one might perform on an account. ### Account Lifecycle & Management * #### `refresh(): Promise` * **Description**: Refreshes the `Account` object's data by fetching the latest information from the Quicksilver Engine. * **Returns**: `Promise` - A promise that resolves with the refreshed `Account` instance. * #### `getChildren(): Promise` * **Description**: Retrieves a list of all direct child accounts (delegated sub-agents) associated with this account. * **Returns**: `Promise` - A promise that resolves to an array of `Account` objects representing the children. * #### `updateLimits(limits): Promise` * **`limits`**: `{ daily?: number; per_transaction?: number; total?: number }` - An object specifying the new daily, per-transaction, or total limits for the account. * **Description**: Updates the financial limits for this account. * **Returns**: `Promise` - A promise that resolves with the updated `Account` instance. * #### `getBalance(): Promise<{ amount: number; currency: string }>` * **Description**: Fetches the current balance of the account. * **Returns**: `Promise<{ amount: number; currency: string }>` - A promise that resolves to an object containing the account's balance amount and currency. ### Delegation * #### `delegate(options): Promise` * **`options`**: `{ name: string, limits: { daily: number } }` - Options for the new delegated sub-agent, including its name and daily transaction limits. * **Description**: Creates and delegates a new sub-agent account under this parent account. The new account will have its own ID and can operate within its defined limits. * **Returns**: `Promise` - A promise that resolves to the newly created and delegated `Account` object. ### Transactions & Commerce * #### `transaction(details): Transaction` * **`details`**: `Omit` - The details for the new transaction, excluding the `from` field (which is implicitly this account's ID) and system-generated fields. * **Description**: Initiates the creation of a new transaction originating from this account. This method returns a `Transaction` object in a 'Draft' state, allowing for further fluent configuration before execution. * **Returns**: `Transaction` - A new `Transaction` object configured with this account as the sender. * #### `purchase(product, options): Promise` * **`product`**: `Product` - The programmable product to purchase. This should be an instance of `ProductBuilder` configured with the product's details. * **`options`**: `Record` - Additional options or context specific to the purchase, such as quantity, specific configurations, or dynamic parameters. * **Description**: Facilitates the purchase of a defined programmable product, initiating a transaction from this account based on the product's rules. * **Returns**: `Promise` - A promise that resolves to the `Transaction` object created for the purchase. ### KYC & Compliance * #### `isVerified(): boolean` * **Description**: Checks if the account has a 'verified' KYC status. * **Returns**: `boolean` - `true` if the account is verified, `false` otherwise. * #### `isRootAccount(): boolean` * **Description**: Determines if this account is a top-level (root) account with no parent. * **Returns**: `boolean` - `true` if it's a root account, `false` otherwise. * #### `canTransact(): boolean` * **Description**: Checks if the account is authorized to perform transactions (typically requires verification). * **Returns**: `boolean` - `true` if the account can transact, `false` otherwise. * #### `canDelegate(): boolean` * **Description**: Checks if the account is authorized to delegate sub-accounts (typically requires verification). * **Returns**: `boolean` - `true` if the account can delegate, `false` otherwise. * #### `submitKYC(kycData): Promise` * **`kycData`**: `{ document_type: string; document_number: string; document_file?: File | Blob; }` - An object containing details for KYC document submission, including document type, number, and an optional file. * **Description**: Submits Know Your Customer (KYC) verification documents for the account. This typically changes the account's verification status to 'pending' or 'in_review'. * **Returns**: `Promise` - A promise that resolves with the updated `Account` instance. * #### `verify(verifiedBy: string): Promise` * **`verifiedBy`**: `string` - The identifier of the user or system performing the verification (e.g., 'admin_user_id'). * **Description**: Manually marks the account's KYC status as 'verified'. This is typically an administrative function requiring elevated permissions. * **Returns**: `Promise` - A promise that resolves with the updated `Account` instance. * #### `rejectVerification(reason: string): Promise` * **`reason`**: `string` - A detailed reason for rejecting the KYC verification. * **Description**: Manually marks the account's KYC status as 'rejected'. This is typically an administrative function requiring elevated permissions. * **Returns**: `Promise` - A promise that resolves with the updated `Account` instance. * #### `getVerificationStatus(): { status: 'unverified' | 'pending' | 'verified' | 'rejected'; verified_at?: string | null; kyc_data?: { document_type?: string; document_number?: string; verified_by?: string; } | null; }` * **Description**: Retrieves the current KYC verification status and any associated details. * **Returns**: `object` - An object containing the verification `status`, `verified_at` timestamp, and `kyc_data` (if available).

API Reference: Account Model

Page Viewers

Guest Views