Auxiliary Funds Capability

Abstract

An EIP-5792 compliant capability that allows wallets to indicate to apps that they have access to funds beyond those that can be accounted for by looking up balances onchain given the wallet’s address.

A wallet’s ability to access auxiliary funds is communicated to apps as part of its response to an EIP-5792 wallet_getCapabilities request. The following standard does not specify the source of these auxiliary funds, but some examples are:

• Funds from offchain sources that can be onramped and used just-in-time
• Wallets that manage many accounts, where assets across those accounts can be transfered to the required account before submitting a transaction requested by an app

Motivation

Many applications check users’ balances before letting them complete some action. For example, if a user wants to swap some amount of tokens on a dex, the dex will commonly block the user from doing so if it sees that the user does not have that amount of tokens at their address. However, more advanced wallets have features that let users access funds from other sources. Wallets need a way to tell apps that they have access to additional funds so that users using these more advanced wallets are not blocked by balance checks.

Specification

One new EIP-5792 wallet capability is defined.

Wallet Implementation

To conform to this specification, wallets that wish to indicate that they have access to auxiliary funds MUST, for each chain they have access to auxiliary funds on, respond to wallet_getCapabilities calls with an auxiliaryFunds object with a supported field set to true.

Wallets may also optionally specify which assets they have additional access to with an assets field, which maps to an array of addresses representing the assets the wallet might have additional access to. If a wallet does not respond with this optional array of assets, the application SHOULD assume the wallet has additional access to any asset.

This specification does not put any constraints on the source of the auxiliary funds.

In this specification, a chain’s native asset (e.g. Ether on Ethereum) MUST be represented by “0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE” as specified by EIP-7528.

wallet_getCapabilities Response Specification

type AuxiliaryFundsCapability = {
  supported: boolean;
  assets?: `0x${string}`[];
};

wallet_getCapabilities Example Response

{
  "0x2105": {
    "auxiliaryFunds": {
      "supported": true,
      "assets": [
        "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
        "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
      ]
    }
  },
  "0x14A34": {
    "auxiliaryFunds": {
      "supported": true,
      "assets": [
        "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
        "0x036CbD53842c5426634e7929541eC2318f3dCF7e"
      ]
    }
  }
}

Extended Usage: requiredAssets Parameter

When a wallet indicates support for the auxiliaryFunds capability (i.e., supported: true), applications that use the wallet_sendCalls method MAY include a requiredAssets parameter in the capabilities.auxiliaryFunds object to enable the wallet to leverage this capability.

A wallet’s signaling support for the auxiliaryFunds capability does not necessarily mean they can interpret or use the requiredAssets metadata. The requiredAssets parameter is an optional capability that wallets may or may not support, even when they support the base auxiliaryFunds capability.

Native Asset Handling: Wallets SHOULD deduce native asset requirements (e.g., ETH on Ethereum mainnet) from the call.value field in the calls array rather than requiring explicit specification in requiredAssets. The requiredAssets parameter is primarily intended for token assets that cannot be inferred from call data alone.

This parameter may be necessary because transaction call data alone does not reliably indicate which assets and amounts are needed for successful execution. Calls may involve complex logic or multiple contracts, making it difficult for wallets to infer requirements. By specifying required assets and amounts explicitly, apps ensure wallets have the information needed to provision, bridge, or swap assets as necessary for the transaction to succeed.

wallet_sendCalls Extended Parameter

If included, the requiredAssets parameter MUST be specified within the capabilities.auxiliaryFunds object of the wallet_sendCalls request.

Note: The capabilities object is specified in EIP-5792 where wallet_sendCalls is first defined: “The capabilities field is how an app can communicate with a wallet about capabilities a wallet supports. For example, this is where an app can specify a paymaster service URL from which an ERC-4337 wallet can request a paymasterAndData input for a user operation.”

// Example wallet_sendCalls type extension
type WalletSendCallsRequest = {
  version: string;
  from: `0x${string}`;
  chainId: `0x{string}`;
  atomicRequired: boolean;
  calls: Array<{
    to: `0x${string}`;
    data: string;
    // ... other call fields ...
  }>;
  capabilities?: {
    auxiliaryFunds?: {
      optional?: boolean;
      requiredAssets?: {
        address: `0x${string}`;
        amount: `0x${string}`; // Amount required, as a hex string representing the integer value in the asset's smallest unit
        standard: "erc20" | "erc721" | "erc1155"; // Token standard
        tokenId?: `0x${string}`; // Token ID as a hex string (required for ERC-721 and ERC-1155)
      }[];
    };
  };
};

Example Scenario: Cross-Chain Deposit to Aave

Suppose a user wants to deposit DAI into Aave on Chain X, but their wallet address on Chain X has no DAI or native gas token. However, the wallet has access to funds on Chain Y (e.g., Ethereum mainnet). The app, upon detecting the auxiliaryFunds capability, can construct a wallet_sendCalls request as follows:

{
  "calls": [
    {
      "to": "0xAaveDAIDepositContractOnChainX",
      "data": "0xd0e30db0" // Example encoded deposit function call
    }
  ],
  "capabilities": {
    "auxiliaryFunds": {
      "optional": true,
      "requiredAssets": [
        {
          "address": "0x6B175474E89094C44Da98b954EedeAC495271d0F", // DAI address on Chain X
          "amount": "0x0de0b6b3a7640000", // 1 DAI
          "standard": "erc20"
        }
      ]
    }
  }
}

The wallet, upon receiving this request, can:

• Bridge or swap the required DAI from Chain Y to Chain X
• Ensure the user has enough native asset (e.g., ETH) for gas on Chain X
• Complete the deposit call to Aave on Chain X

This mechanism allows advanced wallets to abstract away the complexity of cross-chain or offchain funding, enabling seamless user experiences even when the user’s onchain balance is insufficient on the target chain.

Token Standard Extensibility

This specification currently supports three token standards with the following field requirements:

• ERC-20: Requires amount field only
• ERC-721: Requires both amount and tokenId fields
• ERC-1155: Requires both amount and tokenId fields

The amount field semantics vary by token standard:

• ERC-20: Represents token quantity in smallest unit (e.g., wei for 18-decimal tokens)
• ERC-721: Represents NFT quantity (typically “0x01” for single NFT instances)
• ERC-1155: Represents quantity of the specified token ID

Future token standards MUST specify additional required fields as properties on the asset object root to maintain extensibility.

Auxiliary Funds and Atomic Execution

Auxiliary funds provisioning (bridging, swapping, or other asset retrieval operations) is independent of the wallet_sendCalls execution lifecycle. The atomicRequired field applies only to the call bundle execution, not to auxiliary funds provisioning.

Error Codes

The following error codes are defined for auxiliary funds provisioning failures.

Applications SHOULD use the wallet_getCallsStatus method to track the status of call bundles that involve auxiliary funds provisioning, as the provisioning process may take time to complete. The status response will indicate whether the auxiliary funds provisioning is in progress, completed, or failed.

App Implementation Guidance

When an app sees that a connected wallet has access to auxiliary funds via the auxiliaryFunds capability in a wallet_getCapabilities response, the app SHOULD NOT block users from taking actions on the basis of asset balance checks.

Apps MAY include the requiredAssets parameter in the capabilities.auxiliaryFunds object to ensure the wallet has the necessary information to provision assets as needed for successful execution. However, apps should be aware that this is an optional capability and should handle cases where wallets do not support or cannot process the requiredAssets metadata gracefully.

Amount Validation

The wallet MUST cross-check the amount value in requiredAssets against the decimal() value specified on the asset’s contract to ensure that the amount is interpreted correctly according to the asset’s decimal precision.

Rationale

Alternatives

Advanced Balance Fetching

An alternative we considered is defining a way for apps to fetch available auxiliary balances. This could be done, for example, by providing a URL as part of the auxiliaryFunds capability that apps could use to fetch auxiliary balance information. However, we ultimately decided that a boolean was enough to indicate to apps that they should not block user actions on the basis of balance checks, and it is minimally burdensome for apps to implement.

The shape of this capability allows for a more advanced extension if apps feel more functionality is needed.

Backwards Compatibility

• Applications SHOULD only include the requiredAssets parameter if the wallet advertises the auxiliaryFunds capability.
• Applications SHOULD include the auxiliaryFunds capability with optional: true to provide metadata to wallets that support this optional capability while maintaining compatibility with wallets that do not.

Security Considerations

• Apps MUST NOT make any assumptions about the source of auxiliary funds. Apps’ smart contracts should still, as they would today, make appropriate balance checks onchain when processing a transaction.
• Applications MUST NOT assume that the wallet will always be able to fulfill the asset requirements, and SHOULD handle failures gracefully.

Copyright

Copyright and related rights waived via CC0.