@proofchain/sdk 2.1.1 → 2.2.0

package/dist/index.d.mts

@@ -1007,13 +1007,6 @@ interface WalletBalance {
     network: string;
     balances: TokenBalance[];
 }
-interface TokenBalance {
-    token: string;
-    symbol: string;
-    balance: string;
-    decimals: number;
-    usd_value?: number;
-}
 interface NFT {
     id: string;
     wallet_id: string;
@@ -1157,11 +1150,20 @@ interface AddNFTRequest {
     source?: string;
 }
 interface TransferRequest {
-    from_address: string;
+    /** Source wallet address (required if wallet_id not provided) */
+    from_address?: string;
+    /** Source wallet ID (alternative to from_address) */
+    wallet_id?: string;
+    /** Destination address */
     to_address: string;
+    /** Amount to transfer (in token units, e.g., "0.1" for 0.1 ETH) */
     amount: string;
+    /** Token symbol (default: "ETH") */
     token?: string;
+    /** Network (default: "base-sepolia") */
     network?: string;
+    /** Contract address for custom ERC-20 tokens */
+    contract_address?: string;
 }
 interface TransferResult {
     tx_hash: string;
@@ -1169,9 +1171,80 @@ interface TransferResult {
     to: string;
     amount: string;
     token: string;
+    contract_address?: string;
     network: string;
     status: string;
 }
+interface Token {
+    id: string;
+    contract_address: string;
+    network: string;
+    symbol: string;
+    name: string;
+    decimals: number;
+    logo_url?: string;
+    color?: string;
+    coingecko_id?: string;
+    coinmarketcap_id?: string;
+    token_standard: string;
+    is_native_wrapper: boolean;
+    is_verified: boolean;
+    is_active: boolean;
+    is_hidden?: boolean;
+    display_order: number;
+    is_global: boolean;
+}
+interface CreateTokenRequest {
+    contract_address: string;
+    network: string;
+    symbol: string;
+    name: string;
+    decimals?: number;
+    logo_url?: string;
+    color?: string;
+    coingecko_id?: string;
+    coinmarketcap_id?: string;
+    custom_price_feed_url?: string;
+    is_native_wrapper?: boolean;
+    display_order?: number;
+}
+interface UpdateTokenRequest {
+    symbol?: string;
+    name?: string;
+    decimals?: number;
+    logo_url?: string;
+    color?: string;
+    coingecko_id?: string;
+    coinmarketcap_id?: string;
+    custom_price_feed_url?: string;
+    is_active?: boolean;
+    is_hidden?: boolean;
+    display_order?: number;
+}
+interface TokenBalance {
+    token: string;
+    symbol: string;
+    balance: string;
+    decimals: number;
+    usd_value?: number;
+}
+interface TokenBalance {
+    token: string;
+    balance: string;
+    raw_balance?: string;
+    contract_address?: string;
+    decimals: number;
+    name?: string;
+    logo_url?: string;
+    source: 'cdp' | 'custom' | 'global';
+}
+interface WalletBalanceResponse {
+    address: string;
+    network: string;
+    native_balance: string;
+    native_symbol: string;
+    balances: TokenBalance[];
+}
 interface UserWithWallets {
     user_id: string;
     wallets: Array<{
@@ -1225,9 +1298,11 @@ declare class WalletClient {
      */
     createDualBulk(userIds: string[], network?: string): Promise<DualWallets[]>;
     /**
-     * Get wallet balance
+     * Get wallet balance including custom tokens.
+     *
+     * Returns native balance (ETH) plus all registered token balances.
      */
-    getBalance(walletId: string): Promise<WalletBalance>;
+    getBalance(walletId: string): Promise<WalletBalanceResponse>;
     /**
      * Get comprehensive wallet information in a single call.
      *
@@ -1265,21 +1340,33 @@ declare class WalletClient {
         warning: string;
     }>;
     /**
-     * Transfer tokens from one address to another.
+     * Transfer tokens from a CDP wallet to any address.
+     *
+     * Supports native ETH and ERC-20 tokens. The source wallet must be a CDP-managed wallet.
      *
-     * @param request - Transfer details
+     * @param request - Transfer details (use wallet_id or from_address)
      * @returns Transaction result with hash and status
      *
      * @example
      * ```typescript
+     * // Transfer ETH using wallet_id
      * const result = await client.wallets.transfer({
-     *   from_address: '0x123...',
+     *   wallet_id: 'd1096269-f986-4fa6-a1f5-1a29ef69f6e4',
      *   to_address: '0x456...',
-     *   amount: '0.1',
+     *   amount: '0.0001',
      *   token: 'ETH',
-     *   network: 'base-sepolia',
+     *   network: 'base-mainnet',
      * });
      * console.log('TX Hash:', result.tx_hash);
+     *
+     * // Transfer using from_address
+     * const result2 = await client.wallets.transfer({
+     *   from_address: '0xaA2e82E5fCF97003d409Bc90826F40cfc8F27510',
+     *   to_address: '0x456...',
+     *   amount: '0.0001',
+     *   token: 'ETH',
+     *   network: 'base-mainnet',
+     * });
      * ```
      */
     transfer(request: TransferRequest): Promise<TransferResult>;
@@ -1318,6 +1405,63 @@ declare class WalletClient {
         limit?: number;
         offset?: number;
     }): Promise<TransactionHistory>;
+    /**
+     * Register a custom token for the tenant.
+     *
+     * This allows tracking balances and enabling transfers for custom ERC-20 tokens.
+     *
+     * @param request - Token details including contract address, symbol, decimals
+     * @returns The created token
+     *
+     * @example
+     * ```typescript
+     * const token = await client.wallets.createToken({
+     *   contract_address: '0x...',
+     *   network: 'base-mainnet',
+     *   symbol: 'wSOL',
+     *   name: 'Wrapped Solana',
+     *   decimals: 9,
+     * });
+     * ```
+     */
+    createToken(request: CreateTokenRequest): Promise<Token>;
+    /**
+     * List all tokens available to the tenant.
+     *
+     * Returns both tenant-specific tokens and global tokens.
+     *
+     * @param options - Filter options
+     */
+    listTokens(options?: {
+        network?: string;
+        include_global?: boolean;
+        include_hidden?: boolean;
+    }): Promise<Token[]>;
+    /**
+     * List global tokens (available to all tenants).
+     *
+     * These are well-known tokens like USDC, WETH, DAI, etc.
+     */
+    listGlobalTokens(network?: string): Promise<Token[]>;
+    /**
+     * Get a specific token by ID.
+     */
+    getToken(tokenId: string): Promise<Token>;
+    /**
+     * Get a token by contract address and network.
+     */
+    getTokenByContract(contractAddress: string, network: string): Promise<Token>;
+    /**
+     * Update a custom token.
+     */
+    updateToken(tokenId: string, request: UpdateTokenRequest): Promise<Token>;
+    /**
+     * Delete a custom token (soft delete).
+     */
+    deleteToken(tokenId: string): Promise<{
+        message: string;
+        token_id: string;
+    }>;
 }
 
 /**

package/dist/index.d.ts

@@ -1007,13 +1007,6 @@ interface WalletBalance {
     network: string;
     balances: TokenBalance[];
 }
-interface TokenBalance {
-    token: string;
-    symbol: string;
-    balance: string;
-    decimals: number;
-    usd_value?: number;
-}
 interface NFT {
     id: string;
     wallet_id: string;
@@ -1157,11 +1150,20 @@ interface AddNFTRequest {
     source?: string;
 }
 interface TransferRequest {
-    from_address: string;
+    /** Source wallet address (required if wallet_id not provided) */
+    from_address?: string;
+    /** Source wallet ID (alternative to from_address) */
+    wallet_id?: string;
+    /** Destination address */
     to_address: string;
+    /** Amount to transfer (in token units, e.g., "0.1" for 0.1 ETH) */
     amount: string;
+    /** Token symbol (default: "ETH") */
     token?: string;
+    /** Network (default: "base-sepolia") */
     network?: string;
+    /** Contract address for custom ERC-20 tokens */
+    contract_address?: string;
 }
 interface TransferResult {
     tx_hash: string;
@@ -1169,9 +1171,80 @@ interface TransferResult {
     to: string;
     amount: string;
     token: string;
+    contract_address?: string;
     network: string;
     status: string;
 }
+interface Token {
+    id: string;
+    contract_address: string;
+    network: string;
+    symbol: string;
+    name: string;
+    decimals: number;
+    logo_url?: string;
+    color?: string;
+    coingecko_id?: string;
+    coinmarketcap_id?: string;
+    token_standard: string;
+    is_native_wrapper: boolean;
+    is_verified: boolean;
+    is_active: boolean;
+    is_hidden?: boolean;
+    display_order: number;
+    is_global: boolean;
+}
+interface CreateTokenRequest {
+    contract_address: string;
+    network: string;
+    symbol: string;
+    name: string;
+    decimals?: number;
+    logo_url?: string;
+    color?: string;
+    coingecko_id?: string;
+    coinmarketcap_id?: string;
+    custom_price_feed_url?: string;
+    is_native_wrapper?: boolean;
+    display_order?: number;
+}
+interface UpdateTokenRequest {
+    symbol?: string;
+    name?: string;
+    decimals?: number;
+    logo_url?: string;
+    color?: string;
+    coingecko_id?: string;
+    coinmarketcap_id?: string;
+    custom_price_feed_url?: string;
+    is_active?: boolean;
+    is_hidden?: boolean;
+    display_order?: number;
+}
+interface TokenBalance {
+    token: string;
+    symbol: string;
+    balance: string;
+    decimals: number;
+    usd_value?: number;
+}
+interface TokenBalance {
+    token: string;
+    balance: string;
+    raw_balance?: string;
+    contract_address?: string;
+    decimals: number;
+    name?: string;
+    logo_url?: string;
+    source: 'cdp' | 'custom' | 'global';
+}
+interface WalletBalanceResponse {
+    address: string;
+    network: string;
+    native_balance: string;
+    native_symbol: string;
+    balances: TokenBalance[];
+}
 interface UserWithWallets {
     user_id: string;
     wallets: Array<{
@@ -1225,9 +1298,11 @@ declare class WalletClient {
      */
     createDualBulk(userIds: string[], network?: string): Promise<DualWallets[]>;
     /**
-     * Get wallet balance
+     * Get wallet balance including custom tokens.
+     *
+     * Returns native balance (ETH) plus all registered token balances.
      */
-    getBalance(walletId: string): Promise<WalletBalance>;
+    getBalance(walletId: string): Promise<WalletBalanceResponse>;
     /**
      * Get comprehensive wallet information in a single call.
      *
@@ -1265,21 +1340,33 @@ declare class WalletClient {
         warning: string;
     }>;
     /**
-     * Transfer tokens from one address to another.
+     * Transfer tokens from a CDP wallet to any address.
+     *
+     * Supports native ETH and ERC-20 tokens. The source wallet must be a CDP-managed wallet.
      *
-     * @param request - Transfer details
+     * @param request - Transfer details (use wallet_id or from_address)
      * @returns Transaction result with hash and status
      *
      * @example
      * ```typescript
+     * // Transfer ETH using wallet_id
      * const result = await client.wallets.transfer({
-     *   from_address: '0x123...',
+     *   wallet_id: 'd1096269-f986-4fa6-a1f5-1a29ef69f6e4',
      *   to_address: '0x456...',
-     *   amount: '0.1',
+     *   amount: '0.0001',
      *   token: 'ETH',
-     *   network: 'base-sepolia',
+     *   network: 'base-mainnet',
      * });
      * console.log('TX Hash:', result.tx_hash);
+     *
+     * // Transfer using from_address
+     * const result2 = await client.wallets.transfer({
+     *   from_address: '0xaA2e82E5fCF97003d409Bc90826F40cfc8F27510',
+     *   to_address: '0x456...',
+     *   amount: '0.0001',
+     *   token: 'ETH',
+     *   network: 'base-mainnet',
+     * });
      * ```
      */
     transfer(request: TransferRequest): Promise<TransferResult>;
@@ -1318,6 +1405,63 @@ declare class WalletClient {
         limit?: number;
         offset?: number;
     }): Promise<TransactionHistory>;
+    /**
+     * Register a custom token for the tenant.
+     *
+     * This allows tracking balances and enabling transfers for custom ERC-20 tokens.
+     *
+     * @param request - Token details including contract address, symbol, decimals
+     * @returns The created token
+     *
+     * @example
+     * ```typescript
+     * const token = await client.wallets.createToken({
+     *   contract_address: '0x...',
+     *   network: 'base-mainnet',
+     *   symbol: 'wSOL',
+     *   name: 'Wrapped Solana',
+     *   decimals: 9,
+     * });
+     * ```
+     */
+    createToken(request: CreateTokenRequest): Promise<Token>;
+    /**
+     * List all tokens available to the tenant.
+     *
+     * Returns both tenant-specific tokens and global tokens.
+     *
+     * @param options - Filter options
+     */
+    listTokens(options?: {
+        network?: string;
+        include_global?: boolean;
+        include_hidden?: boolean;
+    }): Promise<Token[]>;
+    /**
+     * List global tokens (available to all tenants).
+     *
+     * These are well-known tokens like USDC, WETH, DAI, etc.
+     */
+    listGlobalTokens(network?: string): Promise<Token[]>;
+    /**
+     * Get a specific token by ID.
+     */
+    getToken(tokenId: string): Promise<Token>;
+    /**
+     * Get a token by contract address and network.
+     */
+    getTokenByContract(contractAddress: string, network: string): Promise<Token>;
+    /**
+     * Update a custom token.
+     */
+    updateToken(tokenId: string, request: UpdateTokenRequest): Promise<Token>;
+    /**
+     * Delete a custom token (soft delete).
+     */
+    deleteToken(tokenId: string): Promise<{
+        message: string;
+        token_id: string;
+    }>;
 }
 
 /**

package/dist/index.js

@@ -887,7 +887,9 @@ var WalletClient = class {
   // Balances
   // ---------------------------------------------------------------------------
   /**
-   * Get wallet balance
+   * Get wallet balance including custom tokens.
+   * 
+   * Returns native balance (ETH) plus all registered token balances.
    */
   async getBalance(walletId) {
     return this.http.get(`/wallets/${walletId}/balance`);
@@ -951,21 +953,33 @@ var WalletClient = class {
   // Token Transfers
   // ---------------------------------------------------------------------------
   /**
-   * Transfer tokens from one address to another.
+   * Transfer tokens from a CDP wallet to any address.
+   * 
+   * Supports native ETH and ERC-20 tokens. The source wallet must be a CDP-managed wallet.
    * 
-   * @param request - Transfer details
+   * @param request - Transfer details (use wallet_id or from_address)
    * @returns Transaction result with hash and status
    * 
    * @example
    * ```typescript
+   * // Transfer ETH using wallet_id
    * const result = await client.wallets.transfer({
-   *   from_address: '0x123...',
+   *   wallet_id: 'd1096269-f986-4fa6-a1f5-1a29ef69f6e4',
    *   to_address: '0x456...',
-   *   amount: '0.1',
+   *   amount: '0.0001',
    *   token: 'ETH',
-   *   network: 'base-sepolia',
+   *   network: 'base-mainnet',
    * });
    * console.log('TX Hash:', result.tx_hash);
+   * 
+   * // Transfer using from_address
+   * const result2 = await client.wallets.transfer({
+   *   from_address: '0xaA2e82E5fCF97003d409Bc90826F40cfc8F27510',
+   *   to_address: '0x456...',
+   *   amount: '0.0001',
+   *   token: 'ETH',
+   *   network: 'base-mainnet',
+   * });
    * ```
    */
   async transfer(request) {
@@ -1034,6 +1048,81 @@ var WalletClient = class {
       `/wallets/${walletId}/transactions${query ? `?${query}` : ""}`
     );
   }
+  // ---------------------------------------------------------------------------
+  // Token Management
+  // ---------------------------------------------------------------------------
+  /**
+   * Register a custom token for the tenant.
+   * 
+   * This allows tracking balances and enabling transfers for custom ERC-20 tokens.
+   * 
+   * @param request - Token details including contract address, symbol, decimals
+   * @returns The created token
+   * 
+   * @example
+   * ```typescript
+   * const token = await client.wallets.createToken({
+   *   contract_address: '0x...',
+   *   network: 'base-mainnet',
+   *   symbol: 'wSOL',
+   *   name: 'Wrapped Solana',
+   *   decimals: 9,
+   * });
+   * ```
+   */
+  async createToken(request) {
+    return this.http.post("/tokens", request);
+  }
+  /**
+   * List all tokens available to the tenant.
+   * 
+   * Returns both tenant-specific tokens and global tokens.
+   * 
+   * @param options - Filter options
+   */
+  async listTokens(options = {}) {
+    const params = new URLSearchParams();
+    if (options.network) params.set("network", options.network);
+    if (options.include_global !== void 0) params.set("include_global", String(options.include_global));
+    if (options.include_hidden !== void 0) params.set("include_hidden", String(options.include_hidden));
+    const query = params.toString();
+    return this.http.get(`/tokens${query ? `?${query}` : ""}`);
+  }
+  /**
+   * List global tokens (available to all tenants).
+   * 
+   * These are well-known tokens like USDC, WETH, DAI, etc.
+   */
+  async listGlobalTokens(network) {
+    const params = network ? `?network=${network}` : "";
+    return this.http.get(`/tokens/global${params}`);
+  }
+  /**
+   * Get a specific token by ID.
+   */
+  async getToken(tokenId) {
+    return this.http.get(`/tokens/${tokenId}`);
+  }
+  /**
+   * Get a token by contract address and network.
+   */
+  async getTokenByContract(contractAddress, network) {
+    return this.http.get(
+      `/tokens/by-contract/${contractAddress}?network=${encodeURIComponent(network)}`
+    );
+  }
+  /**
+   * Update a custom token.
+   */
+  async updateToken(tokenId, request) {
+    return this.http.patch(`/tokens/${tokenId}`, request);
+  }
+  /**
+   * Delete a custom token (soft delete).
+   */
+  async deleteToken(tokenId) {
+    return this.http.delete(`/tokens/${tokenId}`);
+  }
 };
 
 // src/users.ts

package/dist/index.mjs

@@ -835,7 +835,9 @@ var WalletClient = class {
   // Balances
   // ---------------------------------------------------------------------------
   /**
-   * Get wallet balance
+   * Get wallet balance including custom tokens.
+   * 
+   * Returns native balance (ETH) plus all registered token balances.
    */
   async getBalance(walletId) {
     return this.http.get(`/wallets/${walletId}/balance`);
@@ -899,21 +901,33 @@ var WalletClient = class {
   // Token Transfers
   // ---------------------------------------------------------------------------
   /**
-   * Transfer tokens from one address to another.
+   * Transfer tokens from a CDP wallet to any address.
+   * 
+   * Supports native ETH and ERC-20 tokens. The source wallet must be a CDP-managed wallet.
    * 
-   * @param request - Transfer details
+   * @param request - Transfer details (use wallet_id or from_address)
    * @returns Transaction result with hash and status
    * 
    * @example
    * ```typescript
+   * // Transfer ETH using wallet_id
    * const result = await client.wallets.transfer({
-   *   from_address: '0x123...',
+   *   wallet_id: 'd1096269-f986-4fa6-a1f5-1a29ef69f6e4',
    *   to_address: '0x456...',
-   *   amount: '0.1',
+   *   amount: '0.0001',
    *   token: 'ETH',
-   *   network: 'base-sepolia',
+   *   network: 'base-mainnet',
    * });
    * console.log('TX Hash:', result.tx_hash);
+   * 
+   * // Transfer using from_address
+   * const result2 = await client.wallets.transfer({
+   *   from_address: '0xaA2e82E5fCF97003d409Bc90826F40cfc8F27510',
+   *   to_address: '0x456...',
+   *   amount: '0.0001',
+   *   token: 'ETH',
+   *   network: 'base-mainnet',
+   * });
    * ```
    */
   async transfer(request) {
@@ -982,6 +996,81 @@ var WalletClient = class {
       `/wallets/${walletId}/transactions${query ? `?${query}` : ""}`
     );
   }
+  // ---------------------------------------------------------------------------
+  // Token Management
+  // ---------------------------------------------------------------------------
+  /**
+   * Register a custom token for the tenant.
+   * 
+   * This allows tracking balances and enabling transfers for custom ERC-20 tokens.
+   * 
+   * @param request - Token details including contract address, symbol, decimals
+   * @returns The created token
+   * 
+   * @example
+   * ```typescript
+   * const token = await client.wallets.createToken({
+   *   contract_address: '0x...',
+   *   network: 'base-mainnet',
+   *   symbol: 'wSOL',
+   *   name: 'Wrapped Solana',
+   *   decimals: 9,
+   * });
+   * ```
+   */
+  async createToken(request) {
+    return this.http.post("/tokens", request);
+  }
+  /**
+   * List all tokens available to the tenant.
+   * 
+   * Returns both tenant-specific tokens and global tokens.
+   * 
+   * @param options - Filter options
+   */
+  async listTokens(options = {}) {
+    const params = new URLSearchParams();
+    if (options.network) params.set("network", options.network);
+    if (options.include_global !== void 0) params.set("include_global", String(options.include_global));
+    if (options.include_hidden !== void 0) params.set("include_hidden", String(options.include_hidden));
+    const query = params.toString();
+    return this.http.get(`/tokens${query ? `?${query}` : ""}`);
+  }
+  /**
+   * List global tokens (available to all tenants).
+   * 
+   * These are well-known tokens like USDC, WETH, DAI, etc.
+   */
+  async listGlobalTokens(network) {
+    const params = network ? `?network=${network}` : "";
+    return this.http.get(`/tokens/global${params}`);
+  }
+  /**
+   * Get a specific token by ID.
+   */
+  async getToken(tokenId) {
+    return this.http.get(`/tokens/${tokenId}`);
+  }
+  /**
+   * Get a token by contract address and network.
+   */
+  async getTokenByContract(contractAddress, network) {
+    return this.http.get(
+      `/tokens/by-contract/${contractAddress}?network=${encodeURIComponent(network)}`
+    );
+  }
+  /**
+   * Update a custom token.
+   */
+  async updateToken(tokenId, request) {
+    return this.http.patch(`/tokens/${tokenId}`, request);
+  }
+  /**
+   * Delete a custom token (soft delete).
+   */
+  async deleteToken(tokenId) {
+    return this.http.delete(`/tokens/${tokenId}`);
+  }
 };
 
 // src/users.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proofchain/sdk",
-  "version": "2.1.1",
+  "version": "2.2.0",
   "description": "Official JavaScript/TypeScript SDK for ProofChain - blockchain-anchored document attestation",
   "main": "dist/index.js",
   "module": "dist/index.mjs",