Wallet Call API

WalletConnect supports EIP-5792, which defines new JSON-RPC methods that enable apps to ask a wallet to process a batch of onchain write calls and to check on the status of those calls. Applications can specify that these onchain calls be executed taking advantage of specific capabilities previously expressed by the wallet; an additional, a novel wallet RPC is defined to enable apps to query the wallet for those capabilities.

wallet_sendCalls: Requests that a wallet submits a batch of calls.
wallet_getCallsStatus: Returns the status of a call batch that was sent via wallet_sendCalls.
wallet_showCallsStatus: Requests that a wallet shows information about a given call bundle that was sent with wallet_sendCalls.
wallet_getCapabilities: This RPC allows an application to request capabilities from a wallet (e.g. batch transactions, paymaster communication).

Usage

wallet_getCapabilities

Capabilities in CAIP-25 Connection Requests

CAIP-25 defines how capabilities can be expressed in wallet-to-dapp connections. These capabilities control how methods like wallet_sendCalls behave.

Session Properties

In a connection request, dapps can request capabilities via sessionProperties. These can be universal (across all chains) or chain-specific:

"sessionProperties": {
  "expiry": "2022-12-24T17:07:31+00:00",
  "caip154": {
    "supported": "true"
  },
  "flow-control": {
    "loose": [], 
    "strict": [],
    "exoticThirdThing": []
  },
  "atomic": {
    "status": "supported"
  }
}

Scoped Properties

For chain-specific capabilities, dapps use scopedProperties:

"scopedProperties": {
  "eip155:8453": {
    "paymasterService": {
      "supported": true
    },
    "sessionKeys": {
      "supported": true
    }
  },
  "eip155:84532": {
    "auxiliaryFunds": {
      "supported": true
    }
  }
}

Wallet Response

A wallet’s response should indicate which capabilities it actually supports, following EIP-5792 and CAIP-25:

"sessionProperties": {
  "expiry": "2022-12-24T17:07:31+00:00",
  "caip154": {
    "supported": "true"
  },
  "flow-control": {
    "loose": ["halt", "continue"],
    "strict": ["continue"]
  },
  "atomic": {
    "status": "ready"
  }
},
"scopedProperties": {
  "eip155:1": {
    "atomic": {
      "status": "supported"
    }
  },
  "eip155:137": {
    "atomic": {
      "status": "unsupported"
    }
  },
  "eip155:84532": {
    "eip155:83532:0x0910e12C68d02B561a34569E1367c9AAb42bd810": {
      "auxiliaryFunds": {
        "supported": false
      },
      "atomic": {
        "status": "supported"
      }
    }
  }
}

Capabilities shared across all address in a namespace can be expressed at top-level
Address-specific capabilities can include exceptions to scope-wide capabilities

Atomic Capability

According to EIP-5792, the atomic capability specifies how the wallet will execute batches of transactions. It has three possible values:

supported - The wallet will execute calls atomically and contiguously
ready - The wallet can upgrade to support atomic execution pending user approval
unsupported - The wallet provides no atomicity guarantees

This capability is expressed per chain and is crucial for determining how wallet_sendCalls with atomicRequired: true will be handled.

Example

The wallet_getCapabilities method is used to request information about what capabilities a wallet supports. Following EIP-5792, here’s how it should be implemented:

Request

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "wallet_getCapabilities",
  "params": ["0xd46e8dd67c5d32be8058bb8eb970870f07244567", ["0x2105", "0x14A34"]]
}

Response

The wallet should return a response following EIP-5792, where capabilities are organized by chain ID:

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "0x2105": {
      "atomic": {
        "status": "supported"
      }
    },
    "0x14A34": {
      "atomic": {
        "status": "unsupported"
      }
    }
  }
}

wallet_sendCalls

Implementation

When implementing wallet_sendCalls, wallets must follow these requirements:

Connection Approval

Only approve this method during the connection approval flow if your wallet can implement it correctly
Define the atomic capability per chain/account in the CAIP-25 response

Request Format

{
  "id": 12345,
  "version": "2.0",
  "method": "wc_sessionRequest",
  "params": {
    "chainId": "caip-2-chain-id",
    "request": {
      "method": "wallet_sendCalls",
      "params": {
        "from": "0xd46e8dd67c5d32be8058bb8eb970870f07244567",
        "chainId": "0x01",
        "atomicRequired": true,
        "calls": [
          {
            "to": "0xd46e8dd67c5d32be8058bb8eb970870f07244567",
            "value": "0x9184e72a",
            "data": "0xd46e8dd67c5d32be8d46e8dd67c5d32be8058bb8eb970870f072445675058bb8eb970870f072445675"
          },
          {
            "to": "0xd46e8dd67c5d32be8058bb8eb970870f07244567",
            "value": "0x182183",
            "data": "0xfbadbaf01"
          }
        ]
      }
    }
  }
}

Core Implementation Requirements

Execute calls in the exact order specified in the request
Do not wait for any calls to be finalized before completing the batch
If the user rejects the request, do not send any calls
When using Wallet Service to get calls status from the bundler (see wallet_getCallsStatus), the returned batchId must be a base64 encoded JSON object with chain_id and user_op_hash fields, example:
```
{
  "chain_id": "0x01",
  "user_op_hash": "0xffff"
}
```

Atomic Execution Behavior

When atomicRequired is true:

Execute all calls atomically (either all succeed or none have any effect)
Execute all calls contiguously (no other transactions between batch calls)
If your wallet can upgrade from ready to supported atomicity, do so before executing

When atomicRequired is false:

You may execute calls sequentially without atomicity guarantees
You may execute atomically if your wallet supports it
You may upgrade to supported atomicity and execute atomically

wallet_getCallsStatus

Example

To enhance the user experience and eliminate the need for app switching, wallets can delegate the Wallet Service to query call status from a bundler. This delegation is configured during session approval by specifying the Wallet Service URL in the scoped properties.

When configured, the dApp will automatically route all subsequent wallet_getCallsStatus requests through the delegated wallet service to the designated bundler.

To implement this functionality, use WalletKit.buildWalletService(bundlerUrl, methods) util method that specifies the wallet service URL and bundler URL for the supported methods:

let scopedProperties: [String: Any] = [
    "eip155": WalletKit.buildWalletService(
       "${bundler_url}",
        ["wallet_getCallsStatus"]
    )
]
WalletKit.approveSession(..., scopedProperties)

WalletKit.buildWalletService is not currently available in WalletKit SDK. This method will be available shortly. Please refer to the docs for the latest updates.

Specify the scopedProperties when approving a session:

"scopedProperties": {
  "eip155": {
    "walletService": [{
      "url": "<wallet service URL>",
      "methods": ["wallet_getCallsStatus"]
    }]
  }
}

Response Format

The response format for wallet_getCallsStatus varies based on the execution method:

For Atomic Execution

{
  "receipts": [/* single receipt or array of receipts */],
  "atomic": true
}

For Non-Atomic Execution

{
  "receipts": [/* array of receipts for all transactions */],
  "atomic": false
}

For non-atomic execution, include all transactions in the receipts array, even those that were included on-chain but eventually reverted.

References

EIP-5792: https://eips.ethereum.org/EIPS/eip-5792#atomicbatch-capability
CAIP-25 namespaces: https://github.com/ChainAgnostic/namespaces/blob/main/eip155/caip25.md

Core

Notifications

Cloud

Usage

Capabilities in CAIP-25 Connection Requests

Session Properties

Scoped Properties

Wallet Response

Atomic Capability

Example

Request

Response

Implementation

Connection Approval

Request Format

Core Implementation Requirements

Atomic Execution Behavior

Example

Response Format

For Atomic Execution

For Non-Atomic Execution

References

Core

Notifications

Cloud

​Usage

​References

Usage

References