Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.sequence.xyz/llms.txt

Use this file to discover all available pages before exploring further.

This page collects practical guidance and common gotchas when constructing explicit session permissions for the Ecosystem Wallet (Web SDK / @0xsequence/connect). If you haven’t set up Connect yet, start with Getting Started.

​
Mental model

An explicit session is a bounded authority grant:
  • Scope: what calls are allowed (targets + function signatures + parameter rules)
  • Budget: how much value can move (native spend limit, ERC20 limits)
  • Time: expiration window
When you request an explicit session, the user approves that permission set in the wallet UI. After approval, your dApp (or server-side automation, depending on your architecture) can execute transactions within those boundaries without repeatedly prompting the user.

​
Permission construction patterns

If your use case has a known contract target (e.g. “deposit into Aave pool”, “mint from this NFT contract”), prefer a tight permission with:
  • a single address
  • a concrete functionSignature
  • parameter rules
This is the most secure and easiest to reason about.

​
2) Open-ended recipient transfers (requires different construction)

If your UX is “send tokens to any recipient” (e.g. a wallet app experience), you are granting broader authority. Guidance:
  • For open-ended ERC20 transfers, the canonical approach is allowing the token contract transfer(address to, uint256 value) with a value limit rule (and no to=EQUAL rule).
  • For open-ended native token sends, use a forwarder pattern. In Sequence wallet configurations, a common approach is granting a target permission for the chain’s ValueForwarder and sending native via a forward call.
If your dApp does not need open-ended recipients, don’t grant them.

​
Fee options & why they matter (dispatch behavior)

When sending a transaction via Sequence relaying, a fee option is selected to pay for execution.

​
Key behaviors

  • If your app relies on relayed transactions, the relayer must be able to determine how fees are paid.
  • In practice, your app should either:
    • enable automatic fee permission inclusion (see includeFeeOptionPermissions), or
    • explicitly include the required fee-related permissions in the session.

​
Common gotcha

Developers often construct a perfectly valid call permission (e.g. ERC20 transfer) but omit fee-related permissions. The transaction may then fail at dispatch time because the relayer cannot select a valid fee payment path. Recommendation: for most dApps, enable includeFeeOptionPermissions unless you have a reason to fully control the fee-permission shape.

​
Lower-level debugging with @0xsequence/dapp-client-cli

The Web SDK abstracts much of the underlying machinery. When you need to debug “what is the relayer doing?”, the CLI can be a useful lens.

​
Helpful workflows

  1. Inspect fee options for a transaction bundle:
npx @0xsequence/dapp-client-cli fee-options \
  --chain-id <chainId> \
  --transactions '<json array of {to,data,value}>'
  1. Send a transaction with an explicitly chosen fee option:
npx @0xsequence/dapp-client-cli send-transaction \
  --chain-id <chainId> \
  --transactions '<json array of {to,data,value}>' \
  --fee-option '<json object from fee-options>'
  1. Compare the permission set you requested vs the calls you are attempting to make.
Tip: start from a target-specific permission set, then progressively widen scope as needed.