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

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<string, any>

  • 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<this>

  • Description: Refreshes the Account object's data by fetching the latest information from the Quicksilver Engine.
  • Returns: Promise<this> - A promise that resolves with the refreshed Account instance.

• getChildren(): Promise<Account[]>

  • Description: Retrieves a list of all direct child accounts (delegated sub-agents) associated with this account.
  • Returns: Promise<Account[]> - A promise that resolves to an array of Account objects representing the children.

• updateLimits(limits): Promise<this>

  • 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<this> - 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<Account>

  • 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<Account> - A promise that resolves to the newly created and delegated Account object.

Transactions & Commerce

• transaction(details): Transaction

  • details: Omit<TransactionData, 'from' | 'id' | 'state' | 'created_at' | 'updated_at' | 'children'> - 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<Transaction>

  • product: Product - The programmable product to purchase. This should be an instance of ProductBuilder configured with the product's details.
  • options: Record<string, any> - 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<Transaction> - 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<this>

  • 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<this> - A promise that resolves with the updated Account instance.

• verify(verifiedBy: string): Promise<this>

  • 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<this> - A promise that resolves with the updated Account instance.

• rejectVerification(reason: string): Promise<this>

  • 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<this> - 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).