@venly/wallet-mcp
Version:
Production-ready MCP server enabling AI agents to perform Web3 wallet operations through Venly's blockchain infrastructure. Supports 14+ networks including Ethereum, Polygon, Arbitrum, and stablecoin operations.
311 lines • 11.8 kB
TypeScript
/**
* Venly API Client
*
* Production-ready client for Venly Wallet-as-a-Service API
* Features OAuth 2.0 authentication, rate limiting, and comprehensive error handling
*/
import type { VenlyAuthToken, Wallet, CreateWalletRequest, TokenBalance, EnrichedTokenBalance, TokenPortfolioSummary, TransactionResult, ExecuteTransactionRequest, PaginationParams, FiatOnrampRequest, FiatOfframpRequest, FiatRampResponse, ExchangeRate, FiatTransactionStatus, FiatProvider, WebhookConfig, WebhookStatus, WebhookEvent, VenlyUser, CreateUserRequest, UpdateUserRequest, CreateSigningMethodRequest, SigningMethod, SendTransactionRequest, SendTokenRequest, TransactionResponse } from '../types/venly.js';
import type { UserVenlyCredentials } from '../auth/CredentialValidator.js';
/**
* Custom error class for Venly API errors
*/
export declare class VenlyApiError extends Error {
readonly errorCode: string;
readonly statusCode?: number | undefined;
readonly isCredentialError: boolean;
readonly details?: Record<string, unknown> | undefined;
constructor(errorCode: string, message: string, statusCode?: number | undefined, isCredentialError?: boolean, details?: Record<string, unknown> | undefined);
}
/**
* Main Venly API Client - Now supports user-specific authentication
*/
export declare class VenlyClient {
private readonly httpClient;
private readonly authClient;
private readonly rateLimiter;
private readonly logger;
private readonly environment;
private readonly workflowStorage;
constructor(environment: 'sandbox' | 'production');
/**
* Authenticate user with their Venly credentials using OAuth 2.0 client credentials flow
*/
authenticateUser(credentials: UserVenlyCredentials): Promise<VenlyAuthToken>;
/**
* Execute operation with user authentication
*/
executeWithUserAuth<T>(credentials: UserVenlyCredentials, operation: (token: string) => Promise<T>): Promise<T>;
/**
* Create a new wallet with user credentials
* This implements the full Venly workflow: create user -> create wallet
*/
createWallet(credentials: UserVenlyCredentials, request: CreateWalletRequest): Promise<Wallet>;
/**
* List all wallets with user credentials
*/
listWallets(credentials: UserVenlyCredentials, params?: PaginationParams): Promise<Wallet[]>;
/**
* Get wallet details by ID with user credentials
*/
getWallet(credentials: UserVenlyCredentials, walletId: string): Promise<Wallet>;
/**
* Get wallet token balances with user credentials
*/
getWalletTokenBalances(credentials: UserVenlyCredentials, walletId: string): Promise<TokenBalance[]>;
/**
* Get enriched wallet token balances with metadata, pricing, and portfolio information
*/
getEnrichedTokenBalances(credentials: UserVenlyCredentials, walletId: string): Promise<EnrichedTokenBalance[]>;
/**
* Get comprehensive token portfolio analysis for a wallet
* Note: Venly doesn't have a separate portfolio endpoint, so we build it from token balances
*/
getTokenPortfolio(credentials: UserVenlyCredentials, walletId: string): Promise<TokenPortfolioSummary>;
/**
* Create a new user with optional signing method
*/
createUser(credentials: UserVenlyCredentials, request: CreateUserRequest): Promise<VenlyUser>;
/**
* List all users with pagination and filtering
* Note: Venly may not have a direct list users endpoint, so we'll implement a fallback approach
*/
listUsers(credentials: UserVenlyCredentials, params?: {
page?: number;
size?: number;
reference?: string;
includeSigningMethods?: boolean;
}): Promise<VenlyUser[]>;
/**
* Get user details by ID
*/
getUser(credentials: UserVenlyCredentials, userId: string): Promise<VenlyUser>;
/**
* Update user information
*/
updateUser(credentials: UserVenlyCredentials, userId: string, updates: UpdateUserRequest): Promise<VenlyUser>;
/**
* Delete a user (if supported by API)
*/
deleteUser(credentials: UserVenlyCredentials, userId: string): Promise<void>;
/**
* Create a signing method for a user
*/
createSigningMethod(credentials: UserVenlyCredentials, userId: string, request: CreateSigningMethodRequest): Promise<SigningMethod>;
/**
* Get all signing methods for a user
*/
getUserSigningMethods(credentials: UserVenlyCredentials, userId: string): Promise<SigningMethod[]>;
/**
* Execute a transaction with user credentials
*/
executeTransaction(credentials: UserVenlyCredentials, request: ExecuteTransactionRequest): Promise<TransactionResult>;
/**
* Get transaction details by hash with user credentials
*/
getTransaction(credentials: UserVenlyCredentials, transactionHash: string): Promise<TransactionResult>;
/**
* Send native tokens from one wallet to another
*/
sendTransaction(credentials: UserVenlyCredentials, request: SendTransactionRequest): Promise<TransactionResponse>;
/**
* Send ERC-20 tokens from one wallet to another
*/
sendTokenTransaction(credentials: UserVenlyCredentials, request: SendTokenRequest): Promise<TransactionResponse>;
/**
* Get transaction status by hash and secret type
*/
getTransactionStatus(credentials: UserVenlyCredentials, transactionHash: string, secretType: string): Promise<TransactionResponse>;
/**
* Helper method to map Venly response to our TransactionResponse format
*/
private mapToTransactionResponse;
/**
* Helper method to map Venly transaction status to our format
*/
private mapTransactionStatus;
/**
* Create fiat onramp URL for purchasing crypto with fiat currency
* Note: Venly doesn't provide direct fiat onramp endpoints, so we simulate the response
*/
createFiatOnramp(credentials: UserVenlyCredentials, request: FiatOnrampRequest): Promise<FiatRampResponse>;
/**
* Create fiat offramp URL for selling crypto to fiat currency
* Note: Venly doesn't provide direct fiat offramp endpoints, so we simulate the response
*/
createFiatOfframp(credentials: UserVenlyCredentials, request: FiatOfframpRequest): Promise<FiatRampResponse>;
/**
* Get real-time exchange rates between fiat and crypto currencies
*/
getExchangeRates(fromCurrency: string, toCurrency: string): Promise<ExchangeRate[]>;
/**
* Track fiat transaction status by provider transaction ID
*/
trackFiatTransaction(transactionId: string, provider: FiatProvider): Promise<FiatTransactionStatus>;
/**
* Setup transaction webhooks for real-time transaction monitoring
*/
setupTransactionWebhooks(credentials: UserVenlyCredentials, request: any): Promise<any>;
/**
* Setup balance webhooks for balance change notifications
*/
setupBalanceWebhooks(credentials: UserVenlyCredentials, request: any): Promise<any>;
/**
* Setup portfolio webhooks for portfolio value change alerts
*/
setupPortfolioWebhooks(credentials: UserVenlyCredentials, request: any): Promise<any>;
/**
* Process webhook events and analyze them
*/
processWebhookEvents(credentials: UserVenlyCredentials, request: any): Promise<any>;
/**
* Get webhook status and health information
*/
getWebhookStatusMCP(credentials: UserVenlyCredentials, request: any): Promise<any>;
/**
* Setup a webhook configuration for real-time event notifications
*/
setupWebhook(config: Omit<WebhookConfig, 'id' | 'createdAt' | 'updatedAt'>): Promise<WebhookConfig>;
/**
* Delete a webhook configuration
*/
deleteWebhook(webhookId: string): Promise<void>;
/**
* Get webhook status and delivery information
*/
getWebhookStatus(webhookId: string): Promise<WebhookStatus>;
/**
* Verify webhook signature using HMAC-SHA256
*/
verifyWebhookSignature(payload: string, signature: string, secret: string): boolean;
/**
* Process incoming webhook event (for hybrid implementation)
*/
processWebhookEvent(event: WebhookEvent): Promise<void>;
/**
* Generate a unique webhook ID
*/
private generateWebhookId;
/**
* Generate a secure secret key for webhook signatures
*/
private generateSecretKey;
/**
* Generate recent webhook deliveries for status simulation
*/
private generateRecentDeliveries;
/**
* Generate onramp URL for a provider
*/
private generateOnrampUrl;
/**
* Generate offramp URL for a provider
*/
private generateOfframpUrl;
/**
* Simulate exchange rate for demonstration purposes
*/
private simulateExchangeRate;
/**
* Simulate transaction status for demonstration purposes
*/
private simulateTransactionStatus;
/**
* Create workflow template for MCP tools
*/
createWorkflowTemplate(credentials: UserVenlyCredentials, request: any): Promise<any>;
/**
* Execute workflow for MCP tools
*/
executeWorkflow(credentials: UserVenlyCredentials, request: any): Promise<any>;
/**
* Monitor workflow status for MCP tools
*/
monitorWorkflowStatus(credentials: UserVenlyCredentials, request: any): Promise<any>;
private getValidToken;
private executeWorkflowSteps;
private executeWorkflowStep;
private workflowTemplates;
private workflowExecutions;
private workflowLogs;
private validateWorkflowTemplate;
private storeWorkflowTemplate;
private getStoredWorkflowTemplate;
private storeWorkflowExecution;
private getStoredWorkflowExecution;
private updateWorkflowExecution;
private logWorkflowEvent;
private getWorkflowLogs;
private resolveStepParameters;
private getStepName;
private getCurrentStepStatus;
private getStepHistory;
/**
* Create a workflow template (legacy)
*/
createWorkflowTemplateLegacy(template: any): Promise<any>;
/**
* Execute a workflow (legacy)
*/
executeWorkflowLegacy(templateId: string, inputs: Record<string, unknown>): Promise<any>;
/**
* Get workflow execution status (legacy)
*/
getWorkflowStatusLegacy(executionId: string): Promise<any>;
/**
* Make authenticated API request with user token and custom headers
*/
private makeRequestWithTokenAndHeaders;
/**
* Make authenticated API request with user token
*/
private makeRequestWithToken;
/**
* Create HTTP client for API requests
*/
private createHttpClient;
/**
* Create HTTP client for authentication
*/
private createAuthClient;
/**
* Create Winston logger instance
*/
private createLogger;
/**
* Get API URL based on environment
*/
private getApiUrl;
/**
* Get authentication URL based on environment
*/
private getAuthUrl;
/**
* Update rate limit information from response headers
*/
private updateRateLimitInfo;
/**
* Handle API errors and convert to VenlyApiError
*/
private handleApiError;
/**
* Export financial data for tax/accounting purposes
*/
exportFinancialData(credentials: UserVenlyCredentials, request: any): Promise<any>;
/**
* Optimize transaction routing across chains
*/
optimizeTransactionRouting(credentials: UserVenlyCredentials, request: any): Promise<any>;
/**
* Helper method to get token name
*/
private getTokenName;
/**
* Helper method to get token price
*/
private getTokenPrice;
/**
* Cleanup resources
*/
cleanup(): Promise<void>;
}
//# sourceMappingURL=VenlyClient.d.ts.map