# ERC-5169: Client Script URI (TokenScript)

Source: https://www.eipsfordesigners.com/standards/ERC-5169
Agent brief: https://www.eipsfordesigners.com/standards/ERC-5169/agent.md
Machine-readable JSON: https://www.eipsfordesigners.com/api/standards/ERC-5169
Last reviewed: 2026-09-18
Last updated: 2026-09-18

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

## UX Impact

Supporting clients can discover token scripts through an array of scriptURI locations. TokenScript is one possible format. Verify authenticity and integrity, handle ScriptUpdate, and obtain consent before exposing script-driven actions. Format support, sandboxing and capability control belong to the client, not the URI interface.

## Summary

ERC-5169 lets token contracts publish script locations for compatible clients. The interface returns an array of URIs; it does not mandate TokenScript or universal wallet support. Clients must check authenticity, supported format and execution permissions before exposing script-driven actions.

## 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

scriptURI() returns an array of script URIs. TokenScript is one possible client-supported format, not the format mandated by this standard.

### Discovery

A supporting wallet or app selects a supported script format, verifies the source and integrity, and only then offers actions. ScriptUpdate notifies consumers that the locations changed.

### 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/)

## UX Patterns

### Dynamic Token Actions

Discover actions from scriptURI.

Components: ActionList, ScriptBadge

User flow:

- User views a token in a supporting client
- Client reads the scriptURI array and selects a supported resource
- Client validates source authenticity and integrity under its trust policy
- Expose supported actions only after verification

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

ERC-5169 defines scriptURI() returning string[], an owner-controlled setScriptURI and the ScriptUpdate event. Consumers must validate an immutable location, a content hash in the URI, or the referenced authenticity mechanism. The ERC mandates neither TokenScript nor a sandbox/runtime. Clients must supply format support, execution isolation, capability limits and explicit user consent; failed verification disables actions.