This section provides instructions on how to initialize the WalletKit client, approve sessions with supported namespaces, and respond to session requests, enabling easy integration of Web3 wallets with dapps through a simple and intuitive interface.

​
Content

Links to sections on this page. Some sections are platform specific and are only visible when the platform is selected. To view a summary of useful platform specific topics, check out Extra (Platform Specific) under this section.

Initialization: Creating a new ReownWalletKit instance and initializing it with a projectId from Cloud.

Session: Connection between a dapp and a wallet.

Don’t have a project ID?

Head over to Reown Cloud and create a new project now!

Get started

​
Initialization

To create an instance of ReownWalletKit, you need to pass in the core and metadata parameters.

final _walletKit = ReownWalletKit(
  core: ReownCore(
    projectId: '{YOUR_PROJECT_ID}',
  ),
  metadata: PairingMetadata(
    name: 'Example Wallet',
    description: 'Example wallet description',
    url: 'https://example.com/',
    icons: ['https://example.com/logo.png'],
    redirect: Redirect(
      native: 'examplewallet://',
      universal: 'https://reown.com/examplewallet',
    ),
  ),
);

​
Session

A session is a connection between a dapp and a wallet. It is established when a user approves a session proposal from a dapp. A session is active until the user disconnects from the dapp or the session expires.

​
Namespace Builder

On flutter you don’t need to worry about Namespace Builder as Flutter SDK would handle that for you and generate a namespace object with the supported ones for you to approve.

All you have to do is make sure you register…

  1. wallet’s accounts with _walletKit.registerAccount() for accounts you want events and methods to be enabled on. This is essential if you want to properly form a session object between your wallet and the requester dapp.
  2. request handlers with _walletKit.registerRequestHandler() for methods you want to support on your wallet. Optional but highly recommended if you want to seamlessly create a session object, as we will see in the coming section.
  3. events emitters with _walletKit.registerEventEmitter() for events you want to support on your wallet. Optional but recommended if you plan to send events such as chainChanged and accountsChanged.

And you’ll have to do this for every chain you want to support on your wallet.

// Quick example:

List<String> supportedChains = ['eip155:1', 'eip155:10', ...];
List<String> walletAddresses = ['0x1234......'];
List<String> supportedEvents = ['chainChanged', 'accountsChanged', ...];

Map<String, dynamic Function(String, dynamic)> get _methodHandlers => {
  'personal_sign': personalSignHandler,
  'eth_sendTransaction': ethSendTransactionHandler,
};

for (final chainId in supportedChains) {
  for (var address in walletAddresses) {
    _walletKit!.registerAccount(
      chainId: chainId, // CAIP-2 format chain id
      accountAddress: address, // 0x.... address
    );
  }

  for (var handler in _methodHandlers.entries) {
    _walletKit.registerRequestHandler(
      chainId: chainId,
      method: handler.key,
      handler: handler.value,
    );
  }

  for (final event in supportedEvents) {
    _walletKit.registerEventEmitter(
      chainId: chainId,
      event: event,
    );
  }
}

When a dApp propose a session, with declared namespaces, your wallet will be able to approve an already generated set of namespaces based on your registered accounts, methods and events.

You can access this object in SessionProposalEvent during onSessionProposal event by querying event.params.generatedNamespaces. (See Session Approval below)

You can choose not to use registerRequestHandler to configure your supported methods and rather define them during session approval (See Session Approval below)

By not using registerRequestHandler your methods requests are going to be sent through onSessionRequest event subscription.

If you do choose to use registerRequestHandler (highly recommended) then onSessionRequest event subscription is not going to be called.

Flutter SDK provides a handy MethodsConstants and EventsConstants for already defined set of required and optional values.

​
EVM methods & events

In @walletconnect/ethereum-provider, (our abstracted EVM SDK for apps) we support by default the following Ethereum methods and events:

{
  //...
  methods: [
    "eth_accounts",
    "eth_requestAccounts",
    "eth_sendRawTransaction",
    "eth_sign",
    "eth_signTransaction",
    "eth_signTypedData",
    "eth_signTypedData_v3",
    "eth_signTypedData_v4",
    "eth_sendTransaction",
    "personal_sign",
    "wallet_switchEthereumChain",
    "wallet_addEthereumChain",
    "wallet_getPermissions",
    "wallet_requestPermissions",
    "wallet_registerOnboarding",
    "wallet_watchAsset",
    "wallet_scanQRCode",
    "wallet_sendCalls",
    "wallet_getCallsStatus",
    "wallet_showCallsStatus",
    "wallet_getCapabilities",
  ],
  events: [
    "chainChanged",
    "accountsChanged",
    "message",
    "disconnect",
    "connect",
  ]
}

​
Session Approval

As mentioned before, the SessionProposalEvent is emitted when a dapp initiates a new session with your wallet. The event object will include the information about the dapp and requested namespaces. The wallet should display a prompt for the user to approve or reject the session.

To approve a session, subscribe to onSessionProposal event and call approveSession() passing in the event.id and the namespaces object.

_walletKit.onSessionProposal.subscribe((SessionProposalEvent? event) {
  // display a prompt for the user to approve or reject the session
  // ....
  // If approved
  _walletKit.approveSession(
    id: event.id,
    namespaces: event.params.generatedNamespaces ?? {},
  );
});

As mentioned before, namespaces: should be either event.params.generatedNamespaces! if you decided to use registerRequestHandler method to configure your supported methods or a Map<String, Namespace> object defined by yourself if you decided not to use registerRequestHandler method

​
Pairing

The pair method initiates a pairing process with a dapp using the given uri (QR code from the dapps). To learn more about pairing, checkout out the docs.

Scan the QR code and parse the URI, and pair with the dapp.
Upon the first pairing, you will immediately receive onSessionProposal and onAuthRequest events.

Uri uri = Uri.parse(scannedUriString);
await _walletKit.pair(uri: uri);

​
Session Rejection

To reject the request, pass in an error code and reason according to protocol specs. See also Formatted Errors section.

To reject a session:

_walletKit.onSessionProposal.subscribe((SessionProposalEvent? event) async {
  // display a prompt for the user to approve or reject the session
  // ....
  // If rejected
  await _walletKit.rejectSession(
    id: event.id,
    reason: Errors.getSdkError(Errors.USER_REJECTED).toSignError(),
  );
});

​
Responding to Session requests

To handle a session request, such as personal_sign, you have two ways as explained before, and they are mutually exclusive, so, either you use onSessionRequest event subscription or your methods handlers configured with registerRequestHandler.

  1. The recommended one is to register a request handler for the methods and chains you want to support. So let’s say your wallet supports eip155:1 and eip155:137. This would translate to:
final supportedChains = ['eip155:1', 'eip155:137'];
Map<String, dynamic Function(String, dynamic)> supportedMethods = {
  'personal_sign': _personalSignHandler,
  'eth_sendTransaction': _ethSendTransactionHandler,
};
// Register your handlers as stated in Namespace Builder section
for (var chainId in supportedChains) {
  for (var method in supportedMethods.entries) {
    _walletKit.registerRequestHandler(
      chainId: chainId,
      method: method.key,
      handler: method.value,
    );
  }
}

Future<void> _personalSignHandler(String topic, dynamic params) async {
  final SessionRequest pendingRequest = _walletKit.pendingRequests.getAll().last;
  final int requestId = pendingRequest.id;

  // message should arrive encoded
  final decoded = hex.decode(params.first.substring(2));
  final message = utf8.decode(decoded);

  // display a prompt for the user to approve or reject the request
  // if approved
  if (approved) {
    // Your code to sign the message here
    final signature = await signMessage(message);

    return _walletKit.respondSessionRequest(
      topic: topic,
      response: JsonRpcResponse(
        id: requestId,
        jsonrpc: '2.0',
        result: signature,
      ),
    );
  }

  // if rejected
  return _walletKit.respondSessionRequest(
    topic: topic,
    response: JsonRpcResponse(
      id: id,
      jsonrpc: '2.0',
      error: const JsonRpcError(code: 5001, message: 'User rejected method'),
    ),
  );
}

Future<void> _ethSendTransactionHandler(String topic, dynamic params) async {
  final SessionRequest pendingRequest = _walletKit.pendingRequests.getAll().last;
  final int requestId = pendingRequest.id;
  final String chainId = pendingRequest.chainId;

  final transaction = (params as List<dynamic>).first as Map<String, dynamic>;

  // display a prompt for the user to approve or reject the request
  // if approved
  if (approved) {
    final signedTx = await sendTransaction(transaction, int.parse(chainId));
    // respond to requester
    await _walletKit.respondSessionRequest(
      topic: topic,
      response: JsonRpcResponse(
        id: requestId, 
        jsonrpc: '2.0', 
        result: signedTx,
      ),
    );
  }

  // if rejected
  return _walletKit.respondSessionRequest(
    topic: topic,
    response: JsonRpcResponse(
      id: id,
      jsonrpc: '2.0',
      error: const JsonRpcError(code: 5001, message: 'User rejected method'),
    ),
  );
}
  1. The other way is subscribing to onSessionRequest events (if you didn’t use generatedNamespaces object) and handle the request based on the method that is firing the event.
_walletKit.onSessionRequest.subscribe(_onSessionRequest);

void _onSessionRequest(SessionRequestEvent? event) async {
  if (event != null) {
    final id = event.id;
    final topic = event.topic;
    final method = event.method;
    final chainId = event.chainId;
    final params = event.params as List;

    // message should arrive encoded
    final decoded = hex.decode(params.first.substring(2));
    final message = utf8.decode(decoded);

    // display a prompt for the user to approve or reject the request
    // if approved
    if (approved) {
      // Your code to sign the message here
      final signature = ...

      return _walletKit.respondSessionRequest(
        topic: topic,
        response: JsonRpcResponse(
          id: id,
          jsonrpc: '2.0',
          result: signature,
        ),
      );
    }
    // if rejected
    return _walletKit.respondSessionRequest(
      topic: topic,
      response: JsonRpcResponse(
        id: id,
        jsonrpc: '2.0',
        error: const JsonRpcError(code: 5001, message: 'User rejected method'),
      ),
    );
  }
}

Remember that if you have handlers registered these are going to be triggered instead of the onSessionRequest event.

​
Updating a Session

If you wish to include new accounts, chains or methods in an existing session, updateSession allows you to do so. You need pass in the topic and a new Namespaces object that contains all of the existing namespaces as well as the new data you wish to include.

After you update the session, the dapp connected to your wallet will receive a SessionUpdate event.

await _walletKit.updateSession(topic: 'topic', namespaces: '{}')

​
Extending a Session

To extend the session, call the extendSession method and pass in the new topic. The SessionUpdate event will be emitted from the wallet.

await _walletKit.extendSession(topic: 'topic')

​
Session Disconnect

To initiate a session disconnect, call the disconnectSession method and pass in the topic and a reason.

When either the dapp or the wallet disconnects from a session, a SessionDelete event will be emitted. It’s important to subscribe to this event so you could keep your state up-to-date.

await _walletKit.disconnectSession(
  topic: session.topic,
  reason: Errors.getSdkError(Errors.USER_DISCONNECTED).toSignError(),
);

Using disconnectSession() alone will make the pairing topic persist, i.e, it can be re-used until it expires. If you want to disconnect (remove) the pairing topic as well you would have add another call as follows:

await _walletKit.core.pairing.disconnect(
  topic: pairing.topic,
);

​
Supporting session events

In order to support session events, such as chainChanged or accountChanged, you would have to register an event emitter for such events, for every chain you want to emit an event for (similar to request handlers).

final supportedChains = ['eip155:1', 'eip155:137'];
const supportedEvents = ['chainChanged', 'accountChanged'];
for (var chainId in supportedChains) {
  for (var event in supportedEvents) {
    _walletKit.registerEventEmitter(
      chainId: chainId,
      event: event,
    );
  }
}

And to emit an event, call emitSessionEvent() as follows:

await _walletKit.emitSessionEvent(
  topic: session.topic,
  chainId: 'eip155:1',
  event: SessionEventParams(
    name: 'chainChanged',
    data: 1,
  ),
);

For a better understanding please check out the example wallet and, in particular, the EVMService inside of it.

​
Formatted Errors

Our SDK exports a variety of ready-made error objects for you to use in the different situations. Most commonly used are…

// When user rejects session proposal or method request.
final userRejectedError = Errors.getSdkError(Errors.USER_REJECTED).toSignError();

// When the request coming to your wallet can not be unparsed
final malformedRequest = Errors.getSdkError(Errors.MALFORMED_REQUEST_PARAMS).toSignError();

// When user disconnects the session
final userDisconnected = Errors.getSdkError(Errors.USER_DISCONNECTED).toSignError();

// When dapp request an unsupported method to your wallet
final unsupportedMethods = Errors.getSdkError(Errors.UNSUPPORTED_METHODS).toSignError();

But you can check the full list of available errors here