# EIP-5169: Client Script URI (TokenScript)

Source: https://www.eipsfordesigners.com/standards/EIP-5169
Agent brief: https://www.eipsfordesigners.com/standards/EIP-5169/agent.md
Machine-readable JSON: https://www.eipsfordesigners.com/api/standards/EIP-5169
Last reviewed: 2026-05-25
Last updated: 2026-05-25

| Field | Value |
| --- | --- |
| Status | Final |
| Chain | both |
| Category | Comprehension & Display |
| Journey stages | Specialized Interactions |
| Detailed guide | Yes |
| Official specification | https://eips.ethereum.org/EIPS/eip-5169 |
| Discussion search | https://ethereum-magicians.org/search?q=EIP-5169 |

## UX Impact

Tokens can link to official scripts/mini-dapps — wallets auto-discover functionality like 'Mint', 'Stake', or smart-lock controls. Design implications: fetch and display scriptURI-linked functionality, show available token actions dynamically, indicate script authenticity/source, sandbox script execution. Design decisions: trust model for token-linked scripts (massive security surface), user consent before running scripts, how to present discovered functionality vs built-in features, handling script updates/versioning.

## Summary

Tokens can link to official scripts/mini-dapps — wallets auto-discover functionality like 'Mint', 'Stake', or smart-lock controls.

## For Designers

- You can display scriptURI-linked actions dynamically per token.
- Your UI can show script source and authenticity before execution.
- You can require explicit user consent before running token scripts.

## Applicability

### When to Use

- Tokens have official client scripts for custom actions.
- Wallets want dynamic action discovery.
- You can sandbox and verify script sources.

### When to Avoid

- Token actions are fully covered by built-in wallet features.
- Script trust model cannot be explained to users.
- Security review cannot vet linked scripts.

## Problems It Solves

### Inconsistent behavior across apps

Impact: high

Old way: Each team reinvents copy and edge cases

New way: Shared standard gives predictable UX patterns

### Users surprised by on-chain rules

Impact: high

Old way: Generic transfer UI fails at submit time

New way: Standard-aware UI sets expectations upfront

### Support burden from opaque errors

Impact: medium

Old way: Raw revert reasons in toasts

New way: Mapped states explain what to do next

## Anti-Patterns

### Hiding standard-imposed restrictions until submit

Severity: critical

Users feel tricked when actions fail at the last step

Instead: Show eligibility and badges before the primary CTA

### Protocol jargon in user-facing copy

Severity: high

Non-technical users cannot consent informedly

Instead: Use outcome language with optional technical disclosure

### No fallback when wallet lacks support

Severity: high

Dead-end flows increase churn

Instead: Explain limitation and offer alternate path or network

## Design Decisions

### How much protocol detail do users see?

Recommendation: Lead with outcomes; tuck identifiers behind review.

Rationale: Users decide on consequences, not function selectors.

### What happens when support is missing?

Recommendation: Block with explanation and fallback path.

Rationale: Silent failure feels like a broken product.

### How do you label restricted assets?

Recommendation: Use persistent badges for non-transferable, locked, or expiring states.

Rationale: Hidden restrictions cause rage-quits at transfer time.

## States to Design

### Ready

Trigger: Prerequisites met.

User need: Understand what happens next.

Design response: Enable primary action with plain-language preview.

### Awaiting signature

Trigger: Wallet prompt open.

User need: Know what they are approving.

Design response: Mirror human-readable summary in app and wallet.

### Pending

Trigger: Transaction submitted.

User need: Confidence it is progressing.

Design response: Show status strip with explorer link.

### Succeeded

Trigger: On-chain confirmation.

User need: See updated ownership or balance.

Design response: Celebrate outcome and show new state clearly.

### Failed or reverted

Trigger: Validation or execution failed.

User need: Fix or retry without guessing.

Design response: Name the failed constraint and offer a concrete next step.

## Vocabulary

- Use "Your balance / Your item" instead of "Token ID / Token contract": Ownership language matches mental models.

- Use "Cannot transfer yet" instead of "Transfer reverted": Explain restriction without EVM vocabulary.

- Use "Confirm in wallet" instead of "Sign transaction": Matches wallet UX users already know.

## What to Prototype First

### Primary happy path

Prove the core user promise before edge cases.

Covers: Success state, Clear outcome copy

- Primary CTA
- Confirmation feedback
- Next step

### Blocked or unsupported state

Users discover limits when wallets or chains lack support.

Covers: Unsupported wallet, Wrong network

- Plain-language reason
- Fallback action

### Failure recovery

Trust breaks when errors look like bugs.

Covers: User rejection, Transaction revert

- Retry path
- Support context

### Advanced disclosure

Power users need technical detail without cluttering the default path.

Covers: Contract address, Token ID, Raw status

- Expandable section
- Copy buttons
- Explorer link

## Mental Model

### Token script link

The token contract points to scriptURI, a hosted TokenScript that describes extra actions beyond send and receive.

### Discovery

Wallets and apps fetch the script to render dynamic buttons like Mint, Stake, or Redeem for that token.

### Trust review

Show script source, publisher, and version before execution. Users must understand who authored the actions.

### User consent

Each script-driven action needs explicit approval with plain-language preview, same as any transaction.

### Execution

The script builds the contract call your UI submits. Failed or unverified scripts should disable actions, not fail silently.

## Seen in the Wild

- AlphaWallet: TokenScript pioneer for dynamic token functionality. (https://alphawallet.com/)

- TokenScript: Framework for token-linked client scripts. (https://tokenscript.org/)

- Rainbow: Wallet action discovery patterns for tokens. (https://rainbow.me/)

## On Monad

### Confirmation speed

Ethereum: Multi-step flows can feel slow between signatures

Monad: Sub-second finality tightens feedback loops

Design implication: Prefer inline status over long pending modals on Monad.

### Transaction cost

Ethereum: Gas can discourage exploratory actions

Monad: Lower fees enable lighter-weight interactions

Design implication: Safe to offer preview retries and social actions more freely.

## UX Patterns

### Dynamic Token Actions

Discover actions from scriptURI.

Components: ActionList, ScriptBadge

User flow:

- User views token
- Wallet fetches scriptURI
- Actions appear
- User selects action

Mockup registry key: `concept/typed-data` (React UI on the live standard page).

### Script Consent Modal

Explicit approval before script execution.

Components: ConsentModal, SourceIndicator

User flow:

- Action selected
- Script source shown
- User approves
- Script runs sandboxed

Mockup registry key: `concept/verify-safety` (React UI on the live standard page).

## Related Standards

- ERC-1046: Token logo and metadata complement

- EIP-747: Token icon and metadata standards

## Technical Notes

EIP-5169 scriptURI links require strict trust model and user consent before execution.