# API Reference: Core Types and Events This page provides a comprehensive reference for the core types, enums, and interfaces used throughout the Quicksilver SDK. Understanding these fundamental building blocks is essential for effectively using the SDK's fluent Domain-Specific Language (DSL) and interacting with the Quicksilver Engine API. The types defined here empower the SDK's strong [Type Safety](/wiki/lantos1618/quicksilver-sdk/sdk-architecture#core-philosophy-from-api-wrapper-to-fluent-dsl) and rich autocompletion, making it easier to build robust and error-resistant applications. --- ## Enums and Union Types These define the categorical values used across accounts, transactions, and streams. ### `AccountType` Defines the different classifications for accounts within the Quicksilver Engine. ```typescript type AccountType = "Human" | "AgentMain" | "AgentDelegated"; ``` * **`Human`**: An account representing a human user. * **`AgentMain`**: A primary AI agent account, capable of delegating to sub-agents. * **`AgentDelegated`**: A sub-agent account delegated by a `AgentMain` account, often with specific limits or permissions. ### `TransactionType` Specifies the various types of financial operations supported by the Quicksilver Engine. ```typescript type TransactionType = "Payment" | "Escrow" | "Stream" | "Scheduled" | "Fund" | "Refund"; ``` * **`Payment`**: A direct, immediate transfer of funds. * **`Escrow`**: Funds held by a third party (the Quicksilver Engine) pending fulfillment of conditions. * **`Stream`**: Continuous, real-time transfer of funds (streaming payments). * **`Scheduled`**: A transaction set to execute at a future date or recurring interval. * **`Fund`**: An operation to add funds to an account. * **`Refund`**: An operation to return funds from a previous transaction. ### `TransactionState` Describes the current lifecycle status of a transaction. ```typescript type TransactionState = "Draft" | "Pending" | "Executing" | "Completed" | "Failed" | "Cancelled"; ``` * **`Draft`**: The transaction has been defined but not yet initiated or submitted for execution. * **`Pending`**: The transaction has been initiated and is awaiting further action (e.g., approval, conditions to be met, processing by a gateway). * **`Executing`**: The transaction is actively being processed, especially relevant for streaming or complex conditional transactions. * **`Completed`**: The transaction has successfully finished. * **`Failed`**: The transaction could not be completed due to an error. * **`Cancelled`**: The transaction was explicitly cancelled before completion. ### `StreamRateUnit` Defines the unit by which a streaming transaction's rate is measured. ```typescript type StreamRateUnit = "PerSecond" | "PerMinute" | "PerHour" | "PerWord" | "PerToken" | { Custom: string }; ``` * **`PerSecond`**, **`PerMinute`**, **`PerHour`**: Time-based units for streaming. * **`PerWord`**: Unit for content-based streaming (e.g., per word translated). * **`PerToken`**: Unit for AI-compute based streaming (e.g., per AI token processed). * **`Custom`**: Allows for defining any other arbitrary unit. ### `Currency` Specifies the supported currencies for financial operations. ```typescript type Currency = "USD" | "USDC" | "EUR" | { Custom: string }; ``` * **`USD`**: United States Dollar. * **`USDC`**: USD Coin (a stablecoin). * **`EUR`**: Euro. * **`Custom`**: Allows for defining any other arbitrary currency or token. ### `QuickSilverEvent` A core enum used by the `ConditionBuilder` to define triggers for conditional logic. These events represent significant occurrences within the Quicksilver Engine that can activate specific actions. ```typescript enum QuickSilverEvent { MilestoneApproved = 'milestone_approved', TimeElapsed = 'time_elapsed', ApiCallSuccess = 'api_call_success', ApiCallFailure = 'api_call_failure', PaymentReceived = 'payment_received', StreamStarted = 'stream_started', StreamStopped = 'stream_stopped', Custom = 'custom' } ``` * **`MilestoneApproved`**: Triggered when a specific project milestone is approved, typically used in escrow scenarios. * **`TimeElapsed`**: Triggered after a specified duration, useful for scheduled payments or time-based releases. * **`ApiCallSuccess`**: Triggered upon a successful external API call. * **`ApiCallFailure`**: Triggered when an external API call fails. * **`PaymentReceived`**: Triggered when a payment is successfully received. * **`StreamStarted`**: Triggered when a streaming payment begins. * **`StreamStopped`**: Triggered when a streaming payment ends. * **`Custom`**: Allows for defining any other arbitrary custom event. --- ## Core DSL Interfaces These interfaces are central to the SDK's DSL, enabling the definition of complex programmable money logic. ### `Action` Represents a single action to be executed when a condition is met. This interface is implemented by the `ActionBuilder` for fluent construction. ```typescript interface Action { type: string; toJSON(): object; } ``` * **`type`**: The type of action (e.g., 'release', 'notify', 'hold'). * **`toJSON()`**: A method to serialize the action into a JSON object for API consumption. ### `Condition` Defines a single conditional rule, comprising a trigger, an optional predicate, and a list of actions. This is used internally by the `ConditionBuilder`. ```typescript interface Condition { trigger: QuickSilverEvent | ((ctx: any) => boolean); predicate?: (ctx: any) => boolean; actions: Action[]; } ``` * **`trigger`**: The event (from `QuickSilverEvent`) or a custom function that starts evaluating this condition. * **`predicate`**: An optional function that further refines when the condition is true (e.g., `ctx => ctx.amount > 100`). * **`actions`**: An array of `Action`s to execute if the condition is met. ### `ProductDefinition` Defines the structure of a programmable product or service, including its pricing model, guarantees, and workflow stages. This is used internally by the `ProductBuilder`. ```typescript interface ProductDefinition { id: string; pricing: { model: 'per_unit' | 'streaming'; rate: number; unit: string; currency: Currency; }; guarantees: Record; workflow: Array<{ name: string; delegateTo: string; charge: number; }>; } ``` * **`id`**: A unique identifier for the product. * **`pricing`**: Defines how the product is charged (e.g., per unit, streaming). * **`guarantees`**: A key-value pair of service level agreements or quality assurances (e.g., `accuracy`, `turnaround`). * **`workflow`**: An array of stages, each potentially delegated to a specific agent with a defined charge. --- ## Main Data Models These interfaces represent the core entities managed by the Quicksilver Engine. ### `Account` (Data Model) Represents an account within the Quicksilver Engine, holding metadata, limits, and verification status. This is the raw data structure wrapped by the [Account Model](/wiki/lantos1618/quicksilver-sdk/sdk-architecture#models). ```typescript interface Account { id: string; name: string; account_type: AccountType; parent_id?: string | null; public_key?: string | null; meta: Record; limits: { daily?: number | null; per_transaction?: number | null; total?: number | null; }; verification: { status: 'unverified' | 'pending' | 'verified' | 'rejected'; verified_at?: string | null; kyc_data?: { document_type?: string; document_number?: string; verified_by?: string; } | null; }; created_at: string; // ISO 8601 DateTime string updated_at: string; // ISO 8601 DateTime string children: string[]; } ``` ### `Transaction` (Data Model) Represents a financial transaction, including its type, amount, parties involved, state, and optional conditional logic. This is the raw data structure wrapped by the [Transaction Model](/wiki/lantos1618/quicksilver-sdk/sdk-architecture#models). ```typescript interface Transaction { id: string; transaction_type: TransactionType; amount: number; currency: Currency; from: string; to?: string | null; parent_id?: string | null; children: string[]; state: TransactionState; conditions?: Condition[] | null; // Now properly typed meta: Record; created_at: string; updated_at: string; executed_at?: string | null; } ``` ### `StreamingTransaction` Extends the base `Transaction` interface with details specific to streaming payments. ```typescript interface StreamingTransaction { base: Transaction; rate: number; rate_unit: StreamRateUnit; start_time: string; end_time?: string | null; accumulated: number; last_batch: string; } ``` * **`base`**: The underlying `Transaction` object. * **`rate`**: The rate at which funds are streamed. * **`rate_unit`**: The unit for the streaming rate (e.g., 'PerSecond', 'PerWord'). * **`start_time`**: The ISO timestamp when the stream began. * **`end_time`**: The ISO timestamp when the stream is scheduled to end, if applicable. * **`accumulated`**: The total amount transferred so far in the stream. * **`last_batch`**: The ID of the last batch transaction for the stream. --- ## API Payload Types These interfaces define the expected structure of data sent to the Quicksilver API when creating or updating resources. ### `CreateAccountPayload` The payload for creating a new account. ```typescript interface CreateAccountPayload { name: string; account_type: AccountType; parent_id?: string; public_key?: string; meta?: Record; limits?: { daily?: number; per_transaction?: number; total?: number; }; verification?: { status?: 'unverified' | 'pending' | 'verified' | 'rejected'; verified_at?: string; kyc_data?: { document_type?: string; document_number?: string; verified_by?: string; }; }; } ``` ### `CreateTransactionPayload` The payload for creating a new transaction. ```typescript interface CreateTransactionPayload { amount: number; currency: Currency; transaction_type: TransactionType; from: string; to?: string; parent_id?: string; meta?: Record; conditions?: Condition[]; // Now properly typed } ``` ### `CreateStreamingTransactionPayload` The payload for creating a streaming transaction. ```typescript interface CreateStreamingTransactionPayload { rate: number; rate_unit: StreamRateUnit; start_time?: string; end_time?: string; } ``` ### `KycInitiatePayload` The payload for initiating a KYC verification process for an account. ```typescript interface KycInitiatePayload { account_id: string; first_name: string; last_name: string; email: string; date_of_birth?: string; address?: { street: string; city: string; state?: string; postal_code: string; country: string; }; } ``` --- ## API Response Types These interfaces define the structure of common responses received from the Quicksilver API. ### `StatusResponse` A generic response for operations that change the status of a resource (e.g., pausing a stream). ```typescript interface StatusResponse { status: 'paused' | 'resumed' | 'stopped'; stream_id: string; timestamp: string; } ``` ### `KycStatus` Details the current KYC verification status of an account. ```typescript interface KycStatus { account_id: string; status: 'pending' | 'in_review' | 'verified' | 'rejected'; verified_at?: string; rejection_reason?: string; kyc_provider?: string; kyc_data?: Record; } ``` ### `KycInitiateResponse` The response received after attempting to initiate a KYC verification. ```typescript interface KycInitiateResponse { success: boolean; verification_url?: string; session_id?: string; message?: string; } ``` --- ## Real-time Event Types (SSE) These interfaces define the structure of events delivered via Server-Sent Events (SSE) for real-time updates. ### `SSEStreamEvent` Represents a lifecycle event occurring on a streaming transaction. ```typescript interface SSEStreamEvent { stream_id: string; event_type: 'streamstarted' | 'paused' | 'resumed' | 'stopped' | 'completed'; timestamp: string; } ``` ### `SSEBatchCreatedEvent` Represents an event indicating that a batch payment has been processed for a streaming transaction. ```typescript interface SSEBatchCreatedEvent { stream_id: string; batch_transaction_id: string; amount: number; timestamp: string; } ``` --- ## Error and Pagination Types Standard interfaces for error handling and data pagination. ### `APIError` The standard structure for error responses from the Quicksilver API. ```typescript interface APIError { error: string; message: string; status_code: number; details?: Record; } ``` * **`error`**: A short, general error code or name. * **`message`**: A human-readable description of the error. * **`status_code`**: The HTTP status code associated with the error. * **`details`**: Optional additional details about the error (e.g., validation errors). ### `PaginationParams` Parameters used when requesting paginated lists of resources. ```typescript interface PaginationParams { page?: number; limit?: number; cursor?: string; } ``` * **`page`**: The specific page number to retrieve (for offset-based pagination). * **`limit`**: The maximum number of items to return per page. * **`cursor`**: A token used for cursor-based pagination to fetch the next set of results. ### `PaginatedResponse` A generic structure for responses that contain a list of items along with pagination metadata. ```typescript interface PaginatedResponse { data: T[]; pagination: { page: number; limit: number; total: number; has_more: boolean; next_cursor?: string; }; } ``` * **`data`**: An array of the requested resource type (`T`). * **`pagination`**: An object containing metadata about the pagination: * **`page`**: The current page number. * **`limit`**: The number of items per page. * **`total`**: The total number of items available. * **`has_more`**: A boolean indicating if there are more pages to fetch. * **`next_cursor`**: An optional cursor for fetching the next page of results.

API Reference: Core Types and Events

Page Viewers

Guest Views