diff --git a/STYLE_GUIDE.md b/STYLE_GUIDE.md index 76d8307..d86d2ca 100644 --- a/STYLE_GUIDE.md +++ b/STYLE_GUIDE.md @@ -59,7 +59,7 @@ The EVM section is the primary developer resource for building on Sei. It covers - **seid CLI**: Installation, querying, and transactions - **Frontend Development**: Sei Global Wallet, building frontends - **Smart Contracts**: Development with Hardhat/Foundry, contract wizard, debugging, tracing, verification, precompiles -- **sei-js Library**: External links to sei-js documentation (Scaffold Sei, MCP Server, X402, Ledger) +- **Developer tooling**: sei-js packages, Scaffold Sei, MCP Server, x402, and Ledger - **Ecosystem Tutorials**: Indexers, wallet integrations, bridging, AI tooling, oracles, VRF - **Reference**: Transactions, RPC reference, tokens, changelog, ecosystem contracts - **Hardware Wallets**: Ledger integration with Ethers diff --git a/ai/mcp-server.mdx b/ai/mcp-server.mdx index 546eea6..590f226 100644 --- a/ai/mcp-server.mdx +++ b/ai/mcp-server.mdx @@ -3,9 +3,11 @@ title: 'MCP Server' description: 'Enable AI assistants to interact with Sei networks through natural language using the Model Context Protocol' keywords: ['mcp', 'ai', 'model context protocol', 'claude', 'cursor', 'windsurf', 'blockchain ai'] --- -The Sei Model Context Protocol (MCP) Server enables AI assistants to interact with Sei networks through natural language. Built on the [Model Context Protocol](https://modelcontextprotocol.io/) standard, it provides seamless blockchain integration for AI coding assistants. +The Sei Model Context Protocol (MCP) Server enables AI assistants to interact with Sei networks through natural language. Built on the [Model Context Protocol](https://modelcontextprotocol.io/) standard, it provides blockchain tools for AI coding assistants. -The Sei MCP Server is open source. Contribute at [github.com/sei-protocol/sei-js](https://github.com/sei-protocol/sei-js/tree/main/packages/mcp-server) +The Sei MCP Server is open source. Contribute at [github.com/sei-protocol/sei-js](https://github.com/sei-protocol/sei-js/tree/main/packages/mcp-server). `@sei-js/mcp-server@1` requires Node.js 20 or newer. + +The server starts in read-only mode. Wallet tools that sign or broadcast are hidden unless you set `WALLET_MODE=private-key` and `PRIVATE_KEY` on the default stdio transport. ## What is MCP? @@ -23,13 +25,13 @@ The Sei MCP Server leverages this protocol to bring blockchain functionality dir | Category | Features | | --- | --- | | Account Management | Wallet addresses • Balance queries • Contract verification | -| Token Operations | SEI transfers • ERC20/721/1155 support • Token approvals | +| Token Operations | SEI, ERC-20, ERC-721, and ERC-1155 reads. Transfers and approvals need wallet mode. | | Blockchain Data | Block information • Transaction details • Network status | -| Smart Contracts | State queries • Function execution • Event logs | +| Smart Contracts | State queries. Function execution and contract deploys need wallet mode. | | Networks | Mainnet • Testnet | -## Setup Guide +## Setup guide @@ -50,10 +52,7 @@ Click **"Add new Global MCP server"** and add this configuration to `mcp.json`: "mcpServers": { "sei-mcp-server": { "command": "npx", - "args": ["-y", "@sei-js/mcp-server"], - "env": { - "PRIVATE_KEY": "your_private_key_here" - } + "args": ["-y", "@sei-js/mcp-server"] } } } @@ -85,10 +84,7 @@ Add the Sei MCP Server to your configuration: "mcpServers": { "sei": { "command": "npx", - "args": ["-y", "@sei-js/mcp-server"], - "env": { - "PRIVATE_KEY": "your_private_key_here" - } + "args": ["-y", "@sei-js/mcp-server"] } } } @@ -120,10 +116,7 @@ Open **Settings** → **Developer** → **Edit Config** and add: "mcpServers": { "sei": { "command": "npx", - "args": ["-y", "@sei-js/mcp-server"], - "env": { - "PRIVATE_KEY": "your_private_key_here" - } + "args": ["-y", "@sei-js/mcp-server"] } } } @@ -168,121 +161,160 @@ The Sei MCP Server activates automatically in your session. -## Private Key Setup +## Private key setup + +The server starts in read-only mode. To enable wallet tools over the default stdio transport, add both variables to the server's `env` configuration: + +```json +{ + "mcpServers": { + "sei": { + "command": "npx", + "args": ["-y", "@sei-js/mcp-server"], + "env": { + "WALLET_MODE": "private-key", + "PRIVATE_KEY": "0x_your_private_key_here" + } + } + } +} +``` -**Security Notice**: Generate a dedicated wallet for MCP operations. Never use your main wallet's private key. +Create a dedicated wallet for MCP operations. Never use your main wallet's private key. The `0x` prefix on `PRIVATE_KEY` is optional. Wallet mode is blocked on HTTP transports. Startup fails if private-key mode is misconfigured instead of silently disabling wallet tools. Export your private key from your wallet: -- Look for "Export Private Key" or "Show Private Key" in wallet settings -- Ensure the key starts with `0x` +- Look for **Export Private Key** or **Show Private Key** in wallet settings - Fund the wallet with small amounts for testing ## Features The Sei MCP Server enables your AI assistant to: -### Blockchain Operations - -- Query account balances and transaction history -- Execute token transfers -- Interact with smart contracts -- Monitor network status - -### Coming Soon - -- Documentation search and explanation -- @sei-js library integration -- Boilerplate generation -- DeFi protocol interactions - -## Available Tools - -### Core Operations - -| Tool | Purpose | Example | -| --- | --- | --- | -| `get_address_from_private_key` | Retrieve wallet address | "What's my wallet address?" | -| `get_balance` | Check SEI balance | "Check balance of 0x123..." | -| `transfer_sei` | Send SEI tokens | "Send 1 SEI to 0x456..." | -| `is_contract` | Verify contract address | "Is 0x789... a contract?" | - - -### Token Management - -| Tool | Purpose | Example | -| --- | --- | --- | -| `get_token_info` | Token metadata | "Get USDC token info" | -| `get_token_balance` | Token balance | "Check my USDC balance" | -| `transfer_token` | Token transfer | "Send 100 USDC to 0x123..." | -| `approve_token_spending` | Token approval | "Approve DEX for USDC" | - - -### NFT Operations - -| Tool | Purpose | Example | -| --- | --- | --- | -| `get_nft_info` | NFT metadata | "Show NFT #123 details" | -| `check_nft_ownership` | Ownership verification | "Who owns NFT #456?" | -| `transfer_nft` | NFT transfer | "Send NFT #789 to 0xABC..." | -| `get_nft_balance` | Collection balance | "How many NFTs do I own?" | - - -### Blockchain Data - -| Tool | Purpose | Example | -| --- | --- | --- | -| `get_chain_info` | Network information | "Show Sei mainnet info" | -| `get_block_by_number` | Block details by number | "Get block 12345" | -| `get_latest_block` | Latest block details | "Get latest block" | -| `get_transaction` | Transaction data | "Show tx 0xTXID..." | -| `read_contract` | Contract state | "Read DEX reserves" | - - -## AI Prompts - -Pre-configured prompts for common tasks: - -
-
-

my_wallet_address

-

Get your wallet address

-
-
-

explore_block

-

Analyze block data

-
-
-

analyze_transaction

-

Transaction details

-
-
-

analyze_address

-

Address analysis

-
-
- -## Usage Examples - -
-
-

Query Balance

-

"What's my SEI balance?"

-

→ Returns wallet balance and address

-
- -
-

Send Transaction

-

"Send 1 SEI to 0x742d35Cc6634C0532925a3b844Bc454e4438f44e"

-

→ Executes transfer and returns transaction hash

-
- -
-

Contract Analysis

-

"Is 0x3894085ef7ff0f0aedf52e2a2704928d1ec074f1 a contract?"

-

→ Identifies contract type and metadata

-
-
+- Query account balances, tokens, NFTs, blocks, and transactions (read-only) +- Search the official Sei docs, including `@sei-js` references (`search_docs`) +- Monitor network status for Pacific-1 and Atlantic-2 +- Execute token transfers, NFT transfers, contract writes, and deploys when wallet mode is enabled on stdio + +## Available tools + +Read-only tools stay registered when wallet mode is disabled. Signing and broadcasting tools are hidden until you enable wallet mode on stdio. + +Network arguments accept `sei`, `sei-testnet`, `1329`, `1328`, `0x531`, or `0x530`. Unknown networks are rejected. Chain-info responses omit RPC URLs. + +`search_docs` queries [docs.sei.io](/). There is no `search_sei_js_docs` tool. + +### Core operations + +| Tool | Purpose | Example | Wallet mode | +| --- | --- | --- | --- | +| `search_docs` | Search the official Sei docs | "How do I use the staking precompile?" | No | +| `get_supported_networks` | List supported networks | "Which Sei networks are available?" | No | +| `get_chain_info` | Network chain ID and latest block | "Show Sei mainnet info" | No | +| `get_balance` | Native SEI balance | "Check balance of 0x123..." | No | +| `is_contract` | Verify a contract address | "Is 0x789... a contract?" | No | +| `read_contract` | Call a read-only contract function | "Read DEX reserves" | No | +| `estimate_gas` | Estimate gas for a call | "How much gas does this transfer need?" | No | +| `get_address_from_private_key` | Address for the configured key | "What's my wallet address?" | Required | +| `transfer_sei` | Send SEI | "Send 1 SEI to 0x456..." | Required | +| `write_contract` | Call a state-changing contract function | "Call transfer on this contract" | Required | +| `deploy_contract` | Deploy bytecode | "Deploy this contract" | Required | + +### Token management + +| Tool | Purpose | Example | Wallet mode | +| --- | --- | --- | --- | +| `get_token_info` | ERC-20 metadata | "Get USDC token info" | No | +| `get_token_balance` | ERC-20 balance (`tokenAddress`, `ownerAddress`) | "Check my USDC balance" | No | +| `transfer_token` | ERC-20 transfer (`tokenAddress`, `toAddress`, `amount`) | "Send 100 USDC to 0x123..." | Required | +| `approve_token_spending` | ERC-20 approval | "Approve a DEX for USDC" | Required | + +Reach for `get_token_balance` and `transfer_token`. The server also registers aliases for backward compatibility: `get_erc20_balance` and `get_token_balance_erc20` behave like `get_token_balance` but name the holder argument `address` instead of `ownerAddress`, and `transfer_erc20` is `transfer_token` under a different name with the same arguments. + +### NFT and ERC-1155 + +| Tool | Purpose | Example | Wallet mode | +| --- | --- | --- | --- | +| `get_nft_info` | ERC-721 metadata | "Show NFT #123 details" | No | +| `check_nft_ownership` | ERC-721 owner check (`ownerAddress` in, boolean out). Failures error instead of returning `false`. | "Does 0x… own NFT #456?" | No | +| `get_nft_balance` | ERC-721 collection balance | "How many NFTs do I own?" | No | +| `get_erc1155_balance` | ERC-1155 balance | "Check my ERC-1155 balance" | No | +| `get_erc1155_token_uri` | ERC-1155 token URI | "Get the URI for this ERC-1155" | No | +| `transfer_nft` | ERC-721 `safeTransferFrom` | "Send NFT #789 to 0xABC..." | Required | +| `transfer_erc1155` | ERC-1155 transfer | "Send this ERC-1155 to 0xABC..." | Required | + +NFT ownership lookup failures propagate as errors instead of reporting `false`. ERC-721 transfers use `safeTransferFrom`, so contract recipients must implement `onERC721Received`. + +### Blocks and transactions + +| Tool | Purpose | Example | Wallet mode | +| --- | --- | --- | --- | +| `get_block_by_number` | Block by number | "Get block 12345" | No | +| `get_latest_block` | Latest block | "Get the latest block" | No | +| `get_transaction` | Transaction data | "Show tx 0xTXID..." | No | +| `get_transaction_receipt` | Transaction receipt | "Get the receipt for 0xTXID..." | No | + +## AI prompts + +These prompts are always available, including in read-only mode: + + + + Analyze block data + + + Break down transaction details + + + Inspect an address and its activity + + + Summarize token metadata and balances + + + Walk through calling a contract + + + Explain an EVM concept in context + + + Compare Pacific-1 and Atlantic-2 + + + +These prompts require wallet mode on the stdio transport: + + + + Return the configured wallet address + + + Guide you through sending a transaction + + + Guide you through a token transfer + + + +## Usage examples + + + + "What's my SEI balance?" + + Calls `get_balance` and returns the wallet balance and address. + + + "Send 1 SEI to 0x742d35Cc6634C0532925a3b844Bc454e4438f44e" + + Calls `transfer_sei` and returns the transaction hash. Requires wallet mode. + + + "Is 0x3894085ef7ff0f0aedf52e2a2704928d1ec074f1 a contract?" + + Calls `is_contract` and identifies the contract type and metadata. + + ## Resource URIs @@ -299,7 +331,6 @@ evm://sei/block/12345 # Transactions evm://sei/tx/0xabc123... -evm://sei/tx/0xabc123.../receipt # Token data evm://sei/token/0x3894085ef7ff0f0aedf52e2a2704928d1ec074f1 @@ -312,53 +343,76 @@ evm://sei/nft/0xNFT_ADDRESS/123/isOwnedBy/0x742d... ## Configuration -### Environment Setup +Client-launched servers (`npx` from Cursor, Claude Desktop, or similar) read variables from the MCP client's `env` object. A project-local `.env` is loaded only when the process starts in a directory that contains one, such as a local checkout. ```bash -# .env file -PRIVATE_KEY=0x_your_private_key_here +# Default: read-only mode +WALLET_MODE=disabled + +# Optional RPC overrides +MAINNET_RPC_URL=https://your-mainnet-rpc.example +TESTNET_RPC_URL=https://your-testnet-rpc.example -# Optional (coming soon) -CUSTOM_RPC_URL=https://your-rpc.com -CUSTOM_CHAIN_ID=1329 +# Optional wallet tools for stdio transport only +# WALLET_MODE=private-key +# PRIVATE_KEY=0x_your_private_key_here ``` -### HTTP Server Mode +| Variable | Default | Notes | +| --- | --- | --- | +| `WALLET_MODE` | `disabled` | `private-key` enables signing tools on stdio | +| `PRIVATE_KEY` | unset | Required when `WALLET_MODE=private-key`. `0x` prefix optional | +| `MAINNET_RPC_URL` | public mainnet RPC | Used only for upstream connections | +| `TESTNET_RPC_URL` | public testnet RPC | Used only for upstream connections | +| `SERVER_TRANSPORT` | `stdio` | `streamable-http` or `http-sse` for HTTP | +| `SERVER_HOST` | `localhost` | HTTP listener host | +| `SERVER_PORT` | `8080` | HTTP listener port | +| `SERVER_PATH` | `/mcp` | HTTP endpoint path | +| `SSE_MAX_SESSIONS` | `100` | Legacy SSE concurrent session cap | +| `STREAMABLE_HTTP_MAX_REQUESTS` | `100` | Streamable HTTP concurrent request cap | -For web applications: +CLI flags such as `--http` are not supported. Set `SERVER_TRANSPORT` instead. Run `npx -y @sei-js/mcp-server --help` for the current reference. -```bash -# Start HTTP server -npx @sei-js/mcp-server --http +### HTTP server mode -# Connect from web app -const eventSource = new EventSource('http://localhost:3001/sse'); +Streamable HTTP is the HTTP transport for new integrations: + +```bash +SERVER_TRANSPORT=streamable-http \ +SERVER_HOST=127.0.0.1 \ +SERVER_PORT=8080 \ +npx -y @sei-js/mcp-server ``` -## Security Guidelines +Connect to `http://127.0.0.1:8080/mcp`. Change the listener with `SERVER_HOST`, `SERVER_PORT`, and `SERVER_PATH`. - -**Security Guidelines:** +Legacy HTTP/SSE is available for older clients: -1. **Use a dedicated wallet** - Create a new wallet specifically for MCP -2. **Minimal funding** - Only add funds needed for testing -3. **Environment variables** - Never hardcode private keys -4. **Monitor activity** - Regularly check transaction history +```bash +SERVER_TRANSPORT=http-sse \ +SERVER_HOST=127.0.0.1 \ +npx -y @sei-js/mcp-server +``` -**For production:** +For `http-sse`, GET `{SERVER_PATH}` is the event stream. Clients POST messages to `{SERVER_PATH}/message?sessionId=`. -- Implement transaction limits -- Use multi-signature wallets -- Add contract whitelisting -- Enable rate limiting + +HTTP transports reject wallet mode. They do not authenticate callers or validate `Origin`/`Host`. Bind to `127.0.0.1` for local use, and put any public exposure behind an authenticating reverse proxy. + +## Security guidelines + + +Use a dedicated wallet with only the funds you need for testing. Set `PRIVATE_KEY` through environment variables or the MCP client's `env` object. Never commit it. Review transaction history on that wallet regularly. +Beyond a throwaway test wallet, treat the signing key as production infrastructure: cap the value any single transaction can move, hold funds in a multi-signature wallet and let the agent operate a low-balance hot wallet, restrict the agent to an allowlist of contract addresses, and rate-limit the tools that sign or broadcast. + ## Troubleshooting -**Connection issues**: Verify Node.js 18+ is installed and restart your AI assistant. +**Connection issues**: Verify Node.js 20 or later is installed and restart your AI assistant. -**Private key errors**: Ensure key format starts with `0x` and wallet has sufficient funds. +**Private key errors**: Set `WALLET_MODE=private-key`, provide a valid 32-byte secp256k1 key (`0x` prefix optional), and use the default stdio transport. **Cursor: The model returned an error. Try disabling the MCP servers, or switch models**: Disable "Auto" in the model menu and select a specific model e.g. `claude-4-sonnet` diff --git a/ai/x402.mdx b/ai/x402.mdx index b13f3bf..dac70de 100644 --- a/ai/x402.mdx +++ b/ai/x402.mdx @@ -1,420 +1,300 @@ --- title: 'x402 Protocol on Sei' sidebarTitle: 'x402 Protocol' -description: 'Implement HTTP micropayments on Sei using the x402 protocol for API monetization and digital services.' -keywords: ['x402', 'micropayments', 'HTTP 402', 'API monetization', 'Sei', 'payments', 'blockchain payments', 'USDC', 'web3 payments', 'AxiomKit'] +description: 'Implement HTTP micropayments on Sei using x402 v2 for API monetization and digital services.' +keywords: ['x402', 'x402 v2', 'micropayments', 'HTTP 402', 'API monetization', 'Sei', 'payments', 'USDC', 'web3 payments'] --- -x402 Protocol brings HTTP micro payments to Sei, enabling you to monetize APIs, premium content, and digital services with instant, low-cost payments. Whether you're building AI APIs, data feeds, or premium content platforms, x402 makes it simple to add payment gates to any HTTP endpoint. +x402 is an open protocol for HTTP-native payments. It lets clients pay for APIs, data, content, and other web resources through the standard `402 Payment Required` flow. A service can charge for a single request without requiring the buyer to create an account, manage a subscription, or negotiate a separate billing integration. -**Works with Sei's advantages:** Sei's fast finality, low gas, and EVM compatibility make it perfect for micro payments. x402 leverages these features to enable seamless payment flows that complete in milliseconds. +When a client requests a paid resource, the server responds with the price and payment terms. The client signs a payment authorization and retries the same request. The server verifies and settles the payment before returning the resource. +## Why x402 on Sei? - +x402 payments sit in the request path. The client receives the protected response only after the payment has been authorized and settled. Sei's fast finality reduces this wait, while its low transaction costs make small per-request payments practical. -**Why x402 on Sei?** +Sei EVM also lets you use the upstream `@x402` packages and standard EVM wallet tooling. Native USDC is already included in the x402 default asset registry for Pacific-1 and Atlantic-2, so dollar-denominated route pricing works without a custom token mapping. -- **Fast & Cheap Payments**: Sei's 400ms finality and low gas make micropayments practical. Perfect for pay-per-request APIs and streaming content. -- **EVM Compatible**: Use familiar tools like Viem, Ethers.js, and Hardhat. All existing Ethereum tooling works seamlessly on Sei. -- **Built-in Wallet Support**: Integrates with Sei wallets, MetaMask, and any EIP-6963 compatible wallet for smooth user experiences. + +When you configure x402 on Sei: +- Pacific-1 uses the CAIP-2 network identifier `eip155:1329`. +- Atlantic-2 uses the CAIP-2 network identifier `eip155:1328`. +- `@x402/evm` provides the EVM payment scheme implementation. -## Use Cases on Sei - -The x402 protocol enables a wide range of monetization strategies for web services and APIs: +## How x402 works -- **AI & Machine Learning Services**: Per-inference pricing for LLM APIs, image generation, and data processing. -- **Premium Content & Media**: Pay-per-view articles, videos, and subscription gates. -- **Real-Time Data & APIs**: Market data feeds, weather and IoT data monetization. -- **Infrastructure & CDN Services**: Bandwidth metering and storage payments. +Three components take part in an x402 payment: -## sei-js Integration +- The **client** requests a resource and signs a payment authorization. It can be a user-facing dApp, an autonomous agent, or another service. +- The **resource server** defines the price, validates payment, and returns the protected resource. +- A **facilitator** can verify the authorization, submit the payment onchain, and return the settlement result. You can use a facilitator service, run your own, or settle payments directly. -The `sei-js` library provides a suite of packages to simplify working with x402 on Sei. You can find more details in the [sei-js x402 repository](https://github.com/sei-protocol/sei-x402). + + +The client sends a normal HTTP request to the paid endpoint. + + +The server returns `402 Payment Required`. Its `PAYMENT-REQUIRED` header describes the accepted scheme, amount, asset, network, recipient, and resource. + + +The client selects an accepted payment option and signs the payment payload with its wallet. + + +The client sends the request again with the signed payload in the `PAYMENT-SIGNATURE` header. The x402 Fetch and Axios adapters automate this retry. + + +The resource server verifies the payload against its payment requirements. It then settles directly or asks a facilitator to submit the payment onchain. + + +After successful settlement, the server returns the requested data and includes settlement details in the `PAYMENT-RESPONSE` header. + + -### Core Concepts +### Payment headers -- [**Protocol Overview**](https://github.com/sei-protocol/sei-x402/blob/main/docs/core-concepts/client-server.md): Learn about the architecture of x402. -- [**Quickstart Guide**](https://github.com/sei-protocol/sei-x402/blob/main/docs/getting-started/quickstart-for-sellers.md): Build your first paid API. -- [**Facilitators**](https://github.com/sei-protocol/sei-x402/blob/main/docs/core-concepts/facilitator.md): Understanding payment facilitators. -- [**Client Integration**](https://github.com/sei-protocol/sei-x402/blob/main/docs/getting-started/quickstart-for-buyers.md): How to integrate x402 in your frontend. +| Header | Direction | Purpose | +| --- | --- | --- | +| `PAYMENT-REQUIRED` | Server to client | Describes the payment options accepted for the resource | +| `PAYMENT-SIGNATURE` | Client to server | Carries the signed payment payload | +| `PAYMENT-RESPONSE` | Server to client | Reports the settlement result | -### Available Packages +The header values contain Base64-encoded JSON. The x402 SDK encodes and decodes them for you. -- [**x402**](https://www.npmjs.com/package/@sei-js/x402): The core protocol implementation. -- [**x402-fetch**](https://www.npmjs.com/package/@sei-js/x402-fetch): A fetch wrapper for making x402-compliant requests. -- [**x402-axios**](https://www.npmjs.com/package/@sei-js/x402-axios): Axios interceptors for x402 payments. -- [**x402-express**](https://www.npmjs.com/package/@sei-js/x402-express): Express middleware for serving paid content. -- [**x402-hono**](https://www.npmjs.com/package/@sei-js/x402-hono): Middleware for Hono applications. -- [**x402-next**](https://www.npmjs.com/package/@sei-js/x402-next): Components and utilities for Next.js applications. +### Payment schemes -These packages help streamline both the client-side (paying) and server-side (charging) aspects of the protocol. +x402 v2 supports different settlement models: ---- - -## Axiom Kit Integration +- [`exact`](https://docs.x402.org/schemes/exact) charges a fixed amount for each request. +- [`upto`](https://docs.x402.org/schemes/upto) lets the client authorize a maximum amount while the seller settles the actual usage. +- [`batch-settlement`](https://docs.x402.org/schemes/batch-settlement) uses an escrow deposit and signed vouchers so high-volume services can settle multiple payments together. -While you can build x402 integrations using standard tools and the libraries mentioned above, you can also optionally use Axiom Kit for a more agent-centric approach. This guide demonstrates an end-to-end x402 (HTTP 402 Payment Required) micropayment flow on the Sei testnet using AxiomKit. +For a fixed-price API or paywall, start with the `exact` scheme. -### What is x402? +## Use cases on Sei -x402 is an open standard protocol for internet-native payments that enables users to send and receive payments globally in a simple, secure, and interoperable manner. The protocol leverages the HTTP 402 status code ("Payment Required") to facilitate blockchain-based micropayments directly through HTTP requests. +- Charge per request for AI inference, image generation, data feeds, or other APIs. +- Gate individual articles, media files, and downloads without requiring a subscription. +- Let agents and backend services pay for machine-to-machine resources. +- Bill for measured infrastructure, storage, or bandwidth usage. -#### Key Features of x402: +## Use upstream x402 v2 -- **HTTP-Native**: Uses standard HTTP status codes and headers -- **Blockchain Integration**: Supports multiple blockchain networks -- **Real-time Settlement**: Enables instant payment verification -- **Interoperable**: Works across different payment schemes and networks -- **Micropayment Support**: Designed for small, frequent transactions + +The `@sei-js/x402`, `@sei-js/x402-fetch`, `@sei-js/x402-axios`, `@sei-js/x402-express`, `@sei-js/x402-hono`, and `@sei-js/x402-next` packages are deprecated and no longer maintained. -### Protocol Overview +Do not use them for new integrations. Migrate existing integrations to the upstream x402 v2 packages under the `@x402` npm scope. + -The x402 protocol follows a specific flow: +x402 v2 separates the protocol core, network mechanisms, and HTTP framework adapters into modular packages. -1. **Initial Request**: Client makes a request to a protected resource -2. **402 Response**: Server responds with HTTP 402 and payment requirements -3. **Payment Execution**: Client executes blockchain payment -4. **Payment Proof**: Client includes payment proof in subsequent request -5. **Resource Access**: Server verifies payment and grants access +| Deprecated package | Upstream replacement | +| --- | --- | +| `@sei-js/x402` | `@x402/core` and `@x402/evm` | +| `@sei-js/x402-fetch` | `@x402/fetch` and `@x402/evm` | +| `@sei-js/x402-axios` | `@x402/axios` and `@x402/evm` | +| `@sei-js/x402-express` | `@x402/express`, `@x402/core`, and `@x402/evm` | +| `@sei-js/x402-hono` | `@x402/hono`, `@x402/core`, and `@x402/evm` | +| `@sei-js/x402-next` | `@x402/next`, `@x402/core`, and `@x402/evm` | -### Axiom Integration +## Install x402 v2 -Axiom is a blockchain interaction framework that provides tools and libraries for building decentralized applications. In this implementation, Axiom integrates with x402 to enable seamless blockchain payments within Sei network applications. +Install the EVM mechanism package together with the adapter for your client or server. -#### Axiom Components Used: + + -- **@axiomkit/core**: Core framework for building blockchain agents -- **@axiomkit/sei**: Sei blockchain integration -- **AxiomSeiWallet**: Wallet management for Sei transactions -- **Context and Actions**: Framework for building interactive blockchain agents +```bash +npm install @x402/core @x402/evm @x402/fetch viem +``` -### Sei Blockchain Implementation + + -This implementation uses the Sei testnet for x402 payments with the following configuration: +```bash +npm install @x402/core @x402/evm @x402/axios viem +``` -#### Network Configuration + + -```typescript -export const X402_CONFIG = { - network: 'sei-testnet', - chainId: 1328, - asset: 'USDC', - assetAddress: '0x4fCF1784B31630811181f670Aea7A7bEF803eaED', // Sei Testnet USDC - assetDecimals: 6, - recipient: '0x9dC2aA0038830c052253161B1EE49B9dD449bD66', - rpcUrl: 'https://evm-rpc-testnet.sei-apis.com' -}; +```bash +npm install @x402/core @x402/evm @x402/express ``` -### Technical Architecture + + -The x402 implementation consists of several key components: +```bash +npm install @x402/core @x402/evm @x402/hono +``` -#### 1. Payment Challenge Generation + + -```typescript -function generatePaymentChallenge() { - const reference = `sei-${Date.now()}-${Math.random().toString(36).substring(7)}`; - const amountInUnits = parseUnits('0.001', X402_CONFIG.assetDecimals); - - return { - x402Version: 1, - accepts: [ - { - scheme: 'exact', - network: X402_CONFIG.network, - maxAmountRequired: amountInUnits.toString(), - resource: '/api/weather', - description: 'Get current weather data', - mimeType: 'application/json', - payTo: X402_CONFIG.recipient, - maxTimeoutSeconds: 300, - asset: X402_CONFIG.assetAddress, - extra: { - name: X402_CONFIG.asset, - version: '2', - reference: reference - } - } - ] - }; -} +```bash +npm install @x402/core @x402/evm @x402/next ``` -#### 2. Payment Verification + + -```typescript -async function verifyPayment(paymentHeader: string) { - const paymentData = JSON.parse(Buffer.from(paymentHeader, 'base64').toString()); - const { x402Version, scheme, network, payload } = paymentData; - - // Validate payment format - if (x402Version !== 1 || scheme !== 'exact' || network !== X402_CONFIG.network) { - return { isValid: false, reason: 'Invalid payment format or network' }; - } - - // Verify transaction on-chain - const receipt = await publicClient.getTransactionReceipt({ - hash: payload.txHash as `0x${string}` - }); +Follow the upstream [seller quickstart](https://docs.x402.org/getting-started/quickstart-for-sellers) or [buyer quickstart](https://docs.x402.org/getting-started/quickstart-for-buyers) for the current API. - return { isValid: receipt?.status === 'success', txHash: payload.txHash }; -} -``` +## Configure Sei -#### 3. Axiom Agent Integration +Use the CAIP-2 identifier for your target network when you configure a route: -The Axiom agent handles the complete x402 flow: +| Network | CAIP-2 identifier | Default USDC | +| --- | --- | --- | +| Pacific-1 | `eip155:1329` | `0xe15fC38F6D8c56aF07bbCBe3BAf5708A2Bf42392` | +| Atlantic-2 | `eip155:1328` | `0x4fCF1784B31630811181f670Aea7A7bEF803eaED` | -```typescript -action({ - name: 'getWeather', - description: 'Get current weather data. This requires an x402 payment of $0.001 USDC.', - async handler({ location }, { memory }) { - // Step 1: Request weather data (returns 402 Payment Required) - const weatherResponse = await fetch(`${baseUrl}/api/weather`); - - if (weatherResponse.status !== 402) { - throw new Error(`Expected 402 Payment Required, got ${weatherResponse.status}`); - } - - const paymentChallenge = await weatherResponse.json(); - - // Step 2: Make x402 payment - const txHash = await makeX402Payment(amount, recipient, reference); - - // Step 3: Retry request with payment proof - const paymentProof = { - x402Version: 1, - scheme: 'exact', - network: X402_CONFIG.network, - payload: { txHash, amount, from: seiWallet.walletAddress } - }; - - const weatherDataResponse = await fetch(`${baseUrl}/api/weather`, { - headers: { 'X-Payment': Buffer.from(JSON.stringify(paymentProof)).toString('base64') } - }); - - return weatherDataResponse.json(); - } -}); -``` +Because x402 registers these assets as the defaults for Sei, a price such as `"$0.001"` resolves to the USDC address for the selected network. To accept another ERC-20 token, configure an explicit token amount and its EIP-712 metadata instead. -### Payment Flow + +x402 can express and sign payments for any EVM network, but your facilitator must also support the selected Sei network. Confirm network support with your facilitator before deployment, or run your own facilitator. + -#### 1. Initial Request +See the upstream [network and token support](https://docs.x402.org/core-concepts/network-and-token-support) reference for current asset and facilitator details. -``` -Client → GET /api/weather -Server → 402 Payment Required + Payment Challenge -``` +### What the facilitator does -#### 2. Payment Challenge Response +A facilitator handles the blockchain-specific work on behalf of your resource server. It checks that the signed payload satisfies the advertised payment requirements, submits the authorized transfer, waits for the settlement result, and returns that result to your server. -```json -{ - "x402Version": 1, - "accepts": [ - { - "scheme": "exact", - "network": "sei-testnet", - "maxAmountRequired": "1000", - "resource": "/api/weather", - "description": "Get current weather data", - "mimeType": "application/json", - "payTo": "0x9dC2aA0038830c052253161B1EE49B9dD449bD66", - "maxTimeoutSeconds": 300, - "asset": "0x4fCF1784B31630811181f670Aea7A7bEF803eaED", - "extra": { - "name": "USDC", - "version": "2", - "reference": "sei-1234567890-abc123" - } - } - ] -} -``` +Native USDC on Sei supports EIP-3009. With the `exact` EVM scheme, the buyer signs a transfer authorization instead of submitting the transfer transaction itself. The facilitator submits the transaction and pays the required gas. -#### 3. Payment Execution +## Protect an Express route -The Axiom agent executes a USDC transfer on Sei testnet: +The following x402 v2 example charges `0.001` USDC for `GET /weather` on Atlantic-2. Set `X402_FACILITATOR_URL` to a facilitator that supports `eip155:1328`. ```typescript -const transferData = encodeFunctionData({ - abi: [ - { - name: 'transfer', - type: 'function', - stateMutability: 'nonpayable', - inputs: [ - { name: 'to', type: 'address' }, - { name: 'amount', type: 'uint256' } - ], - outputs: [{ name: '', type: 'bool' }] - } - ], - functionName: 'transfer', - args: [recipient, amountInUnits] -}); - -const hash = await seiWallet.walletClient.sendTransaction({ - to: X402_CONFIG.assetAddress, - data: transferData -}); -``` +import express from "express"; +import { HTTPFacilitatorClient } from "@x402/core/server"; +import { ExactEvmScheme } from "@x402/evm/exact/server"; +import { paymentMiddleware, x402ResourceServer } from "@x402/express"; -#### 4. Payment Proof Submission +const facilitatorUrl = process.env.X402_FACILITATOR_URL; +const payTo = process.env.PAY_TO_ADDRESS as `0x${string}` | undefined; -``` -Client → GET /api/weather + X-Payment Header (base64 encoded payment proof) -Server → Verifies payment + Returns weather data -``` +if (!facilitatorUrl || !payTo) { + throw new Error("Set X402_FACILITATOR_URL and PAY_TO_ADDRESS"); +} -### Code Examples +const app = express(); +const network = "eip155:1328"; +const facilitator = new HTTPFacilitatorClient({ url: facilitatorUrl }); +const resourceServer = new x402ResourceServer(facilitator).register( + network, + new ExactEvmScheme(), +); -#### Complete Weather API Implementation +app.use( + paymentMiddleware( + { + "GET /weather": { + accepts: [ + { + scheme: "exact", + price: "$0.001", + network, + payTo, + }, + ], + description: "Current weather data", + mimeType: "application/json", + }, + }, + resourceServer, + ), +); + +app.get("/weather", (_request, response) => { + response.json({ + location: "Sei", + conditions: "sunny", + }); +}); -```typescript -export async function GET(req: NextRequest) { - const paymentHeader = req.headers.get('x-payment'); - - if (!paymentHeader) { - // No payment provided, return 402 with payment requirements - return NextResponse.json(generatePaymentChallenge(), { status: 402 }); - } - - // Verify the payment - const verification = await verifyPayment(paymentHeader); - - if (!verification.isValid) { - // Invalid payment, return 402 with error - const challenge = generatePaymentChallenge(); - challenge.error = verification.reason || 'Payment verification failed'; - return NextResponse.json(challenge, { status: 402 }); - } - - // Payment verified, return weather data - const weatherData = { - location: 'Sei Network', - temperature: '99°F', - conditions: 'Sunny', - humidity: '45%', - windSpeed: '8 mph', - timestamp: new Date().toISOString(), - payment: verification - }; - - return NextResponse.json(weatherData); -} +app.listen(4021); ``` -#### Axiom Agent Weather Action +The middleware handles the initial `402` response, payment verification, and settlement. Your route handler runs after verification. The middleware buffers its response and sends it to the client only if settlement succeeds. -```typescript -action({ - name: 'getWeather', - description: 'Get current weather data. This requires an x402 payment of $0.001 USDC.', - schema: { - location: z.string().optional().describe('Optional location for weather data.') - }, - async handler({ location }, { memory }) { - try { - // Step 1: Request weather data (this will return 402 Payment Required) - const weatherResponse = await fetch(`${baseUrl}/api/weather`); - - if (weatherResponse.status !== 402) { - throw new Error(`Expected 402 Payment Required, got ${weatherResponse.status}`); - } - - const paymentChallenge = await weatherResponse.json(); - - // Step 2: Make x402 payment - const reference = paymentChallenge.accepts[0].extra.reference; - const amount = '0.001'; // $0.001 USDC - const recipient = paymentChallenge.accepts[0].payTo; - - const txHash = await makeX402Payment(amount, recipient, reference); - - // Step 3: Wait for transaction confirmation - await new Promise((resolve) => setTimeout(resolve, 3000)); - - // Step 4: Retry weather request with payment proof - const paymentProof = { - x402Version: 1, - scheme: 'exact', - network: X402_CONFIG.network, - payload: { - txHash: txHash, - amount: parseUnits(amount, X402_CONFIG.assetDecimals).toString(), - from: seiWallet.walletAddress - } - }; - - const paymentHeader = Buffer.from(JSON.stringify(paymentProof)).toString('base64'); - - const weatherDataResponse = await fetch(`${baseUrl}/api/weather`, { - headers: { - 'Content-Type': 'application/json', - 'X-Payment': paymentHeader - } - }); - - const weatherData = await weatherDataResponse.json(); - - // Update memory - memory.transactions.unshift(txHash); - memory.lastTransaction = txHash; - - return actionResponse(`🌤️ **Weather Data Retrieved** - -**Location:** ${weatherData.location} -**Temperature:** ${weatherData.temperature} -**Conditions:** ${weatherData.conditions} -**Humidity:** ${weatherData.humidity} -**Wind Speed:** ${weatherData.windSpeed} - -✅ **Payment Successful!** - -**Transaction Hash:** ${txHash} -**Amount:** $${amount} USDC -**Status:** Confirmed on Sei Testnet - -🔗 **View Transaction:** [Seiscan](https://testnet.seiscan.io/tx/${txHash})`); - } catch (error) { - return actionResponse(`❌ **Weather Request Failed** - -${error.message} - -Please try again or check your wallet balance for USDC tokens needed for the payment.`); - } - } -}); -``` +## Make a paid request -### Security Considerations +The Fetch adapter handles the client side of the flow. It makes the initial request, reads the `402` response, signs an accepted payment option, and retries with `PAYMENT-SIGNATURE`. -#### Payment Verification +```typescript +import { x402Client } from "@x402/core/client"; +import { ExactEvmScheme } from "@x402/evm/exact/client"; +import { wrapFetchWithPayment } from "@x402/fetch"; +import { privateKeyToAccount } from "viem/accounts"; -- **On-chain Verification**: All payments are verified against the Sei blockchain. -- **Transaction Receipt Validation**: Ensures transaction success and proper recipient. -- **Payment Caching**: Prevents double-spending by caching verified payments. -- **Reference Validation**: Unique payment references prevent replay attacks. +const privateKey = process.env.EVM_PRIVATE_KEY as `0x${string}` | undefined; -#### Network Security +if (!privateKey) { + throw new Error("Set EVM_PRIVATE_KEY"); +} -- **HTTPS Required**: All API communications use secure connections. -- **Base64 Encoding**: Payment proofs are base64 encoded for safe transmission. -- **Timeout Handling**: Payment challenges include timeout mechanisms. -- **Error Handling**: Comprehensive error handling prevents information leakage. +const signer = privateKeyToAccount(privateKey); +const client = new x402Client(); +client.register("eip155:*", new ExactEvmScheme(signer)); -#### Wallet Security +const fetchWithPayment = wrapFetchWithPayment(fetch, client); +const response = await fetchWithPayment("https://api.example.com/weather"); -- **Private Key Management**: Private keys are stored securely in environment variables. -- **Transaction Signing**: All transactions are properly signed before submission. -- **Balance Validation**: Sufficient balance checks before payment execution. +if (!response.ok) { + throw new Error(`Request failed with status ${response.status}`); +} -### Tutorials & Resources +console.log(await response.json()); +``` -- **[Sei-js X402 Repository](https://github.com/sei-protocol/sei-x402)**: Comprehensive guide on using the x402 protocol with the sei-js library, including package details and examples. -- **[AxiomKit X402 Demo Repository](https://github.com/AxiomKit/axiomkit-showcase)**: The complete source code for the Axiom integration demo used in this guide, including installation and configuration instructions. + +Do not treat a successful transaction receipt by itself as proof that a request was paid. Verification must bind the signed payload to the required network, asset, amount, recipient, resource, and validity window. Use the x402 middleware and a compatible facilitator, or implement the complete verification and settlement rules when you self-facilitate. + + +## Production checks + +- Use HTTPS so intermediaries cannot read or replace payment headers. +- Keep buyer wallet keys in a secret manager or another server-side secret store. Do not ship a private key in browser code. +- Confirm facilitator support for Pacific-1 or Atlantic-2 before you deploy. +- Test rejected signatures, expired authorizations, failed settlement, and insufficient balances. +- Fulfill the protected request only after x402 reports a valid payment. + +## Migrate from v1 + +The deprecated `@sei-js/x402*` packages implement the v1 protocol. Migrating requires more than changing package names. + +| v1 | v2 | +| --- | --- | +| `X-PAYMENT` request header | `PAYMENT-SIGNATURE` | +| `X-PAYMENT-RESPONSE` response header | `PAYMENT-RESPONSE` | +| Network names such as `sei-testnet` | CAIP-2 identifiers such as `eip155:1328` | +| `x402Version: 1` | `x402Version: 2` | + +Use the official [x402 v1-to-v2 migration guide](https://docs.x402.org/guides/migration-v1-to-v2) to update client construction, server middleware, payment schemes, headers, and network identifiers. + +## Resources + + + + Read the upstream protocol and SDK documentation. + + + Review source code, examples, and releases. + + + Protect an API or web resource with x402. + + + Add automatic payment handling to a client. + + + Follow the complete request and payment lifecycle. + + + Learn how verification and settlement services work. + + diff --git a/docs.json b/docs.json index 21acf25..09d2c58 100644 --- a/docs.json +++ b/docs.json @@ -208,7 +208,6 @@ "pages": [ "evm/sei-js/index", "evm/sei-js/create-sei", - "evm/sei-js/ledger", "evm/sei-js/registry" ] }, @@ -1268,6 +1267,11 @@ "destination": "/evm/ledger-ethers", "permanent": true }, + { + "source": "/evm/sei-js/ledger", + "destination": "/evm/ledger-ethers", + "permanent": true + }, { "source": "/dev-ecosystem-providers/wallets", "destination": "/learn/wallets", @@ -1579,27 +1583,62 @@ "permanent": true }, { - "source": "/:os(Users|home|root|etc|var|usr|tmp|dev)/:rest*", + "source": "/Users/*", + "destination": "/node/troubleshooting", + "permanent": true + }, + { + "source": "/home/*", + "destination": "/node/troubleshooting", + "permanent": true + }, + { + "source": "/root/*", + "destination": "/node/troubleshooting", + "permanent": true + }, + { + "source": "/etc/*", + "destination": "/node/troubleshooting", + "permanent": true + }, + { + "source": "/var/*", + "destination": "/node/troubleshooting", + "permanent": true + }, + { + "source": "/usr/*", "destination": "/node/troubleshooting", "permanent": true }, { - "source": "/sei-config-:rest(.*)", + "source": "/tmp/*", + "destination": "/node/troubleshooting", + "permanent": true + }, + { + "source": "/dev/*", + "destination": "/node/troubleshooting", + "permanent": true + }, + { + "source": "/sei-config-*", "destination": "/node", "permanent": true }, { - "source": "/sei-data-:rest(.*)", + "source": "/sei-data-*", "destination": "/node", "permanent": true }, { - "source": "/sei-backup-:rest(.*)", + "source": "/sei-backup-*", "destination": "/node/troubleshooting", "permanent": true }, { - "source": "/priv_validator_:rest(.*)", + "source": "/priv_validator_*", "destination": "/node", "permanent": true }, @@ -1635,12 +1674,12 @@ }, { "source": "/agents", - "destination": "/llms/agents.md", + "destination": "/skill.md", "permanent": true }, { - "source": "/agents.md", - "destination": "/llms/agents.md", + "source": "/llms/agents", + "destination": "/skill.md", "permanent": true }, { @@ -1652,11 +1691,6 @@ "source": "/llms/skill", "destination": "/skill.md", "permanent": true - }, - { - "source": "/llms/skill.md", - "destination": "/skill.md", - "permanent": true } ], "interaction": { diff --git a/evm/ai-tooling/agentic-wallets.mdx b/evm/ai-tooling/agentic-wallets.mdx deleted file mode 100644 index c6767d6..0000000 --- a/evm/ai-tooling/agentic-wallets.mdx +++ /dev/null @@ -1,654 +0,0 @@ ---- -title: 'Agentic Wallets' -description: 'Build AI agents with secure, programmable wallets on Sei using Coinbase AgentKit or Privy server wallets. Includes setup guides, policy engines, and a full feature comparison.' -keywords: ['agentic wallets', 'ai agents', 'coinbase agentkit', 'privy', 'server wallets', 'sei ai', 'agent wallet', 'cdp wallet', 'wallet policy engine'] ---- -Agentic wallets give AI agents the ability to hold funds, sign transactions, and interact with smart contracts autonomously — without exposing private keys to the agent or the LLM. This page covers the two leading solutions that work on Sei today: **Coinbase AgentKit** and **Privy server wallets**. - - -Both platforms support Sei as an EVM-compatible chain. No special integration is required — you point the wallet provider at Sei's RPC and chain ID and everything works out of the box. - - -## How It Works - -An agentic wallet sits between your AI agent and the blockchain: - -1. **Agent decides** — The LLM reasons about what onchain action to take (e.g. "send 5 USDC to 0x..."). -2. **SDK prepares** — The wallet SDK constructs and validates the transaction. -3. **Policy check** — The policy engine evaluates the transaction against spending limits, allowlists, and other guardrails. -4. **TEE signs** — The private key, isolated in a Trusted Execution Environment, signs the transaction. The key is never exposed to the agent. -5. **Broadcast** — The signed transaction is submitted to Sei's EVM RPC. - -``` -┌─────────┐ ┌───────────┐ ┌──────────────┐ ┌─────────┐ ┌──────────┐ -│ LLM / │────▶│ Wallet │────▶│ Policy │────▶│ TEE │────▶│ Sei EVM │ -│ Agent │ │ SDK │ │ Engine │ │ Signer │ │ RPC │ -└─────────┘ └───────────┘ └──────────────┘ └─────────┘ └──────────┘ -``` - -## Quick Comparison - -| Dimension | Coinbase AgentKit | Privy Server Wallets | -| --- | --- | --- | -| **Type** | Open-source SDK + wallet infra | Wallet-as-a-service API | -| **Key isolation** | Self-custodial on Sei (bring-your-own key via Viem). CDP's TEE-managed signer does not support Sei. | TEE + Shamir secret sharing | -| **Sei support** | Via `ViemWalletProvider` (TS) or `EthAccountWalletProvider` (Python) | Via CAIP-2 `eip155:1329` | -| **Policy engine** | Spending limits, address/contract allowlists, network restrictions | All of the above + time-based controls, key quorums | -| **Built-in actions** | 40+ action providers (wallet, ERC-20, ERC-721, Pyth on Sei; many others Base/Ethereum-only) | Wallet operations only (create, sign, send) | -| **AI frameworks** | LangChain, Vercel AI SDK, OpenAI Agents SDK, MCP | LangChain (`langchain-privy`) | -| **Server SDKs** | TypeScript, Python | TypeScript, Python, Java, Rust, Go + REST API | -| **Open source** | Yes (MIT) | Partial (`langchain-privy` is OSS) | -| **Pricing** | Free SDK; CDP wallets $0.005/op (5K free/mo) | Free 50K sigs/mo; paid tiers from $299/mo | - - -**Use both together:** AgentKit ships with a built-in `PrivyWalletProvider`, so you can combine Privy's policy engine with AgentKit's 40+ action providers. - ---- - -## Coinbase AgentKit on Sei - -[AgentKit](https://github.com/coinbase/agentkit) is Coinbase's open-source toolkit for giving AI agents crypto wallets and onchain capabilities. It is framework-agnostic (LangChain, Vercel AI SDK, OpenAI Agents SDK, MCP) and wallet-agnostic (CDP wallets, Privy, Viem, and more). - -### Architecture - -AgentKit is organized around three concepts: - -- **Wallet Providers** — Abstraction over different wallet implementations. For Sei, use `ViemWalletProvider` (TypeScript) or `EthAccountWalletProvider` (Python). -- **Action Providers** — Units of onchain functionality (ERC-20 transfers, ERC-721 ops, Pyth price feeds, etc.). Generic EVM providers work on Sei; providers with hard-coded chain allowlists (e.g. `x402ActionProvider`, `wethActionProvider`, CDP-managed ones) do not — see the support matrix below. -- **Framework Extensions** — Adapters that turn AgentKit actions into tools for your AI framework of choice. - -### Prerequisites - -- Node.js v22+ (TypeScript) or Python 3.10+ -- A [CDP Secret API Key](https://portal.cdp.coinbase.com/) (for CDP wallet providers; not required for Viem) -- A funded wallet on Sei - -### Setup - - - - - - - -```bash -npm install @coinbase/agentkit @coinbase/agentkit-langchain viem -``` - - - -Viem ships with `sei` (id `1329`) and `seiTestnet` (id `1328`) out of the box, so you can import them directly from `viem/chains`. - -```typescript -import { AgentKit, ViemWalletProvider, walletActionProvider, erc20ActionProvider } from '@coinbase/agentkit'; -import { createWalletClient, http } from 'viem'; -import { privateKeyToAccount } from 'viem/accounts'; -import { sei } from 'viem/chains'; - -// Create a Viem wallet client pointed at Sei -const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`); -const client = createWalletClient({ - account, - chain: sei, - transport: http('https://evm-rpc.sei-apis.com'), -}); - -// Wrap it in AgentKit -const walletProvider = new ViemWalletProvider(client); -const agentKit = await AgentKit.from({ - walletProvider, - actionProviders: [ - walletActionProvider(), - erc20ActionProvider(), - // Add more action providers as needed - ], -}); -``` - - - -```typescript -import { getLangChainTools } from '@coinbase/agentkit-langchain'; -import { ChatOpenAI } from '@langchain/openai'; -import { createReactAgent } from '@langchain/langgraph/prebuilt'; - -const tools = await getLangChainTools(agentKit); -const model = new ChatOpenAI({ model: 'gpt-4o' }); - -const agent = createReactAgent({ - llm: model, - tools, - messageModifier: - 'You are an AI agent operating on the Sei blockchain. You can check balances, transfer tokens, and interact with smart contracts.', -}); - -// Run the agent -const result = await agent.invoke({ - messages: [{ role: 'user', content: 'What is my SEI balance?' }], -}); -``` - - - - - - - - - - -```bash -pip install coinbase-agentkit coinbase-agentkit-langchain -``` - - - -```python -from coinbase_agentkit import ( - AgentKit, - AgentKitConfig, - EthAccountWalletProvider, - EthAccountWalletProviderConfig, -) -from eth_account import Account - -account = Account.from_key("YOUR_PRIVATE_KEY") - -wallet_provider = EthAccountWalletProvider( - config=EthAccountWalletProviderConfig( - account=account, - chain_id=1329, # Sei mainnet - rpc_url="https://evm-rpc.sei-apis.com", - ) -) - -agent_kit = AgentKit(AgentKitConfig(wallet_provider=wallet_provider)) -``` - - - -```python -from coinbase_agentkit_langchain import get_langchain_tools -from langchain_openai import ChatOpenAI -from langgraph.prebuilt import create_react_agent - -tools = get_langchain_tools(agent_kit) -model = ChatOpenAI(model="gpt-4o") - -agent = create_react_agent( - model, - tools=tools, - state_modifier="You are an AI agent on the Sei blockchain.", -) - -result = agent.invoke({ - "messages": [{"role": "user", "content": "What is my SEI balance?"}] -}) -``` - - - - - - - -### Available Action Providers on Sei - -Not every AgentKit action provider works on Sei — some are chain-specific. Here's what you can use: - -| Action Provider | Works on Sei | Notes | -| --- | --- | --- | -| `walletActionProvider` | Yes | Balance, transfers, native SEI operations | -| `erc20ActionProvider` | Yes | Any ERC-20 token (USDC, WSEI, etc.) | -| `erc721ActionProvider` | Yes | NFT minting, transfers | -| `pythActionProvider` | Yes | Pyth price feeds via Hermes (off-chain, chain-agnostic) | -| `wethActionProvider` | No | Hard-coded WETH addresses; no WSEI entry. Use `erc20ActionProvider` against Sei's WSEI contract instead. | -| `x402ActionProvider` | No | Provider's `SUPPORTED_NETWORKS` allowlist is limited to `base-mainnet`, `base-sepolia`, `solana-mainnet`, and `solana-devnet`. The x402 protocol itself is chain-agnostic — write a custom action provider or call the facilitator directly if you need x402 on Sei. | -| `cdpApiActionProvider` | No | Requires a Coinbase `networkId`; Sei isn't in AgentKit's chain map. | -| `morphoActionProvider` | No | Morpho contracts not deployed on Sei | -| `moonwellActionProvider` | No | Moonwell contracts not deployed on Sei | - - - -For Sei-native DeFi actions (swaps on Symphony/DragonSwap, staking via Silo, lending via Takara), use the [Cambrian Agent Kit](/evm/ai-tooling/cambrian-agent-kit) alongside AgentKit, or write custom action providers. - - -### Known Quirks on Sei - -Verified by running AgentKit `0.10.4` against Sei testnet (`chain 1328`). These quirks sit in AgentKit's network and action-provider layer and apply to **both** `ViemWalletProvider` and `PrivyWalletProvider`: - -- **Balances are labeled "ETH" in action output.** `walletActionProvider` hard-codes the native-currency symbol, so `get_wallet_details` returns strings like `Native Balance: 512993.50 ETH` and `native_transfer` responses say `Transferred 0.05 ETH to 0x...` even on Sei. Signing and arithmetic are unaffected — it's a display-only quirk. If the LLM will quote balances or transfer confirmations to users, add a post-processing step or a system-prompt instruction to rewrite `ETH` → `SEI` when `chain_id == 1329 || 1328`. -- **`networkId` is `undefined`.** Coinbase's internal `CHAIN_ID_TO_NETWORK_ID` map only includes Ethereum, Polygon, Base, Arbitrum, and Optimism (mainnet + testnet). Sei's chain IDs aren't in it, so `walletProvider.getNetwork()` returns `{ protocolFamily: 'evm', chainId: '1328', networkId: undefined }`. This is harmless for signing/sending, but **any action provider that branches on `networkId`** will refuse to run on Sei. In practice, `AgentKit.from({...})` prints a warning like `The following action providers are not supported on the current network and will be unavailable: weth, x402` and silently drops them — if you expect an action and it's missing from `agentKit.getActions()`, check this warning first. - -### CDP-Managed Wallets and Sei - -AgentKit's `CdpEvmWalletProvider` (CDP-managed server wallets with built-in policies) is currently scoped to `base`, `base-sepolia`, `ethereum`, `ethereum-sepolia`, `polygon`, `arbitrum`, and `optimism` — **Sei is not a supported network**. - -For managed cloud custody with a policy engine on Sei, use one of: - -- **Privy server wallets** (below) — TEE-isolated keys with a policy engine that works on any EVM chain, including Sei. -- **AgentKit + Privy combined** — use `PrivyWalletProvider` inside AgentKit to keep the 40+ action providers while delegating custody and policy enforcement to Privy. See [Using AgentKit with Privy (Combined)](#using-agentkit-with-privy-combined) below. - -If you only need self-custodial keys (no TEE, you hold the private key), use `ViemWalletProvider` as shown above and enforce limits in your own application logic. - ---- - -## Privy Server Wallets on Sei - -[Privy](https://docs.privy.io/) provides wallet-as-a-service infrastructure for AI agents. Server wallets are programmatically managed wallets designed for backend use — no user interaction required. Keys are isolated in TEEs with Shamir secret sharing and never leave secure enclaves. - -### Prerequisites - -- A [Privy account](https://dashboard.privy.io/) with an App ID and App Secret -- An authorization keypair (generated in the Privy dashboard) - -### Setup - - - - - - - -```bash -curl --request POST https://api.privy.io/v1/wallets \ - -u ":" \ - -H "privy-app-id: " \ - -H 'Content-Type: application/json' \ - -d '{ - "chain_type": "ethereum", - "policy_ids": ["your_policy_id"] - }' -``` - -Response: -```json -{ - "id": "wallet_abc123", - "address": "0x1234...abcd", - "chain_type": "ethereum", - "policy_ids": ["your_policy_id"] -} -``` - - - -Use `eip155:1329` (CAIP-2 format) to target Sei mainnet: - -```bash -curl --request POST https://api.privy.io/v1/wallets/wallet_abc123/rpc \ - -u ":" \ - -H "privy-app-id: " \ - -H "privy-authorization-signature: " \ - -H 'Content-Type: application/json' \ - -d '{ - "method": "eth_sendTransaction", - "caip2": "eip155:1329", - "params": { - "transaction": { - "to": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e", - "value": "0x2386F26FC10000", - "chain_id": 1329 - } - } - }' -``` - - - -```bash -curl --request POST https://api.privy.io/v1/wallets/wallet_abc123/rpc \ - -u ":" \ - -H "privy-app-id: " \ - -H "privy-authorization-signature: " \ - -H 'Content-Type: application/json' \ - -d '{ - "method": "personal_sign", - "caip2": "eip155:1329", - "params": { - "message": "Hello from Sei" - } - }' -``` - - - - - - - - - - -```bash -npm install @privy-io/server-auth -``` - - - -```typescript -import { PrivyClient } from '@privy-io/server-auth'; -import { parseEther } from 'viem'; - -const privy = new PrivyClient('', '', { - walletApi: { authorizationPrivateKey: process.env.PRIVY_AUTH_KEY }, -}); - -// Create a server wallet -const wallet = await privy.walletApi.createWallet({ chainType: 'ethereum' }); -console.log('Wallet address:', wallet.address); - -// Send a transaction on Sei -// NOTE: `value` must be a hex string — Privy's request signer can't -// serialize a BigInt, so don't pass `parseEther(...)` directly. -const { hash } = await privy.walletApi.ethereum.sendTransaction({ - walletId: wallet.id, - caip2: 'eip155:1329', // Sei mainnet - transaction: { - to: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e', - value: '0x' + parseEther('0.01').toString(16), - chainId: 1329, - }, -}); -console.log('Transaction hash:', hash); -``` - - - - - - - - - - -```bash -pip install privy-client -``` - - - -```python -from privy import PrivyAPI - -client = PrivyAPI(app_id="", app_secret="") - -# Create a server wallet -wallet = client.wallets.create(chain_type="ethereum") -print(f"Wallet address: {wallet.address}") - -# Send a transaction on Sei -result = client.wallets.rpc( - wallet_id=wallet.id, - method="eth_sendTransaction", - caip2="eip155:1329", # Sei mainnet - params={ - "transaction": { - "to": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e", - "value": "0x2386F26FC10000", - "chain_id": 1329, - } - }, -) -print(f"Transaction hash: {result.hash}") -``` - - - - - - - -### Known Quirks on Sei (Privy) - -Verified by running `@privy-io/server-auth` `1.32.5` against Sei testnet (`eip155:1328`): - -- **`value` must be a hex string, not a `BigInt`.** Privy's request signer uses RFC 8785 JSON canonicalization (`canonicalize`), which throws `TypeError: Do not know how to serialize a BigInt` if you pass a `BigInt` in any field of the `transaction` object. Convert viem's `parseEther(...)` output with `'0x' + parseEther('0.01').toString(16)` before sending. -- **`authorizationKeyIds` on `createWallet` expects the public-key registration ID, not the dashboard key ID.** Passing the ID shown next to a key in the Privy dashboard can fail with `400 Invalid authorization key IDs`. If you only need an app-owned wallet (app credentials + `authorizationPrivateKey` for request signing), omit `authorizationKeyIds` — the wallet is still fully operable. - -### Privy with LangChain - -Privy publishes a LangChain integration (`langchain-privy`) that exposes wallet operations as a single LangChain tool. The tool reads `PRIVY_APP_ID` and `PRIVY_APP_SECRET` from the environment and is bound directly to the LLM: - -```python -import os -from langchain_privy import PrivyWalletTool -from langchain_openai import ChatOpenAI - -os.environ["PRIVY_APP_ID"] = "" -os.environ["PRIVY_APP_SECRET"] = "" - -tool = PrivyWalletTool() -print(f"Wallet: {tool.wallet_address}") - -llm = ChatOpenAI(model="gpt-4o-mini", temperature=0) -llm_with_tools = llm.bind_tools([tool]) - -response = llm_with_tools.invoke("What is my wallet address?") -``` - - -As of `langchain-privy@0.1.0`, the library's `Chain` enum does not include Sei — the built-in tool only targets Ethereum, Base, Optimism, Arbitrum, Polygon, Zora, Avalanche, BSC, Celo, Linea, Solana, and Bitcoin. For Sei, either: - -- Call Privy's REST API / server-auth SDK directly with `caip2: eip155:1329` (shown above), or -- Use AgentKit's `PrivyWalletProvider` with a LangChain adapter (`@coinbase/agentkit-langchain`) — see the [Combined](#using-agentkit-with-privy-combined) section below. - - -### Privy Policy Engine - -Privy's policy engine evaluates policies server-side before signing. Each rule pairs an `ALLOW`/`DENY` action with an RPC `method` and a list of `conditions` on transaction fields. Attach one or more policies to a wallet via `updateWallet`. - - -**Privy's engine is default-deny.** A request is allowed only when at least one `ALLOW` rule matches and no `DENY` rule matches. A policy built from `DENY`-only rules blocks every transaction — including ones you expect to pass. Always start from an explicit `ALLOW` rule that describes the happy path, then layer `DENY` rules on top. - - -```typescript -// "Cap sends at 10 SEI and block a specific address." -// Rule 1 (ALLOW) defines the happy path; without it, every request is denied. -// Rule 2 (DENY) carves a specific hole in that allow. -const policy = await privy.walletApi.createPolicy({ - name: 'sei-agent-policy', - version: '1.0', - chainType: 'ethereum', - rules: [ - { - name: 'Allow sends up to 10 SEI', - action: 'ALLOW', - method: 'eth_sendTransaction', - conditions: [ - { - fieldSource: 'ethereum_transaction', - field: 'value', - operator: 'lte', - value: '10000000000000000000', // 10 SEI in wei - }, - ], - }, - { - name: 'Deny sends to blocklisted address', - action: 'DENY', - method: 'eth_sendTransaction', - conditions: [ - { - fieldSource: 'ethereum_transaction', - field: 'to', - operator: 'in', - value: ['0xdEAD000000000000000042069420694206942069'], - }, - ], - }, - ], -}); - -// Attach policy to wallet -await privy.walletApi.updateWallet({ - id: wallet.id, - policyIds: [policy.id], -}); -``` - - -Conditions support the `eq`, `gt`, `gte`, `lt`, `lte`, and `in` operators against `ethereum_transaction` fields (`to`, `value`) or `ethereum_calldata` fields. Operand order is `tx_field rule_value` — e.g. `operator: 'lte'` with `value: '10000000000000000000'` means "transaction value ≤ 10 SEI". `method` must be `eth_sendTransaction` or `eth_signTransaction`. Chain restriction is not a policy condition — enforce `caip2: 'eip155:1329'` at the call site to keep an agent on Sei. - - -Privy also offers features beyond the policy engine: - -- **Key quorums** — require multiple authorization keys to approve high-value transactions -- **Webhook notifications** — get notified of all wallet activity (works chain-agnostically) - ---- - -## Using AgentKit with Privy (Combined) - -AgentKit includes a built-in `PrivyWalletProvider`, so you can use Privy's wallet infrastructure and policy engine as the backend while using AgentKit's 40+ action providers for onchain operations. - -Because of the `authorizationKeyIds` quirk noted above, the simplest working pattern is to create the wallet once via the Privy SDK (or the dashboard) and then hand the resulting `walletId` to AgentKit: - -```typescript -import { AgentKit, PrivyWalletProvider, walletActionProvider, erc20ActionProvider } from '@coinbase/agentkit'; -import { PrivyClient } from '@privy-io/server-auth'; - -// Step 1 — create (or look up) a server wallet via the Privy SDK. -// Omit authorizationKeyIds here; attach policies with updateWallet if needed. -const privy = new PrivyClient(process.env.PRIVY_APP_ID!, process.env.PRIVY_APP_SECRET!, { - walletApi: { authorizationPrivateKey: process.env.PRIVY_AUTH_KEY }, -}); -const wallet = await privy.walletApi.createWallet({ chainType: 'ethereum' }); - -// Step 2 — wrap the existing wallet in AgentKit's PrivyWalletProvider. -const walletProvider = await PrivyWalletProvider.configureWithWallet({ - appId: process.env.PRIVY_APP_ID!, - appSecret: process.env.PRIVY_APP_SECRET!, - chainId: '1329', // Sei mainnet - walletId: wallet.id, - authorizationPrivateKey: process.env.PRIVY_AUTH_KEY, -}); - -const agentKit = await AgentKit.from({ - walletProvider, - actionProviders: [ - walletActionProvider(), - erc20ActionProvider(), - ], -}); -``` - -This gives you the best of both worlds: Privy's fine-grained policies and key quorums with AgentKit's rich action library. - - -If you call `PrivyWalletProvider.configureWithWallet` **without** a `walletId`, AgentKit will attempt to create a new wallet for you and pass `authorizationKeyId` through to Privy — which hits the same `400 Invalid authorization key IDs` failure described in Privy's Known Quirks. Always pre-create the wallet and pass `walletId`. - - ---- - -## Feature Matrix - -### Wallet Creation & Key Management - -| Capability | Coinbase AgentKit | Privy | -| --- | --- | --- | -| Programmatic wallet creation on Sei | Yes — self-custodial via `ViemWalletProvider` (you hold the key). CDP-managed server wallets do not currently support Sei. | Yes — Server wallets on any EVM | -| TEE-secured key isolation on Sei | No — CDP's TEE signer is scoped to Base/Ethereum/Polygon/Arbitrum/Optimism. Use Privy (standalone or via `PrivyWalletProvider` in AgentKit). | Yes — TEE + key sharding | -| Managed cloud custody on Sei | No via CDP. Yes via `PrivyWalletProvider`. | Yes — Server wallets with `eip155:1329` | -| Multi-party key quorum | No | Yes — Authorization key quorums via dashboard | -| Key export / portability | Yes | Yes | - - -### Policy Engine & Guardrails - -| Capability | Coinbase AgentKit | Privy | -| --- | --- | --- | -| Spending limits (per-tx) on Sei | Only via app-level checks with `ViemWalletProvider`. CDP's `ethValue` policy doesn't apply on Sei. | Yes — Policy engine, any chain | -| Contract / address allowlisting on Sei | Only via app-level checks with `ViemWalletProvider`. CDP's `evmAddress` policy doesn't apply on Sei. | Yes — Contract allowlist rules | -| Network restriction policies on Sei | N/A — CDP networkIds don't include Sei | Yes — Chain restrictions | -| Time-based access controls | No | Yes | -| Transaction simulation | No | No — Needs Sei-specific RPC | - - -### Gas & Transaction Management - -| Capability | Coinbase AgentKit | Privy | -| --- | --- | --- | -| Gasless / sponsored transactions on Sei | No — Gasless is Base-only | No — Requires Sei-native paymaster | -| Smart wallet (ERC-4337) on Sei | No — Smart Accounts don't include Sei | No — Possible via ZeroDev or Biconomy integration | -| Batch transactions on Sei | No — Requires Smart Accounts | Yes | -| Basic send / transfer on Sei | Yes | Yes | -| ERC-20 token operations on Sei | Yes — `erc20ActionProvider` | Yes — Standard EVM ops | - - -### Agentic DeFi Actions - -| Capability | Coinbase AgentKit | Privy | -| --- | --- | --- | -| Token swaps on Sei DEXs | No — Built-in swap providers (Jupiter, 0x, Sushi, Enso) don't route Sei DEXs | No | -| Yield / lending on Sei | No — Built-in lending providers (Morpho, Moonwell, Compound, Yelay) aren't deployed on Sei | No | -| Liquidity provision on Sei | No | No | -| Cross-chain bridge to/from Sei | No — Sei not a listed Across route | No | -| Pyth oracle price feeds | Yes — `pythActionProvider` works on Sei | No | - - - -For Sei-native DeFi actions, use the [Cambrian Agent Kit](/evm/ai-tooling/cambrian-agent-kit) which includes built-in integrations for Symphony, DragonSwap, Silo, Takara, and Citrex. - - -### x402 & Machine-to-Machine Payments - -| Capability | Coinbase AgentKit | Privy | -| --- | --- | --- | -| x402 protocol support on Sei | No via built-in `x402ActionProvider` (allowlist is Base + Solana only) — possible via a custom action provider | Yes — Works wherever agent holds stablecoins | -| Agent-to-agent USDC transfers | Yes — ERC-20 transfers with Sei USDC | Yes — Server wallet transfers | -| Stablecoin operations on Sei | Yes — `erc20ActionProvider` + Sei USDC | Yes — Standard ERC-20 ops | - - -### Developer Experience - -| Capability | Coinbase AgentKit | Privy | -| --- | --- | --- | -| MCP server integration | Yes — AgentKit MCP framework extension | No | -| LangChain / Vercel AI SDK | Yes — Framework extensions for both | Yes — `langchain-privy` | -| OpenAI Agents SDK | Yes — Native extension | No | -| Webhook / event monitoring on Sei | No — Webhooks for supported networks only | Yes — Chain-agnostic webhooks | -| Multi-language SDKs | TypeScript, Python | TypeScript, Python, Java, Rust, Go + REST | - - ---- - -## Other Agentic Wallet Solutions - -While Coinbase AgentKit and Privy are the most mature options for Sei, several other platforms support agentic wallet use cases: - -| Platform | Approach | Sei Support | Best For | -| --- | --- | --- | --- | -| [Turnkey](https://docs.turnkey.com/products/embedded-wallets/features/agentic-wallets) | TEE-based key isolation, sub-100ms signing, granular policies | Yes (any EVM) | Enterprise agents needing fine-grained policies | -| [Lit Protocol](https://developer.litprotocol.com/) | Decentralized key management (DKG), programmable key pairs as NFTs | Yes (any EVM) | Decentralized, user-owned agent delegation | -| [Dynamic](https://www.dynamic.xyz/ecosystems/sei) | MPC or smart contract wallets, strong onboarding UX | Yes (explicit Sei support) | Apps serving both humans and agents | -| [thirdweb](https://thirdweb.com/) | Backend wallets + account abstraction, session keys | Yes (any EVM) | Broadest AI framework support (6+ frameworks) | -| [Openfort](https://www.openfort.io/solutions/ai-agents) | TEE server wallets, sub-125ms signing, 25+ EVM chains | Yes (any EVM) | Gaming and high-throughput agent workloads | - - ---- - -## Sei Network Configuration Reference - -Use these values when configuring any agentic wallet provider for Sei: - -| Parameter | Mainnet | Testnet | -| --- | --- | --- | -| **Chain ID** | `1329` | `1328` | -| **Chain ID (hex)** | `0x531` | `0x530` | -| **CAIP-2** | `eip155:1329` | `eip155:1328` | -| **RPC URL** | `https://evm-rpc.sei-apis.com` | `https://evm-rpc-testnet.sei-apis.com` | -| **Currency** | SEI (18 decimals) | SEI (18 decimals) | -| **Block Explorer** | [seiscan.io](https://seiscan.io) | [seiscan.io](https://testnet.seiscan.io) | -| **Finality** | ~400ms | ~400ms | - - - -**Security Reminders:** - -- Never expose private keys or authorization secrets to the LLM/agent process. -- Always use dedicated wallets for agent operations — never your main wallet. -- Start with testnet (`eip155:1328`) before deploying to mainnet. -- Set spending limits and contract allowlists via the policy engine before going live. -- Monitor agent wallet activity via block explorers or webhook notifications. - diff --git a/evm/ai-tooling/cambrian-agent-kit.mdx b/evm/ai-tooling/cambrian-agent-kit.mdx deleted file mode 100644 index 04e281d..0000000 --- a/evm/ai-tooling/cambrian-agent-kit.mdx +++ /dev/null @@ -1,536 +0,0 @@ ---- -title: 'Cambrian Agent Kit Ecosystem Tutorial' -sidebarTitle: 'Cambrian Agent Kit' -description: 'Learn to build powerful, autonomous AI agents and agentic chatbots on the SEI blockchain with DeFi protocol integrations including Takara, Silo, Citrex, and Symphony.' -keywords: ['cambrian agent kit', 'sei blockchain', 'ai agents', 'defi protocols', 'takara', 'silo', 'citrex', 'symphony', 'autonomous agents'] ---- -## Overview - -Cambrian Agent Kit is a developer SDK for building powerful, autonomous AI agents and agentic chatbots on the SEI blockchain. It lets you interact with DeFi protocols (Takara, Silo, Citrex, Symphony), manage SEI tokens and NFTs, and seamlessly integrate AI workflows. In this tutorial, you'll learn how to set up the kit, run your first agent, and use it for real DeFi use cases—customized for your needs. To understand more and deep dive into how it works under the hood, please refer to the [Cambrian Agent Kit Documentation](https://deepwiki.com/CambrianAgents/sei-agent-kit/1-overview). - -## Supported Features - -The SEI Agent Kit supports a comprehensive set of features for blockchain agent development: - -- Token Operations: Complete SEI ERC-20 and ERC-721 token management -- DeFi Protocol Integration: Seamless interaction with SEI's DeFi ecosystem -- Swap Functionality: Token swapping through Symphony aggregator -- Liquidity Management: Add and remove liquidity with DragonSwap -- Lending & Borrowing: Interact with Takara protocol for lending operations -- Staking Operations: Stake and unstake SEI tokens with Silo -- LangChain Integration: Build AI agents with LangChain and LangGraph - -## What this guide teaches you: - -This tutorial guides you through: - -- **Setup**: Install and configure the Agent Kit, connect your wallet and API keys. -- **Core Concepts**: Understand agents, supported protocols, and how these components fit together. -- **End-to-End Examples**: You'll run practical code to: - - Check your token/NFT balances. - - Swap tokens using Symphony. - - Stake/unstake SEI in Silo. - - Lend/borrow with Takara. - - Trade perps with Citrex. -- **Customization**: Learn to adapt the kit for your own protocol or workflow. - - -**Some Use Cases:** - -- **Autonomous DeFi Agents**: Agents that can automatically manage token positions, provide liquidity, or engage in lending activities -- **AI-Assisted Wallets**: Conversational interfaces for blockchain operations -- **Financial Assistant Agents**: AI agents that can analyze market conditions and execute trades -- **Portfolio Management Agents**: Automated management of crypto asset portfolios - - - -## Hands-on Tutorial - -### 1. Prerequisites - -- Node.js & npm installed -- SEI wallet private key -- OpenAI API key (for AI integrations) -- **Minimum SEI balance**: Ensure you have sufficient SEI for gas - -### 2. Project Setup - -```bash -git clone https://github.com/CambrianAgents/sei-agent-kit.git -cd sei-agent-kit -cp .env.example .env # Fill in your keys! -npm install -``` - -Edit `.env`: - -```env -OPENAI_API_KEY=your_openai_api_key -SEI_PRIVATE_KEY=your_wallet_private_key -RPC_URL=https://evm-rpc.sei-apis.com -``` - - -**Important Security Notes:** - -- **Never share your private key**: Your private key controls your funds - - - -### 3. Running Your First Agent - -```bash -npm run test -``` - -The following is the output and interaction with the Cambrian Agent: - -```bash -npm run test - -> sei-agent-kit@0.0.3 test -> tsx test/index.ts - - - ███████╗███████╗██╗ █████╗ ██████╗ ███████╗███╗ ██╗████████╗ ██╗ ██╗██╗████████╗ - ██╔════╝██╔════╝██║ ██╔══██╗██╔════╝ ██╔════╝████╗ ██║╚══██╔══╝ ██║ ██╔╝██║╚══██╔══╝ - ███████╗█████╗ ██║ ███████║██║ ███╗█████╗ ██╔██╗ ██║ ██║ █████╔╝ ██║ ██║ - ╚════██║██╔══╝ ██║ ██╔══██║██║ ██║██╔══╝ ██║╚██╗██║ ██║ ██╔═██╗ ██║ ██║ - ███████║███████╗██║ ██║ ██║╚██████╔╝███████╗██║ ╚████║ ██║ ██║ ██╗██║ ██║ - ╚══════╝╚══════╝╚═╝ ╚═╝ ╚═╝ ╚═════╝ ╚══════╝╚═╝ ╚═══╝ ╚═╝ ╚═╝ ╚═╝╚═╝ ╚═╝ - - -Starting chat with the Cambrian Agent... Type 'bye' to end. - -You: Hey, I would like to swap some sei to usdc. - -Cambrian Agent: Sure thing! How much SEI would you like to swap for USDC? Let me know, and I'll get the magic started! ✨ - ------------------------------------ - - -You: I would like to swap 0.2 sei for some usdc - -Cambrian Agent: - ------------------------------------ - -Getting token address for USDC... -Swapping 0.2 0x0 to 0x3894085ef7ff0f0aedf52e2a2704928d1ec074f1... -Querying balance of SEI for 0xa0E377AEaF32024f949667f56e7fa4409AFE6b8D... - -Cambrian Agent: {"status":"success","result":"0x638d08db41e9ed370504861b4d2ced693869c45136bfdba2d92e8aed43c080fa","fromToken":"SEI","toToken":"USDC","amount":"0.2"} - ------------------------------------ - - -Cambrian Agent: Your swap of 0.2 SEI to USDC was successful! 🎉 The transaction hash is `0x638d08db41e9ed370504861b4d2ced693869c45136bfdba2d92e8aed43c080fa`. If you have any more magical swaps or questions, just let me know! 🪄 - ------------------------------------ - - -You: Give me my new balances after the previous transaction - -Cambrian Agent: - ------------------------------------ - -Getting token address for SEI... -Getting token address for USDC... -Querying balance of 0x3894085ef7ff0f0aedf52e2a2704928d1ec074f1 for 0xa0E377AEaF32024f949667f56e7fa4409AFE6b8D... -Querying balance of 0x67da7010c6c231ad620e3940e707adb6c1a08f23 for 0xa0E377AEaF32024f949667f56e7fa4409AFE6b8D... - -Cambrian Agent: {"status":"success","balance":"0","token":{"ticker":"SEI"}} - ------------------------------------ - - -Cambrian Agent: After the swap, your new balances are: - -- SEI: 0 SEI (Looks like you've spent it all!) -- USDC: 0.147866 USDC - -If you need anything else, just give me a shout! 📢 - ------------------------------------ - - -You: bye -``` - - -**Understanding the Transaction:** - -- **SEI Address**: `0x0` represents native SEI token in the agent kit -- **Transaction Hash**: Can be verified on [Seiscan](https://seiscan.io/) -- **Gas Fees**: Automatically calculated and deducted from your balance - - - -### 4. Explore Core Features & Protocols - -#### a) Check Token Balance with Error Handling - -```typescript -import { SeiAgentKit } from './src/agent'; - -async function checkBalanceWithErrorHandling() { - try { - const agent = new SeiAgentKit(process.env.SEI_PRIVATE_KEY, 'openai'); - - // Check SEI balance - const balance = await agent.getERC20Balance(); // SEI or specify contract address - console.log('Your SEI Balance:', balance); - - // Validate balance before proceeding - if (parseFloat(balance) < 0.01) { - console.warn('⚠️ Low SEI balance. You may need more SEI for gas fees.'); - } - } catch (error) { - console.error('Error checking balance:', error.message); - - // Handle specific error types - if (error.message.includes('insufficient funds')) { - console.log('💡 Tip: Add more SEI to your wallet'); - } else if (error.message.includes('network')) { - console.log('💡 Tip: Check your RPC connection'); - } - } -} -``` - -#### b) Safe Token Swapping with Symphony - -```typescript -async function safeSwap() { - try { - const agent = new SeiAgentKit(process.env.SEI_PRIVATE_KEY, 'openai'); - - // Validate inputs - const amount = '1.0'; - const fromToken = '0x0'; // SEI - const toToken = 'usdc_contract_address'; - - // Check balance first - const balance = await agent.getERC20Balance(); - if (parseFloat(balance) < parseFloat(amount)) { - throw new Error('Insufficient balance for swap'); - } - - // Execute swap with error handling - const tx = await agent.swap(amount, fromToken, toToken); - console.log('Swap TX:', tx); - - // Verify transaction - if (tx.status === 'success') { - console.log('✅ Swap successful!'); - console.log('🔗 Transaction hash:', tx.result); - } else { - console.error('❌ Swap failed:', tx.error); - } - } catch (error) { - console.error('Swap error:', error.message); - - // Handle common swap errors - if (error.message.includes('slippage')) { - console.log('💡 Tip: Try increasing slippage tolerance'); - } else if (error.message.includes('liquidity')) { - console.log('💡 Tip: Insufficient liquidity for this pair'); - } - } -} -``` - - -**Swap Safety Tips:** - -- **SEI Native Token**: Use "0x0" as the address for native SEI token while using the agent kit -- **Slippage Protection**: Always set appropriate slippage tolerance -- **Price Impact**: Monitor price impact before large swaps - - - -#### c) Liquid Staking with Silo Protocol - -```typescript -async function stakingWithSilo() { - try { - const agent = new SeiAgentKit(process.env.SEI_PRIVATE_KEY, 'openai'); - - // Stake SEI and receive iSEI - const stakeAmount = '2.0'; - const stakeTx = await agent.stake(stakeAmount); - console.log('Staked TX:', stakeTx); - - if (stakeTx.status === 'success') { - console.log('✅ Successfully staked SEI!'); - console.log('📄 You received iSEI tokens representing your stake'); - console.log('💰 Your rewards will auto-compound over time'); - } - - // Later, unstake if needed - const unstakeAmount = '1.0'; - const unstakeTx = await agent.unstake(unstakeAmount); - console.log('Unstaked TX:', unstakeTx); - } catch (error) { - console.error('Staking error:', error.message); - - if (error.message.includes('minimum amount')) { - console.log('💡 Tip: Check minimum staking amount requirements'); - } - } -} -``` - - -**Silo Staking Details:** - -- **iSEI Token**: [Represents your staked SEI plus auto-compounded rewards](https://silostaking.gitbook.io/silo-staking/general-faq) -- **No Unbonding Period**: [Immediate liquidity unlike traditional staking](https://medium.com/@nordicmoney22/unleashing-the-power-of-liquid-staking-on-sei-4a1d045232e1) -- **5% Fee**: [Annual management fee of 5% on rewards](https://silostaking.gitbook.io/silo-staking/general-faq) -- **MEV Benefits**: [Validators share MEV profits with stakers](https://www.silostaking.io/) - - - -#### d) Lending/Borrowing with Takara Protocol - -```typescript -async function takaraLending() { - try { - const agent = new SeiAgentKit(process.env.SEI_PRIVATE_KEY, 'openai'); - - // Mint tTokens (supply liquidity) - const mintTx = await agent.mintTakara('USDC', '10'); - console.log('Mint Takara:', mintTx); - - if (mintTx.status === 'success') { - console.log('✅ Successfully supplied USDC to Takara'); - console.log('💰 You are now earning interest on your supply'); - } - - // Borrow against collateral - const borrowTx = await agent.borrowTakara('USDC', '5'); - console.log('Borrow Takara:', borrowTx); - - if (borrowTx.status === 'success') { - console.log('✅ Successfully borrowed USDC from Takara'); - console.log('⚠️ Remember to monitor your collateral ratio'); - } - - // Repay borrowed amount - const repayTx = await agent.repayTakara('USDC', '5'); - console.log('Repay Takara:', repayTx); - } catch (error) { - console.error('Takara error:', error.message); - - if (error.message.includes('collateral')) { - console.log('💡 Tip: Add more collateral to maintain healthy ratio'); - } else if (error.message.includes('liquidity')) { - console.log('💡 Tip: Insufficient liquidity in the pool'); - } - } -} -``` - -#### e) Perpetual Trading with Citrex Markets - -```typescript -async function citrexTrading() { - try { - const agent = new SeiAgentKit(process.env.SEI_PRIVATE_KEY, 'openai'); - - // Deposit margin - const depositAmount = '10'; - const depositTx = await agent.citrexDeposit(depositAmount); - console.log('Citrex Deposit:', depositTx); - - if (depositTx.status === 'success') { - console.log('✅ Successfully deposited margin to Citrex'); - console.log('⚡ You can now trade perpetuals with up to 20x leverage'); - } - - // Check available products - const products = await agent.citrexGetProducts(); - console.log('Available Products:', products); - - // Withdraw margin when done - const withdrawTx = await agent.citrexWithdraw('5'); - console.log('Citrex Withdraw:', withdrawTx); - } catch (error) { - console.error('Citrex error:', error.message); - - if (error.message.includes('margin')) { - console.log('💡 Tip: Ensure sufficient margin for your positions'); - } else if (error.message.includes('leverage')) { - console.log('💡 Tip: Reduce leverage to lower risk'); - } - } -} -``` - -See `/tools/` for more advanced protocol integrations! - -## Error Handling & Troubleshooting - -### Common Error Types - - -**Comprehensive Error Handling Examples:** - -```typescript -// Robust error handling for all operations -async function robustAgentOperation() { - const agent = new SeiAgentKit(process.env.SEI_PRIVATE_KEY, 'openai'); - - try { - // Operation code here - } catch (error) { - // Network errors - if (error.code === 'NETWORK_ERROR') { - console.log('🌐 Network issue - retrying in 5 seconds...'); - await new Promise((resolve) => setTimeout(resolve, 5000)); - // Implement retry logic - } - - // Insufficient funds - if (error.message.includes('insufficient funds')) { - console.log('💰 Insufficient funds for this operation'); - const balance = await agent.getERC20Balance(); - console.log('Current balance:', balance); - } - - // Gas estimation errors - if (error.message.includes('gas')) { - console.log('⛽ Gas estimation failed - transaction may fail'); - console.log('Try reducing transaction amount or increasing gas limit'); - } - - // Contract-specific errors - if (error.message.includes('revert')) { - console.log('📋 Smart contract reverted the transaction'); - console.log('Check transaction parameters and try again'); - } - } -} -``` - - - -### Transaction Monitoring - -```typescript -async function monitorTransaction(txHash: string) { - const maxRetries = 30; // 30 seconds max wait - let retries = 0; - - while (retries < maxRetries) { - try { - // Check transaction status - const receipt = await checkTransactionStatus(txHash); - - if (receipt.status === 'success') { - console.log('✅ Transaction confirmed!'); - return receipt; - } else if (receipt.status === 'failed') { - console.log('❌ Transaction failed'); - return receipt; - } - - // Wait and retry - await new Promise((resolve) => setTimeout(resolve, 1000)); - retries++; - } catch (error) { - console.log(`⏳ Waiting for confirmation... (${retries}/${maxRetries})`); - retries++; - await new Promise((resolve) => setTimeout(resolve, 1000)); - } - } - - console.log('⏰ Transaction timeout - check manually on Seiscan'); -} -``` - -### Troubleshooting Guide - -| Issue | Cause | Solution | -| --- | --- | --- | -| "Insufficient funds" | Low SEI balance | Add more SEI to your wallet | -| "Transaction failed" | Gas estimation error | Reduce transaction amount | -| "Network error" | RPC connection issue | Check RPC URL in .env | -| "Slippage too high" | Price moved during swap | Increase slippage tolerance | -| "Invalid private key" | Incorrect key format | Verify private key format | - - -**Debug Commands:** - -```bash -# Check network connection -curl -X POST https://evm-rpc.sei-apis.com \ - -H "Content-Type: application/json" \ - -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' - -# Verify wallet balance -# Use Seiscan: https://seiscan.io/ -``` - -### 5. Advanced Features & Customization - -#### Multi-Protocol Strategy Example - -```typescript -async function deFiStrategy() { - const agent = new SeiAgentKit(process.env.SEI_PRIVATE_KEY, 'openai'); - - try { - // 1. Swap SEI for USDC via Symphony - console.log('Step 1: Swapping SEI for USDC...'); - const swapTx = await agent.swap('10', '0x0', 'usdc_address'); - - // 2. Supply USDC to Takara for lending - console.log('Step 2: Supplying USDC to Takara...'); - const supplyTx = await agent.mintTakara('USDC', '5'); - - // 3. Stake remaining SEI via Silo - console.log('Step 3: Staking SEI via Silo...'); - const stakeTx = await agent.stake('5'); - - // 4. Monitor positions - console.log('Step 4: Monitoring positions...'); - const balance = await agent.getERC20Balance(); - - console.log('✅ Multi-protocol strategy executed successfully!'); - console.log('📊 Final balance:', balance); - } catch (error) { - console.error('Strategy failed:', error.message); - // Implement rollback logic if needed - } -} -``` - -#### Monitoring & Alerts: - -```typescript -// Set up monitoring for your agent -async function setupMonitoring() { - const agent = new SeiAgentKit(process.env.SEI_PRIVATE_KEY, 'openai'); - - // Monitor balance changes - setInterval(async () => { - const balance = await agent.getERC20Balance(); - if (parseFloat(balance) < 1.0) { - console.warn('⚠️ Low balance alert:', balance); - // Send alert to your monitoring system - } - }, 60000); // Check every minute - - // Monitor failed transactions - agent.on('transactionFailed', (error) => { - console.error('Transaction failed:', error); - // Log to monitoring system - }); -} -``` - -#### Custom Protocol Integration - -To extend the Cambrian Agent Kit for your own protocol, please follow this repository which explains how to add plugins to the agent kit so that it can support your protocol: [Cambrian Agents Plugin Guide](https://github.com/CambrianAgents/cambrian-plugin) diff --git a/evm/ai-tooling/mcp-server.mdx b/evm/ai-tooling/mcp-server.mdx deleted file mode 100644 index 546eea6..0000000 --- a/evm/ai-tooling/mcp-server.mdx +++ /dev/null @@ -1,364 +0,0 @@ ---- -title: 'MCP Server' -description: 'Enable AI assistants to interact with Sei networks through natural language using the Model Context Protocol' -keywords: ['mcp', 'ai', 'model context protocol', 'claude', 'cursor', 'windsurf', 'blockchain ai'] ---- -The Sei Model Context Protocol (MCP) Server enables AI assistants to interact with Sei networks through natural language. Built on the [Model Context Protocol](https://modelcontextprotocol.io/) standard, it provides seamless blockchain integration for AI coding assistants. - -The Sei MCP Server is open source. Contribute at [github.com/sei-protocol/sei-js](https://github.com/sei-protocol/sei-js/tree/main/packages/mcp-server) - -## What is MCP? - -The Model Context Protocol is an open standard that connects AI systems with external tools and data sources. It enables: - -- Real-time data access from external services -- Function execution and operations -- Context preservation across interactions -- Specialized capabilities beyond base training - -The Sei MCP Server leverages this protocol to bring blockchain functionality directly to your AI assistant. - -## Capabilities - -| Category | Features | -| --- | --- | -| Account Management | Wallet addresses • Balance queries • Contract verification | -| Token Operations | SEI transfers • ERC20/721/1155 support • Token approvals | -| Blockchain Data | Block information • Transaction details • Network status | -| Smart Contracts | State queries • Function execution • Event logs | -| Networks | Mainnet • Testnet | - - -## Setup Guide - - - - -### Cursor Setup - - - - -Navigate to `Cursor → Settings → Cursor Settings → MCP` - - - -Click **"Add new Global MCP server"** and add this configuration to `mcp.json`: - -```json -{ - "mcpServers": { - "sei-mcp-server": { - "command": "npx", - "args": ["-y", "@sei-js/mcp-server"], - "env": { - "PRIVATE_KEY": "your_private_key_here" - } - } - } -} -``` - - - -Restart Cursor to activate the MCP server. You'll see a notification when it's ready. - - - - - - - -### Windsurf Setup - - - - -Navigate to `Windsurf → Settings → Windsurf Settings → Cascade` - - - -Add the Sei MCP Server to your configuration: - -```json -{ - "mcpServers": { - "sei": { - "command": "npx", - "args": ["-y", "@sei-js/mcp-server"], - "env": { - "PRIVATE_KEY": "your_private_key_here" - } - } - } -} -``` - - - -Save and restart Windsurf. The server loads automatically. - - - - - - - -### Claude Desktop Setup - - - - -Download [Claude Desktop](https://claude.ai/download) from Anthropic. - - - -Open **Settings** → **Developer** → **Edit Config** and add: - -```json -{ - "mcpServers": { - "sei": { - "command": "npx", - "args": ["-y", "@sei-js/mcp-server"], - "env": { - "PRIVATE_KEY": "your_private_key_here" - } - } - } -} -``` - - - -Save and restart Claude Desktop to enable Sei tools. - - - - - - - -### Claude CLI Setup - - - - -```bash -npm install -g @anthropic-ai/claude-code -``` - - - -```bash -claude mcp add sei-mcp-server npx @sei-js/mcp-server -``` - - - -```bash -claude -``` - -The Sei MCP Server activates automatically in your session. - - - - - - - -## Private Key Setup - -**Security Notice**: Generate a dedicated wallet for MCP operations. Never use your main wallet's private key. - -Export your private key from your wallet: - -- Look for "Export Private Key" or "Show Private Key" in wallet settings -- Ensure the key starts with `0x` -- Fund the wallet with small amounts for testing - -## Features - -The Sei MCP Server enables your AI assistant to: - -### Blockchain Operations - -- Query account balances and transaction history -- Execute token transfers -- Interact with smart contracts -- Monitor network status - -### Coming Soon - -- Documentation search and explanation -- @sei-js library integration -- Boilerplate generation -- DeFi protocol interactions - -## Available Tools - -### Core Operations - -| Tool | Purpose | Example | -| --- | --- | --- | -| `get_address_from_private_key` | Retrieve wallet address | "What's my wallet address?" | -| `get_balance` | Check SEI balance | "Check balance of 0x123..." | -| `transfer_sei` | Send SEI tokens | "Send 1 SEI to 0x456..." | -| `is_contract` | Verify contract address | "Is 0x789... a contract?" | - - -### Token Management - -| Tool | Purpose | Example | -| --- | --- | --- | -| `get_token_info` | Token metadata | "Get USDC token info" | -| `get_token_balance` | Token balance | "Check my USDC balance" | -| `transfer_token` | Token transfer | "Send 100 USDC to 0x123..." | -| `approve_token_spending` | Token approval | "Approve DEX for USDC" | - - -### NFT Operations - -| Tool | Purpose | Example | -| --- | --- | --- | -| `get_nft_info` | NFT metadata | "Show NFT #123 details" | -| `check_nft_ownership` | Ownership verification | "Who owns NFT #456?" | -| `transfer_nft` | NFT transfer | "Send NFT #789 to 0xABC..." | -| `get_nft_balance` | Collection balance | "How many NFTs do I own?" | - - -### Blockchain Data - -| Tool | Purpose | Example | -| --- | --- | --- | -| `get_chain_info` | Network information | "Show Sei mainnet info" | -| `get_block_by_number` | Block details by number | "Get block 12345" | -| `get_latest_block` | Latest block details | "Get latest block" | -| `get_transaction` | Transaction data | "Show tx 0xTXID..." | -| `read_contract` | Contract state | "Read DEX reserves" | - - -## AI Prompts - -Pre-configured prompts for common tasks: - -
-
-

my_wallet_address

-

Get your wallet address

-
-
-

explore_block

-

Analyze block data

-
-
-

analyze_transaction

-

Transaction details

-
-
-

analyze_address

-

Address analysis

-
-
- -## Usage Examples - -
-
-

Query Balance

-

"What's my SEI balance?"

-

→ Returns wallet balance and address

-
- -
-

Send Transaction

-

"Send 1 SEI to 0x742d35Cc6634C0532925a3b844Bc454e4438f44e"

-

→ Executes transfer and returns transaction hash

-
- -
-

Contract Analysis

-

"Is 0x3894085ef7ff0f0aedf52e2a2704928d1ec074f1 a contract?"

-

→ Identifies contract type and metadata

-
-
- -## Resource URIs - -Access blockchain data through standardized URIs: - -```bash -# Network data -evm://sei/chain -evm://sei-testnet/chain - -# Block information -evm://sei/block/latest -evm://sei/block/12345 - -# Transactions -evm://sei/tx/0xabc123... -evm://sei/tx/0xabc123.../receipt - -# Token data -evm://sei/token/0x3894085ef7ff0f0aedf52e2a2704928d1ec074f1 -evm://sei/token/0x389.../balanceOf/0x742d... - -# NFT data -evm://sei/nft/0xNFT_ADDRESS/123 -evm://sei/nft/0xNFT_ADDRESS/123/isOwnedBy/0x742d... -``` - -## Configuration - -### Environment Setup - -```bash -# .env file -PRIVATE_KEY=0x_your_private_key_here - -# Optional (coming soon) -CUSTOM_RPC_URL=https://your-rpc.com -CUSTOM_CHAIN_ID=1329 -``` - -### HTTP Server Mode - -For web applications: - -```bash -# Start HTTP server -npx @sei-js/mcp-server --http - -# Connect from web app -const eventSource = new EventSource('http://localhost:3001/sse'); -``` - -## Security Guidelines - - -**Security Guidelines:** - -1. **Use a dedicated wallet** - Create a new wallet specifically for MCP -2. **Minimal funding** - Only add funds needed for testing -3. **Environment variables** - Never hardcode private keys -4. **Monitor activity** - Regularly check transaction history - -**For production:** - -- Implement transaction limits -- Use multi-signature wallets -- Add contract whitelisting -- Enable rate limiting - - - -## Troubleshooting - -**Connection issues**: Verify Node.js 18+ is installed and restart your AI assistant. - -**Private key errors**: Ensure key format starts with `0x` and wallet has sufficient funds. - -**Cursor: The model returned an error. Try disabling the MCP servers, or switch models**: Disable "Auto" in the model -menu and select a specific model e.g. `claude-4-sonnet` diff --git a/evm/evm-parity/evm-compatibility.mdx b/evm/evm-parity/evm-compatibility.mdx index 1d6892e..2bdbacf 100644 --- a/evm/evm-parity/evm-compatibility.mdx +++ b/evm/evm-parity/evm-compatibility.mdx @@ -100,8 +100,8 @@ These capabilities are Sei-specific and have no standard Ethereum equivalent. Th | Feature | Notes | | --- | --- | -| Sei precompiles (staking, governance, distribution, oracle, P256, JSON, CosmWasm bridge) | EVM contracts at deterministic addresses. ABIs and contract addresses are exported from `@sei-js/precompiles` for use with any standard EVM library. | -| Pointer contracts (CW20 ↔ ERC-20, CW721 ↔ ERC-721) | Bridge between CosmWasm and EVM token standards. Standard ERC interfaces work against pointer contracts. | +| Sei precompiles (staking, governance, distribution, P256, JSON, Solo, pointers, and the CosmWasm bridge) | EVM contracts at deterministic addresses. ABIs and contract addresses are exported from `@sei-js/precompiles` for use with any standard EVM library. The retired Oracle and disabled IBC precompiles are not exported. | +| Pointer contracts (CW20 ↔ ERC-20, CW721 ↔ ERC-721, CW1155 ↔ ERC-1155) | Bridge between CosmWasm and EVM token standards. Standard ERC interfaces work against pointer contracts. Look up with `POINTERVIEW_PRECOMPILE_ADDRESS` (`0x…100A`). Register with `POINTER_PRECOMPILE_ADDRESS` (`0x…100B`). | | Native address association (EVM ↔ Cosmos address) | Links an EVM address and a Cosmos address for the same account. Required before some Sei-native flows. | ## Unsupported RPC Methods diff --git a/evm/evm-parity/examples/deploy-verify.mdx b/evm/evm-parity/examples/deploy-verify.mdx index 15ebd9f..da982d5 100644 --- a/evm/evm-parity/examples/deploy-verify.mdx +++ b/evm/evm-parity/examples/deploy-verify.mdx @@ -218,4 +218,3 @@ Running `npx hardhat verify` without the `sourcify` subtask attempts verificatio | --- | --- | --- | --- | | Mainnet | 1329 | `https://evm-rpc.sei-apis.com` | [seiscan.io](https://seiscan.io) | | Testnet | 1328 | `https://evm-rpc-testnet.sei-apis.com` | [testnet.seiscan.io](https://testnet.seiscan.io) | -| Devnet | 713715 | `https://evm-rpc-arctic-1.sei-apis.com` | — | diff --git a/evm/evm-parity/examples/pointer-contracts.mdx b/evm/evm-parity/examples/pointer-contracts.mdx index ee29425..ccc9973 100644 --- a/evm/evm-parity/examples/pointer-contracts.mdx +++ b/evm/evm-parity/examples/pointer-contracts.mdx @@ -15,8 +15,9 @@ This guide covers pointers for already-deployed CosmWasm contracts only. It does | --- | --- | --- | | CW20 (CosmWasm fungible token) | ERC-20 pointer | Standard ERC-20 | | CW721 (CosmWasm NFT) | ERC-721 pointer | Standard ERC-721 | +| CW1155 (CosmWasm multi-token) | ERC-1155 pointer | Standard ERC-1155 | -Once you have the pointer address, you interact with it using the standard ERC-20 or ERC-721 interface — no Sei-specific code needed. +Once you have the pointer address, you interact with it using the standard ERC-20, ERC-721, or ERC-1155 interface. For background on how pointer contracts work, see the [Pointers overview](/learn/pointers). @@ -51,6 +52,14 @@ const erc721Pointer = await client.readContract({ functionName: 'getCW721Pointer', args: ['sei1...cw721ContractAddress'], }); + +// CW1155 → ERC-1155 pointer +const erc1155Pointer = await client.readContract({ + address: POINTERVIEW_PRECOMPILE_ADDRESS, + abi: POINTERVIEW_PRECOMPILE_ABI, + functionName: 'getCW1155Pointer', + args: ['sei1...cw1155ContractAddress'], +}); ``` ```ts ethers @@ -73,6 +82,9 @@ const erc20Pointer = await pointerview.getCW20Pointer('sei1...cw20ContractAddres // CW721 → ERC-721 pointer const erc721Pointer = await pointerview.getCW721Pointer('sei1...cw721ContractAddress'); + +// CW1155 → ERC-1155 pointer +const erc1155Pointer = await pointerview.getCW1155Pointer('sei1...cw1155ContractAddress'); ``` diff --git a/evm/evm-parity/examples/wagmi-react.mdx b/evm/evm-parity/examples/wagmi-react.mdx index 6e6e5a9..45cc121 100644 --- a/evm/evm-parity/examples/wagmi-react.mdx +++ b/evm/evm-parity/examples/wagmi-react.mdx @@ -33,7 +33,7 @@ The hooks below — `useBlockNumber`, `useBalance` — are thin wrappers over JS ## Install ```bash -npm install wagmi viem @sei-js/precompiles @tanstack/react-query +npm install wagmi viem @sei-js/precompiles@^3 @tanstack/react-query ``` ## Configuration diff --git a/evm/evm-parity/websocket.mdx b/evm/evm-parity/websocket.mdx index be7d876..cd7aedf 100644 --- a/evm/evm-parity/websocket.mdx +++ b/evm/evm-parity/websocket.mdx @@ -13,7 +13,6 @@ Sei supports `eth_subscribe` over WebSocket. You can subscribe to new blocks, ev | --- | --- | | Mainnet | `wss://evm-ws.sei-apis.com` | | Testnet | `wss://evm-ws-testnet.sei-apis.com` | -| Devnet | `wss://evm-ws-arctic-1.sei-apis.com` | ## Connecting diff --git a/evm/ledger-ethers.mdx b/evm/ledger-ethers.mdx index e025901..1439231 100644 --- a/evm/ledger-ethers.mdx +++ b/evm/ledger-ethers.mdx @@ -3,7 +3,11 @@ title: 'Ledger Setup (EVM)' description: 'Set up your Ledger hardware wallet for signing EVM transactions on Sei, including device configuration, Ethers.js integration, and a simple transfer example.' keywords: ['ledger wallet', 'ethers.js', 'hardware wallet', 'blockchain security', 'sei transactions', 'evm'] --- -This guide covers connecting a Ledger hardware wallet to Sei's EVM for signing transactions with Ethers.js. For Cosmos-side signing with the `@sei-js/ledger` package, see the [@sei-js/ledger reference](/evm/sei-js/ledger). +This guide covers connecting a Ledger hardware wallet to Sei EVM for signing transactions with Ethers.js. + + +`@sei-js/ledger` is no longer in the sei-js monorepo. npm still serves deprecated `1.1.6`; do not install it. It previously handled Cosmos-side Amino signing, and there is no replacement package for that flow. Cosmos SDK signing is deprecated. See [SIP-3](/learn/sip-03-migration) and the [Cosmos SDK deprecation notice](/cosmos-sdk). This page covers EVM transactions only. + ## Prerequisites diff --git a/evm/precompiles/cosmwasm-precompiles/addr.mdx b/evm/precompiles/cosmwasm-precompiles/addr.mdx index 2f786bb..c547dd9 100644 --- a/evm/precompiles/cosmwasm-precompiles/addr.mdx +++ b/evm/precompiles/cosmwasm-precompiles/addr.mdx @@ -108,8 +108,8 @@ npx hardhat --init # Install ethers.js for smart contract interactions npm install ethers -# Install Sei EVM bindings for precompile addresses and ABIs -npm install @sei-js/precompiles@2.1.2 +# Install @sei-js/precompiles for precompile addresses and ABIs +npm install @sei-js/precompiles@^3 ``` #### Setup Hardhat Environment diff --git a/evm/precompiles/cosmwasm-precompiles/bank.mdx b/evm/precompiles/cosmwasm-precompiles/bank.mdx index 48b1021..957113d 100644 --- a/evm/precompiles/cosmwasm-precompiles/bank.mdx +++ b/evm/precompiles/cosmwasm-precompiles/bank.mdx @@ -33,7 +33,7 @@ The examples below use `balance()` with `usei`. They do not cover arbitrary Bank ## Setup ```bash -npm install ethers @sei-js/precompiles +npm install ethers @sei-js/precompiles@^3 ``` ```typescript diff --git a/evm/precompiles/cosmwasm-precompiles/cosmwasm.mdx b/evm/precompiles/cosmwasm-precompiles/cosmwasm.mdx index d0e82e8..2affbfa 100644 --- a/evm/precompiles/cosmwasm-precompiles/cosmwasm.mdx +++ b/evm/precompiles/cosmwasm-precompiles/cosmwasm.mdx @@ -105,8 +105,8 @@ Install the required packages for interacting with Sei precompiles: # Install ethers.js for smart contract interactions npm install ethers -# Install Sei EVM bindings for precompile addresses and ABIs -npm install @sei-js/precompiles@2.1.2 +# Install @sei-js/precompiles for precompile addresses and ABIs +npm install @sei-js/precompiles@^3 ``` #### Import Precompile Components diff --git a/evm/precompiles/cosmwasm-precompiles/example-usage.mdx b/evm/precompiles/cosmwasm-precompiles/example-usage.mdx index 5fe3cd6..d21cff5 100644 --- a/evm/precompiles/cosmwasm-precompiles/example-usage.mdx +++ b/evm/precompiles/cosmwasm-precompiles/example-usage.mdx @@ -6,7 +6,7 @@ keywords: ["precompile example", "ethers.js", "cosmwasm query", "evm integration -Per [Proposal 115](https://seistream.app/proposals/115), no new CosmWasm contracts can be deployed on Sei. The examples below apply to **pre-existing CosmWasm contracts** only — `instantiate()` will revert. +Per [Proposal 115](https://seistream.app/proposals/115), no new CosmWasm contracts can be deployed on Sei. The examples below apply to **pre-existing CosmWasm contracts** only. `instantiate()` will revert. The Sei precompiles can be used like any standard smart contract on the EVM. For @@ -19,17 +19,15 @@ To install `ethers`, run the following command in your project directory terminal: ```bash -npm install ethers -npm install @sei-js/evm +npm install ethers @sei-js/precompiles@^3 ``` -Next, you'll need to use one of the precompiles in `EVM Precompiles` section. In -this example, we're going to be using the [wasmd precompile](/evm/precompiles/cosmwasm-precompiles/cosmwasm): +This example uses the [CosmWasm precompile](/evm/precompiles/cosmwasm-precompiles/cosmwasm): ```typescript // Import Wasm precompile address and ABI -// View the entire ABI here: https://github.com/sei-protocol/sei-chain/tree/evm/precompiles/wasmd -import { WASM_PRECOMPILE_ABI, WASM_PRECOMPILE_ADDRESS } from '@sei-js/evm'; +// View the source ABI: https://github.com/sei-protocol/sei-chain/tree/main/precompiles/wasmd +import { WASM_PRECOMPILE_ABI, WASM_PRECOMPILE_ADDRESS } from '@sei-js/precompiles'; ``` ## Using the contract diff --git a/evm/precompiles/distribution.mdx b/evm/precompiles/distribution.mdx index aad554c..143ae93 100644 --- a/evm/precompiles/distribution.mdx +++ b/evm/precompiles/distribution.mdx @@ -16,7 +16,7 @@ The distribution precompile provides EVM access to Cosmos SDK's distribution mod - **Commission Handling**: Validators can withdraw earned commissions - **Batch Operations**: Withdraw from multiple validators efficiently - **Flexible Withdrawals**: Set custom withdrawal addresses -- **Comprehensive Queries**: Access detailed reward information +- **Comprehensive Queries**: Access detailed reward information through `rewards(address)` ## Interface Overview @@ -39,6 +39,20 @@ interface IDistr { } ``` +## Setup + +Install Ethers.js and the Sei EVM bindings that ship the precompile address and ABI: + +```bash +npm install ethers @sei-js/precompiles@^3 +``` + +Import both constants wherever you build the contract instance: + +```ts +import { DISTRIBUTION_PRECOMPILE_ABI, DISTRIBUTION_PRECOMPILE_ADDRESS } from '@sei-js/precompiles'; +``` + ## Events The distribution precompile emits events for all state-changing operations, allowing off-chain services to track reward distributions and configuration changes. @@ -474,4 +488,4 @@ function setupTreasuryWithdrawals(address treasury) external onlyOwner { } ``` -View the complete distribution precompile source code and ABI [here](https://github.com/sei-protocol/sei-chain/tree/main/precompiles/distribution). +View the complete distribution precompile ABI at the [Sei Chain v6.6.1 snapshot](https://github.com/sei-protocol/sei-chain/blob/v6.6.1/precompiles/distribution/legacy/v66/abi.json). diff --git a/evm/precompiles/example-usage.mdx b/evm/precompiles/example-usage.mdx index e620dd4..bf84897 100644 --- a/evm/precompiles/example-usage.mdx +++ b/evm/precompiles/example-usage.mdx @@ -12,18 +12,35 @@ Sei precompiles are special smart contracts deployed at fixed addresses that exp | Precompile | Address | Description | | --- | --- | --- | -| Bank | `0x1001` | Query the native SEI bank balance | -| JSON | `0x1003` | Parse JSON data within contracts | -| Staking | `0x1005` | Delegation and staking operations | -| Governance | `0x1006` | Proposal voting | -| Distribution | `0x1007` | Claim staking rewards | -| P256 | `0x1011` | Verify P-256 elliptic curve signatures | +| Bank | `0x0000000000000000000000000000000000001001` | Query the native SEI bank balance | +| CosmWasm | `0x0000000000000000000000000000000000001002` | Query or execute existing CosmWasm contracts. `instantiate()` reverts (Proposal 115). | +| JSON | `0x0000000000000000000000000000000000001003` | Parse JSON data within contracts | +| Address | `0x0000000000000000000000000000000000001004` | Convert and associate EVM and Sei addresses | +| Staking | `0x0000000000000000000000000000000000001005` | Delegation and staking operations | +| Governance | `0x0000000000000000000000000000000000001006` | Proposal voting | +| Distribution | `0x0000000000000000000000000000000000001007` | Claim staking rewards | +| Pointer view | `0x000000000000000000000000000000000000100A` | Look up pointer contract addresses | +| Pointer | `0x000000000000000000000000000000000000100B` | Register pointer contracts | +| Solo | `0x000000000000000000000000000000000000100C` | Claim Solo migration payloads | +| P256 | `0x0000000000000000000000000000000000001011` | Verify P-256 elliptic curve signatures | + +This page shows Bank, Staking, Governance, Distribution, JSON, and Solo. The rest are covered on their own pages: [CosmWasm](/evm/precompiles/cosmwasm-precompiles/cosmwasm), [Address](/evm/precompiles/cosmwasm-precompiles/addr), [Pointer contracts](/evm/evm-parity/examples/pointer-contracts) for both pointer precompiles, and [P256](/evm/precompiles/p256-precompile). +The IBC and Oracle precompiles are not exported by `@sei-js/precompiles`. IBC is disabled in both directions, and native Oracle queries are retired. Calls to either precompile cannot succeed on live Sei. See [IBC is disabled](/learn/sip-03-migration#ibc-is-disabled) and [Oracle Precompile (Retired)](/evm/precompiles/oracle). + + +`@sei-js/precompiles@3` is ESM-only and matches Sei Chain v6.6.1 ABIs. Import raw `*_PRECOMPILE_ABI` constants from the package root, `@sei-js/precompiles/precompiles`, or `@sei-js/precompiles/viem`. Ethers factories are on `@sei-js/precompiles/ethers`. The package does not expose `VIEM_*_PRECOMPILE_ABI` aliases. It re-exports Viem's `sei` and `seiTestnet` definitions and also exports `seiLocal` (chain ID `713714`, `http://localhost:8545`). Viem 2.55.16 or newer is required. + +```ts +import { getStakingPrecompileEthersV6Contract } from '@sei-js/precompiles/ethers'; +``` + + ## Setup ```bash -npm install viem ethers @sei-js/precompiles +npm install viem ethers @sei-js/precompiles@^3 ``` @@ -109,7 +126,7 @@ const delegation = await client.readContract({ args: [account, 'seivaloper1...'], }); -// Undelegate 5 SEI — amount is in 6-decimal usei (1 SEI = 1_000_000 usei), not wei +// Undelegate 5 SEI. The amount uses 6-decimal usei (1 SEI = 1_000_000 usei), not wei. const undelegateHash = await walletClient.writeContract({ address: STAKING_PRECOMPILE_ADDRESS, abi: STAKING_PRECOMPILE_ABI, @@ -132,7 +149,7 @@ await tx.wait(); const delegation = await readStaking.delegation(await signer.getAddress(), 'seivaloper1...'); console.log('Delegated:', delegation.balance.amount.toString()); -// Undelegate 5 SEI — amount is in 6-decimal usei (1 SEI = 1_000_000 usei), not wei +// Undelegate 5 SEI. The amount uses 6-decimal usei (1 SEI = 1_000_000 usei), not wei. const undelegateTx = await staking.undelegate('seivaloper1...', ethers.parseUnits('5', 6)); await undelegateTx.wait(); ``` @@ -203,7 +220,7 @@ await tx.wait(); ## JSON Precompile -Parse JSON data within EVM contracts or dApps — useful for processing oracle responses, NFT metadata, and structured payloads: +Parse JSON data within EVM contracts or dApps. This is useful for processing oracle responses, NFT metadata, and structured payloads: @@ -251,6 +268,36 @@ console.log(`${symbol}: ${price}`); +## Solo Precompile + +Claim a Solo migration payload. Both functions take the signed payload as `bytes` and return a boolean: + + + +```ts viem +import { SOLO_PRECOMPILE_ABI, SOLO_PRECOMPILE_ADDRESS } from '@sei-js/precompiles'; + +const hash = await walletClient.writeContract({ + address: SOLO_PRECOMPILE_ADDRESS, + abi: SOLO_PRECOMPILE_ABI, + functionName: 'claim', + args: ['0xYourPayloadBytes'], +}); +``` + +```ts ethers +import { getSoloPrecompileEthersV6Contract } from '@sei-js/precompiles/ethers'; + +const solo = getSoloPrecompileEthersV6Contract(signer); + +const tx = await solo.claim('0xYourPayloadBytes'); +await tx.wait(); +``` + + + +Use `claimSpecific` with the same argument shape to claim a single payload rather than everything available to the address. + ## Common Patterns ### Error Handling @@ -281,16 +328,16 @@ Fetch multiple precompile values in parallel: const [delegation1, delegation2, rewards] = await Promise.all([ readStaking.delegation(address, validator1), readStaking.delegation(address, validator2), - distribution.delegationTotalRewards(address), + distribution.rewards(address), ]); ``` ### Gas Limits -Precompile calls that write state need enough gas. Use `estimateGas` rather than hard-coding: +Precompile calls that write state need enough gas. Use `estimateContractGas` rather than hard-coding: ```ts viem -const gas = await client.estimateGas({ +const gas = await client.estimateContractGas({ account, address: STAKING_PRECOMPILE_ADDRESS, abi: STAKING_PRECOMPILE_ABI, @@ -352,3 +399,5 @@ For full ABI reference and all available functions on each precompile: - [Distribution Precompile →](/evm/precompiles/distribution) - [JSON Precompile →](/evm/precompiles/json) - [P256 Precompile →](/evm/precompiles/p256-precompile) +- [CosmWasm Precompiles →](/evm/precompiles/cosmwasm-precompiles/example-usage) +- [Pointer contracts →](/evm/evm-parity/examples/pointer-contracts) diff --git a/evm/precompiles/governance.mdx b/evm/precompiles/governance.mdx index 552134c..1e54e21 100644 --- a/evm/precompiles/governance.mdx +++ b/evm/precompiles/governance.mdx @@ -1,12 +1,12 @@ --- title: 'Governance Precompile Usage' sidebarTitle: 'Governance' -description: "Learn how to interact with Sei's governance precompile through ethers.js, enabling proposal submission, voting, token deposits, and governance queries to participate in on-chain governance directly from EVM applications." +description: "Learn how to interact with Sei's governance precompile through ethers.js, enabling proposal submission, voting, and token deposits from EVM applications." keywords: ['governance precompile', 'ethers.js', 'proposal voting', 'blockchain governance', 'on-chain voting', 'sei evm', 'dao governance'] --- **Address:** `0x0000000000000000000000000000000000001006` -The Sei governance precompile enables EVM applications to participate in Sei's on-chain governance process. This allows users and smart contracts to submit proposals, vote on them, deposit tokens, and query governance information directly through the EVM interface. +The Sei governance precompile enables EVM applications to submit proposals, vote, and deposit tokens. The ABI is write-only. Query proposal state through Cosmos REST/RPC or a Sei explorer. **What is a precompile?** A precompile is a special smart contract deployed at a fixed address by the Sei protocol itself, that exposes custom native chain logic to EVM-based applications. It acts like a regular contract from the EVM's perspective, but executes privileged, low-level logic efficiently. @@ -122,8 +122,8 @@ Install the required packages for interacting with Sei precompiles: # Install ethers.js for smart contract interactions npm install ethers -# Install Sei EVM bindings for precompile addresses and ABIs -npm install @sei-js/precompiles@2.1.2 +# Install @sei-js/precompiles for precompile addresses and ABIs +npm install @sei-js/precompiles@^3 # Install dotenv for managing private keys (optional but recommended) npm install dotenv @@ -133,7 +133,7 @@ npm install dotenv ```typescript // Import Governance precompile address and ABI -// View the entire ABI here: https://github.com/sei-protocol/sei-chain/tree/main/precompiles/gov +// View the entire ABI here: https://github.com/sei-protocol/sei-chain/blob/v6.6.1/precompiles/gov/legacy/v66/abi.json import { GOVERNANCE_PRECOMPILE_ABI, GOVERNANCE_PRECOMPILE_ADDRESS } from '@sei-js/precompiles'; import { ethers } from 'ethers'; ``` @@ -621,10 +621,10 @@ await addDepositToProposal(proposalID, additionalDeposit); Create a comprehensive governance interaction script: -```javascript title="governance-mainnet-demo.js" -const { ethers } = require('ethers'); -const { GOVERNANCE_PRECOMPILE_ABI, GOVERNANCE_PRECOMPILE_ADDRESS } = require('@sei-js/precompiles'); -require('dotenv').config(); +```javascript title="governance-mainnet-demo.mjs" +import { ethers } from 'ethers'; +import { GOVERNANCE_PRECOMPILE_ABI, GOVERNANCE_PRECOMPILE_ADDRESS } from '@sei-js/precompiles'; +import 'dotenv/config'; // Validation functions function isValidVoteOption(option) { @@ -885,7 +885,7 @@ npm init -y 2. **Install dependencies:** ```bash -npm install ethers @sei-js/precompiles@^2.1.2 dotenv +npm install ethers @sei-js/precompiles@^3 dotenv ``` 3. **Create a `.env` file:** @@ -895,7 +895,7 @@ PRIVATE_KEY=your_private_key_here ``` 4. **Create the demo file:** - Copy the complete integration example above into `governance-mainnet-demo.js` + Copy the complete integration example above into `governance-mainnet-demo.mjs` 5. **Ensure you have sufficient SEI:** @@ -906,7 +906,7 @@ PRIVATE_KEY=your_private_key_here 6. **Run the script:** ```bash -node governance-mainnet-demo.js +node governance-mainnet-demo.mjs ``` ### Expected Output diff --git a/evm/precompiles/json.mdx b/evm/precompiles/json.mdx index 6541c0d..14896a9 100644 --- a/evm/precompiles/json.mdx +++ b/evm/precompiles/json.mdx @@ -12,7 +12,7 @@ The Sei JSON precompile allows EVM applications to efficiently parse and query J ## How Does the JSON Precompile Work? -The JSON precompile at address `0x0000000000000000000000000000000000001003` exposes functions like `extractAsBytes()`, `extractAsBytesList()`, and `extractAsUint256()`. +The JSON precompile at address `0x0000000000000000000000000000000000001003` exposes `extractAsBytes()`, `extractAsBytesList()`, `extractAsBytesFromArray()`, and `extractAsUint256()`. - **Direct Integration:** EVM contracts and dApps can parse JSON data like any other smart contract method. - **Native Execution:** JSON parsing is executed at the native level for maximum efficiency. @@ -51,6 +51,15 @@ function extractAsBytesList( string memory key ) external view returns (bytes[] memory response); +/// Extracts one element from a JSON array by index. +/// @param input The input data. +/// @param arrayIndex The zero-based array index. +/// @return The extracted data as bytes. +function extractAsBytesFromArray( + bytes memory input, + uint16 arrayIndex +) external view returns (bytes memory response); + /// Extracts data as a uint256 from the input using the specified key. /// @param input The input data. /// @param key The key to extract. @@ -82,8 +91,8 @@ Install the required packages for interacting with Sei precompiles: # Install ethers.js for smart contract interactions npm install ethers -# Install Sei EVM bindings for precompile addresses and ABIs -npm install @sei-js/precompiles@^2.1.2 +# Install @sei-js/precompiles for precompile addresses and ABIs +npm install @sei-js/precompiles@^3 # Install dotenv for managing private keys (recommended for security) npm install dotenv @@ -93,7 +102,7 @@ npm install dotenv ```typescript // Import JSON precompile address and ABI -// View the entire ABI here: https://github.com/sei-protocol/sei-chain/tree/main/precompiles/json +// View the entire ABI here: https://github.com/sei-protocol/sei-chain/blob/v6.6.1/precompiles/json/legacy/v66/abi.json import { JSON_PRECOMPILE_ABI, JSON_PRECOMPILE_ADDRESS } from '@sei-js/precompiles'; import { ethers } from 'ethers'; ``` @@ -294,11 +303,11 @@ console.log('Wallet data:', walletData); // Output: { balance: 1000, currency: " Create a comprehensive JSON parsing application for mainnet: -```javascript title="json-precompile-mainnet.js" -// json-precompile-mainnet.js -const { ethers } = require('ethers'); -const { JSON_PRECOMPILE_ABI, JSON_PRECOMPILE_ADDRESS } = require('@sei-js/precompiles'); -require('dotenv').config(); +```javascript title="json-precompile-mainnet.mjs" +// json-precompile-mainnet.mjs +import { ethers } from 'ethers'; +import { JSON_PRECOMPILE_ABI, JSON_PRECOMPILE_ADDRESS } from '@sei-js/precompiles'; +import 'dotenv/config'; // Safe extraction utilities async function safeExtractBytes(jsonPrecompile, data, key, defaultValue = '') { @@ -506,7 +515,7 @@ npm init -y 2. **Install dependencies:** ```bash -npm install ethers @sei-js/precompiles@^2.1.2 dotenv +npm install ethers @sei-js/precompiles@^3 dotenv ``` 3. **Create a `.env` file:** @@ -518,7 +527,7 @@ PRIVATE_KEY=your_private_key_here **Security Note:** Never commit private keys to version control! The `.env` file should be added to your `.gitignore`. 4. **Create the demo file:** - Copy the complete integration example above into `json-precompile-mainnet.js` + Copy the complete integration example above into `json-precompile-mainnet.mjs` 5. **Ensure you have SEI tokens:** @@ -527,7 +536,7 @@ PRIVATE_KEY=your_private_key_here 6. **Run the script:** ```bash -node json-precompile-mainnet.js +node json-precompile-mainnet.mjs ``` ### Expected Output @@ -703,7 +712,7 @@ async function handleMissingKeys(jsonPrecompile: ethers.Contract, data: any) { - **Decimal Handling:** Store decimal numbers as integers with known precision (e.g., 275 for 2.75 with 2 decimal places) - **Boolean Values:** Use 0/1 integers to represent false/true - **Key Paths:** Extract parent objects first, then parse manually - dot notation may not be supported -- **Arrays:** Must use `extractAsBytesList()` for array data +- **Arrays:** Object-keyed arrays use `extractAsBytesList()`. JSON arrays by index use `extractAsBytesFromArray()`. - **Gas Costs:** Large JSON objects require higher gas limits - **Encoding:** Always use UTF-8 encoding with `ethers.toUtf8Bytes()` - **Error Handling:** Always implement fallback values for production applications diff --git a/evm/precompiles/p256-precompile.mdx b/evm/precompiles/p256-precompile.mdx index 5f468aa..0005063 100644 --- a/evm/precompiles/p256-precompile.mdx +++ b/evm/precompiles/p256-precompile.mdx @@ -351,11 +351,10 @@ function prepareP256Input(messageHash, signature, publicKey) { } // Usage with ethers.js -const P256_VERIFY_ADDRESS = '0x0000000000000000000000000000000000001011'; -const P256_VERIFY_ABI = ['function verify(bytes input) view returns (bytes response)']; +import { P256_PRECOMPILE_ABI, P256_PRECOMPILE_ADDRESS } from '@sei-js/precompiles'; async function verifyP256Signature(provider, messageHash, signature, publicKey) { - const precompile = new ethers.Contract(P256_VERIFY_ADDRESS, P256_VERIFY_ABI, provider); + const precompile = new ethers.Contract(P256_PRECOMPILE_ADDRESS, P256_PRECOMPILE_ABI, provider); const input = prepareP256Input(messageHash, signature, publicKey); try { const result = await precompile.verify(input); @@ -442,4 +441,4 @@ contract P256Test { - **Caching**: Cache public keys on-chain to reduce calldata for repeated verifications - **Hardware Integration**: Particularly efficient for applications using hardware-backed keys -For more information about the P256 precompile implementation, visit the [Sei Chain repository](https://github.com/sei-protocol/sei-chain/tree/main/precompiles/p256). +View the complete P256 precompile ABI in the [Sei Chain v6.6.1 snapshot](https://github.com/sei-protocol/sei-chain/blob/v6.6.1/precompiles/p256/legacy/v66/abi.json), or browse the [implementation source](https://github.com/sei-protocol/sei-chain/tree/v6.6.1/precompiles/p256). diff --git a/evm/precompiles/staking.mdx b/evm/precompiles/staking.mdx index 16f33c2..1e6cab6 100644 --- a/evm/precompiles/staking.mdx +++ b/evm/precompiles/staking.mdx @@ -19,7 +19,7 @@ The staking precompile at address `0x0000000000000000000000000000000000001005` e - **Direct Integration:** EVM contracts and dApps can call staking functions like any other smart contract method. - **Native Execution:** Operations are executed at the Cosmos SDK level for maximum efficiency and security. - **Seamless Bridge:** No need for separate wallet integrations or complex cross-chain interactions. -- **Event Emission:** All staking operations emit events (`Delegate`, `Undelegate`, `Redelegate`, `ValidatorCreated`, `ValidatorEdited`) for easy tracking and indexing. +- **Event Emission:** Staking operations emit `Delegate`, `Undelegate`, `Redelegate`, `DelegationRewardsWithdrawn`, `ValidatorCreated`, and `ValidatorEdited`. ## Use Cases @@ -53,6 +53,18 @@ The staking precompile emits the following events: */ event Delegate(address indexed delegator, string validator, uint256 amount); +/** + * @notice Emitted when a delegator withdraws staking rewards + * @param delegator The address of the delegator + * @param validator The validator address + * @param amount The amount withdrawn in base units + */ +event DelegationRewardsWithdrawn( + address indexed delegator, + string validator, + uint256 amount +); + /** * @notice Emitted when tokens are redelegated from one validator to another * @param delegator The address of the delegator @@ -114,6 +126,10 @@ staking.on('Delegate', (delegator, validator, amount) => { console.log(`${delegator} delegated ${amount} to ${validator}`); }); +staking.on('DelegationRewardsWithdrawn', (delegator, validator, amount) => { + console.log(`${delegator} withdrew ${amount} from ${validator}`); +}); + // Listen for redelegation events staking.on('Redelegate', (delegator, srcValidator, dstValidator, amount) => { console.log(`${delegator} redelegated ${amount} from ${srcValidator} to ${dstValidator}`); @@ -467,15 +483,15 @@ Install the required packages for interacting with Sei precompiles: # Install ethers.js for smart contract interactions npm install ethers -# Install Sei EVM bindings for precompile addresses and ABIs -npm install @sei-js/precompiles@2.1.2 +# Install @sei-js/precompiles for precompile addresses and ABIs +npm install @sei-js/precompiles@^3 ``` #### Import Precompile Components ```typescript // Import Staking precompile address and ABI -// View the entire ABI here: https://github.com/sei-protocol/sei-chain/tree/main/precompiles/staking +// View the entire ABI here: https://github.com/sei-protocol/sei-chain/blob/v6.6.1/precompiles/staking/legacy/v66/abi.json import { STAKING_PRECOMPILE_ABI, STAKING_PRECOMPILE_ADDRESS } from '@sei-js/precompiles'; import { ethers } from 'ethers'; ``` diff --git a/evm/sei-global-wallet.mdx b/evm/sei-global-wallet.mdx index 9434f47..e6128c2 100644 --- a/evm/sei-global-wallet.mdx +++ b/evm/sei-global-wallet.mdx @@ -25,9 +25,8 @@ Unlike traditional browser extension wallets, Sei Global Wallet is built directl **For Developers:** -- **One-Line Integration:** Single import enables wallet across all EIP-6963 compatible libraries -- **Zero Configuration:** Pre-configured and ready to use -- **Universal Compatibility:** Works with RainbowKit, ConnectKit, Web3-React, and more +- **One-line integration:** A single EIP-6963 import works with RainbowKit, ConnectKit, Web3-React, and other compatible libraries +- **ESM-only:** `@sei-js/sei-global-wallet@2` has no `require()` entry. Add the [required consumer overrides](https://github.com/sei-protocol/sei-js/tree/main/packages/sei-global-wallet#required-consumer-overrides) before installing. ## How to Create a Sei Global Wallet Account @@ -47,6 +46,10 @@ Unlike traditional browser extension wallets, Sei Global Wallet is built directl ## Installation + +Add the [required consumer overrides](https://github.com/sei-protocol/sei-js/tree/main/packages/sei-global-wallet#required-consumer-overrides) to your root manifest **before** you install. Dynamic Global Wallet Client pulls `axios` and `uuid` versions with known vulnerabilities, and this package cannot push overrides into your app. The npm block pins `axios` to 1.18.0, `uuid` to 11.1.1, and `ws` to 8.21.0 under `viem`; the Bun block pins `axios` and `uuid` only. Drop the overrides once Dynamic ships a release that fixes those pins. + + Install Sei Global Wallet Package: ```bash @@ -65,6 +68,10 @@ Import the package to register the wallet: import '@sei-js/sei-global-wallet/eip6963'; ``` + +`@sei-js/sei-global-wallet@2` is ESM-only. The `/eip6963` import still registers the provider. It also exports `registerEIP6963Provider`, `unregisterEIP6963Provider`, and `eip6963ProviderInfo`. Other entrypoints are `/ethereum`, `/solana`, and `/zerodev`. + + **Important:** Importing the package registers the wallet for discovery, but you'll need to ensure your application's provider stack is properly configured to interact with it. Most wallet connection libraries that support EIP-6963 will automatically detect the wallet after import. --- @@ -1049,15 +1056,10 @@ chainId: '0x530'; // for Sei Testnet (1328) ### Debugging Commands ```javascript -// Check if EIP-6963 events are firing -console.log('EIP-6963 providers:', window.eip6963Providers); - -// Listen for wallet announcements window.addEventListener('eip6963:announceProvider', (event) => { console.log('Wallet announced:', event.detail); }); -// Request wallet announcements window.dispatchEvent(new Event('eip6963:requestProvider')); ``` diff --git a/evm/sei-js/create-sei.mdx b/evm/sei-js/create-sei.mdx index f7d44f7..36b7599 100644 --- a/evm/sei-js/create-sei.mdx +++ b/evm/sei-js/create-sei.mdx @@ -1,39 +1,41 @@ --- title: 'Scaffold Sei' -description: 'CLI tool for scaffolding production-ready Sei applications with pre-configured templates' +description: 'Create a Next.js dApp with wallet integration and Sei network configuration' keywords: ['create-sei', 'scaffold', 'cli', 'sei', 'nextjs', 'wagmi', 'viem', 'template'] --- -`@sei-js/create-sei` is a CLI tool that scaffolds production-ready Sei dApps in seconds. Quickly spin up templates with Next.js, modern wallet integration, and TypeScript support. +`@sei-js/create-sei` creates a Next.js dApp with TypeScript, wallet integration, and Sei network configuration. ```bash -npx @sei-js/create-sei app --name my-sei-app +npx @sei-js/create-sei app -n my-sei-app ``` -Every generated project includes wallet connections, contract interactions, TypeScript, Tailwind CSS, Mantine UI, Biome for formatting, and responsive layouts — no additional setup required. +The generated project includes Wagmi, Viem, RainbowKit, TypeScript, Tailwind CSS, Mantine UI, and Biome. It pins `@sei-js/precompiles` 3.x. -## Quick Start +## Quick start -You don't need to install `@sei-js/create-sei` globally. Use it directly with npx or pnpm: +You do not need to install `@sei-js/create-sei` globally. `-n` and `--name` are the same option. ```bash - npx @sei-js/create-sei app --name my-sei-app + npx @sei-js/create-sei app -n my-sei-app ``` - + ```bash - pnpm create @sei-js/sei app --name my-sei-app + bunx @sei-js/create-sei app -n my-sei-app ``` -## Interactive Setup +The project name must be an unscoped lowercase npm package name (`my-sei-app`). Scoped names, spaces, and most punctuation are rejected. + +## Interactive setup -Execute the create-sei command with your project name: +Run the command without `-n` to enter the project name interactively: ```bash npx @sei-js/create-sei app @@ -43,69 +45,72 @@ npx @sei-js/create-sei app ```bash cd my-sei-app -npm install -npm run dev +bun install +bun run dev ``` -The CLI automatically configures TypeScript, Next.js, Tailwind CSS, Biome formatting, Mantine UI components, and Git initialization. +Open `http://localhost:3000`. The generated dApp connects to Pacific-1 when `NEXT_PUBLIC_CHAIN` is unset. Set `NEXT_PUBLIC_CHAIN=testnet` in `.env.local` to use Atlantic-2. The template's `.env.example` already sets that value, so copying it to `.env.local` selects testnet. -### CLI Options +### CLI options -| Command | Description | -| ----------------------- | ----------------------------------------------------- | -| `app` | Create a new Sei dApp | -| `app --name ` | Specify a project name (must be a valid package name) | -| `app --extension ` | Add an optional extension to your project | -| `list-extensions` | List available extensions | +| Command | Description | +| ----------------------- | ------------------------------------------------------------------------ | +| `app` | Create a new Sei dApp | +| `app -n ` | Specify a project name (`--name` is the same flag) | +| `app --extension ` | Add an optional extension to your project | +| `list-extensions` | List available extensions | -## Default Template +## Default template -The default template creates a **Next.js + Wagmi (EVM)** application — a production-ready Next.js app with Wagmi for type-safe Ethereum wallet connections and blockchain interactions. Includes built-in support for MetaMask, WalletConnect, Coinbase Wallet, and other popular wallets. +The default template is a Next.js EVM dApp. Wagmi and Viem provide typed blockchain interactions. RainbowKit provides wallet connections and defaults to the generic injected connector, not a MetaMask-only setup. -**Tech Stack:** Next.js 14, Wagmi v2, Viem, TanStack Query, Tailwind CSS +The template pins Next.js 15, React 19, Wagmi 2, Viem 2, RainbowKit 2, TanStack Query 5, Tailwind CSS 4, Mantine 8, Biome 2, and `@sei-js/precompiles` 3.x. Exact versions live in the generated `package.json`. ```bash -npx @sei-js/create-sei app --name my-sei-app +npx @sei-js/create-sei app -n my-sei-app ``` +The template declares `packageManager: bun@1.3.14`, so use Bun 1.3.14 or newer for `bun install` and `bun run dev`. Its `overrides` block pins patched transitive dependencies in the npm and Bun format. Yarn reads `resolutions` and pnpm reads `pnpm.overrides`, so both skip those pins and resolve a different, unverified dependency graph. + +WalletConnect-based wallets need `NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID` in `.env.local`. The injected connector works without it. Next.js image optimization is disabled in the template because of a Sharp version conflict, so `next/image` serves unoptimized images. + ## Extensions -Enhance your project with additional functionality using extensions. +Use an extension to add an example to the base template. -### List Available Extensions +### List available extensions ```bash npx @sei-js/create-sei list-extensions ``` -### Precompiles Extension +### Precompiles extension -Add Sei precompile contract integration with examples for querying native blockchain data like token supply, staking info, and governance proposals. +Add a Bank precompile example that queries the native SEI supply: ```bash -npx @sei-js/create-sei app --name my-sei-precompile-app --extension precompiles +npx @sei-js/create-sei app -n my-sei-precompile-app --extension precompiles ``` -Includes Bank precompile, Staking precompile, and Governance precompile examples. - -## What's Included - -After running the CLI, you'll have a fully configured Sei dApp ready for development: +## Included configuration -- **Project structure** — Organized file structure with components, hooks, and utilities -- **Wallet integration** — Pre-configured wallet connections and hooks -- **Development tools** — TypeScript, Biome, Mantine UI, and Tailwind CSS with sensible defaults -- **Sei network integration** — Built-in network configuration and contract interaction examples +- Next.js App Router project structure +- Wallet connections through Wagmi, RainbowKit, and the injected browser-wallet connector +- Pacific-1 and Atlantic-2 chain configuration via `NEXT_PUBLIC_CHAIN` +- TypeScript, Biome, Mantine UI, and Tailwind CSS -**Prerequisites:** Node.js v18 or higher is required. Use `node --version` to verify your installation. + +Install [Node.js](https://nodejs.org/) 20 or newer to run the CLI with `npx`. That is the version the generated project's `.nvmrc` pins. Install [Bun](https://bun.sh/docs/installation) 1.3.14 or newer to install and run the generated project. + ## Troubleshooting -- **Node version conflicts** — Use `nvm use` to switch to the correct Node.js version -- **Permission errors** — Avoid using `sudo` with npm. Use `nvm` or fix npm permissions -- **Network timeouts** — Try switching to a different registry: `npm config set registry https://registry.npmjs.org/` +- If `bun install` fails, confirm `bun --version` reports 1.3.14 or newer. +- For Node.js version conflicts when running `npx`, use `nvm` to switch to Node 20 or newer. +- For npm permission errors, do not use `sudo`. Use `nvm` or fix your npm permissions. +- For registry timeouts, run `npm config set registry https://registry.npmjs.org/` before retrying `npx`. diff --git a/evm/sei-js/index.mdx b/evm/sei-js/index.mdx index a213e55..1ad7a6e 100644 --- a/evm/sei-js/index.mdx +++ b/evm/sei-js/index.mdx @@ -1,34 +1,40 @@ --- title: '@sei-js SDK' sidebarTitle: 'Introduction' -description: 'A complete TypeScript SDK for building decentralized applications on Sei Network' +description: 'TypeScript packages for building EVM applications on Sei' keywords: ['sei-js', 'typescript', 'sdk', 'sei network', 'evm', 'precompiles', 'wallet', 'mcp'] --- -@sei-js is the complete TypeScript SDK for building applications on Sei Network. Whether you're creating DeFi protocols, NFT marketplaces, or blockchain games, @sei-js provides everything you need to ship faster. +`@sei-js` is a set of TypeScript packages for building EVM applications on Sei. Use the packages for Sei-specific functionality, and use standard EVM libraries such as Viem or Ethers.js for everything else. -**Works with your favorite tools:** Sei is fully EVM-compatible, so you can use Viem, Ethers.js, Foundry, Hardhat, and all your existing Ethereum development tools without any changes. @sei-js extends these tools with Sei-specific features like precompiled contracts and optimized wallet connections. +Sei is EVM-compatible, so you can also use Foundry, Hardhat, Wagmi, and other Ethereum tooling. `@sei-js` adds precompile ABIs, chain definitions, wallet integration, network metadata, scaffolding, and an MCP server. @sei-js is open source. Contribute at [github.com/sei-protocol/sei-js](https://github.com/sei-protocol/sei-js). + +Current npm majors are ESM-only: `@sei-js/precompiles@3`, `@sei-js/registry@2`, `@sei-js/create-sei@2`, `@sei-js/sei-global-wallet@2`, and `@sei-js/mcp-server@1`. Use `import`. `require()` does not resolve these packages. `@sei-js/precompiles` needs Viem 2.55.16 or newer. The MCP server needs Node.js 20 or newer. `@sei-js/ledger` is not part of the current monorepo. + + ## Why @sei-js? -- **Complete TypeScript support** — Full type safety for every function, contract interaction, and API response. Catch errors at compile time. -- **Production ready** — Battle-tested components used by major applications in the Sei ecosystem. -- **Optimized for Sei** — Take advantage of Sei's fast finality, low gas, and native features. +- Typed ABIs and addresses for Sei precompiles +- Viem's Pacific-1 and Atlantic-2 chain definitions re-exported for convenience, plus a `seiLocal` definition for local nodes +- Packages that work with standard EVM libraries -## Package Ecosystem +## Packages ### [@sei-js/precompiles](/evm/precompiles) -Access Sei's precompiled contracts directly from your EVM applications. Interact with native blockchain functions for staking, governance, and more. +Import precompile addresses and raw `*_PRECOMPILE_ABI` constants from the package root, `@sei-js/precompiles/precompiles`, or `@sei-js/precompiles/viem`. Ethers factories live on `@sei-js/precompiles/ethers`. + +Viem owns the `sei` and `seiTestnet` chain definitions, so import those from `viem/chains`. The root and `viem` entrypoints re-export them if you would rather use a single import, and they also export `seiLocal` for a local node. ```bash -npm install @sei-js/precompiles +npm install @sei-js/precompiles@^3 ``` ### [@sei-js/create-sei](/evm/sei-js/create-sei) -Bootstrap new Sei projects with pre-configured templates and tooling. Scaffold production-ready dApps in seconds. +Create a Next.js dApp with wallet integration, TypeScript, and Sei network configuration. ```bash npx @sei-js/create-sei app @@ -36,23 +42,15 @@ npx @sei-js/create-sei app ### [@sei-js/sei-global-wallet](/evm/sei-global-wallet) -Connect to any Sei-compatible wallet using the EIP-6963 standard. Provides a cross-application embedded wallet experience with social login. +Add the EIP-6963 compatible Sei Global Wallet to a dApp. ```bash npm install @sei-js/sei-global-wallet ``` -### [@sei-js/ledger](/evm/sei-js/ledger) - -Secure transaction signing with Ledger hardware wallets. Provides TypeScript helper functions for address derivation and offline Amino signing via the SEI Ledger app. - -```bash -npm install @sei-js/ledger -``` - ### [@sei-js/registry](/evm/sei-js/registry) -Chain constants, RPC endpoints, token metadata, gas parameters, and wallet info — a typed reference for Sei network configuration. +Use typed chain IDs, RPC endpoints, token metadata, and wallet information for Pacific-1 and Atlantic-2. ```bash npm install @sei-js/registry @@ -60,24 +58,45 @@ npm install @sei-js/registry ### [@sei-js/mcp-server](/ai/mcp-server) -Teach Claude, Cursor, Windsurf, or any LLM to interact with the Sei blockchain through the Model Context Protocol. +Connect an MCP-compatible AI assistant to Sei for blockchain queries, contract interactions, and documentation search. ```bash npx @sei-js/mcp-server ``` -## Quick Start +## Deprecated packages + +The five packages above are the entire current monorepo. Every other `@sei-js` package is deprecated on npm and no longer maintained. If one of these appears in your `package.json`, migrate off it. + +| Deprecated package | What to use instead | +| --- | --- | +| `@sei-js/evm` | `@sei-js/precompiles` — same library, renamed | +| `@sei-js/ledger` | No replacement. See [Ledger with ethers](/evm/ledger-ethers) for the EVM signing flow | +| `@sei-js/x402` | `@x402/core` and `@x402/evm`. See [x402 on Sei](/ai/x402) | +| `@sei-js/x402-fetch` | `@x402/fetch` and `@x402/evm` | +| `@sei-js/x402-axios` | `@x402/axios` and `@x402/evm` | +| `@sei-js/x402-express` | `@x402/express`, `@x402/core`, and `@x402/evm` | +| `@sei-js/x402-hono` | `@x402/hono`, `@x402/core`, and `@x402/evm` | +| `@sei-js/x402-next` | `@x402/next`, `@x402/core`, and `@x402/evm` | +| `@sei-js/core` | No replacement. Use Viem or Ethers.js for EVM access | +| `@sei-js/cosmjs` | No replacement | +| `@sei-js/cosmos` | No replacement | +| `@sei-js/proto` | No replacement | -Generate a new Sei application using the CLI tool: +The last four covered Cosmos SDK access, which is deprecated under [SIP-3](/learn/sip-03-migration). Build on the EVM instead. + +## Quick start + +Generate a new Sei dApp: ```bash -npx @sei-js/create-sei app -cd app -npm install -npm run dev +npx @sei-js/create-sei app -n my-sei-app +cd my-sei-app +bun install +bun run dev ``` -This creates a production-ready project with TypeScript, wallet connections, and Sei network integration out of the box. See the [Scaffold Sei](/evm/sei-js/create-sei) page for details on available templates and options. +See [Scaffold Sei](/evm/sei-js/create-sei) for the generated template and CLI options. ## Examples @@ -122,7 +141,7 @@ End-to-end code examples using viem and ethers with Sei: -## Community & Support +## Community and support -- [Discord](https://discord.gg/sei) — Join the Sei developer community -- [GitHub Issues](https://github.com/sei-protocol/sei-js/issues) — Report bugs and request features +- [Discord](https://discord.gg/sei): Join the Sei developer community +- [GitHub Issues](https://github.com/sei-protocol/sei-js/issues): Report bugs and request features diff --git a/evm/sei-js/ledger.mdx b/evm/sei-js/ledger.mdx deleted file mode 100644 index c3bc183..0000000 --- a/evm/sei-js/ledger.mdx +++ /dev/null @@ -1,139 +0,0 @@ ---- -title: '@sei-js/ledger' -description: 'TypeScript library for SEI Ledger app helper functions — address derivation, Amino signing, and CosmJS integration' -keywords: ['sei-js', 'ledger', 'hardware wallet', 'cosmos', 'amino', 'cosmjs', 'offline signer'] ---- -The `@sei-js/ledger` package provides TypeScript helper functions for the SEI Ledger hardware wallet app. It enables address derivation and offline Amino signing for Cosmos-side transactions on Sei. - -For EVM-side transaction signing with Ethers.js, see the [Ledger Setup (EVM)](/evm/ledger-ethers) guide instead. - -## Installation - -```bash -npm install @sei-js/ledger -``` - -## Hardware Requirements - -- Ledger Nano S Plus, Nano X, or compatible device -- **SEI app** installed on the Ledger device (via Ledger Live Manager) -- USB or Bluetooth connection to your computer - -## Core Functions - -### createTransportAndApp - -Creates a transport connection and app instance for communicating with the Ledger device. - -```typescript -import { createTransportAndApp } from '@sei-js/ledger'; - -const { transport, app } = await createTransportAndApp(); -``` - -**Returns:** `Promise<{ transport: Transport, app: SeiApp }>` - -### getAddresses - -Retrieves both EVM and Cosmos addresses from the Ledger device for a given derivation path. - -```typescript -import { createTransportAndApp, getAddresses } from '@sei-js/ledger'; - -const { app } = await createTransportAndApp(); -const { evmAddress, nativeAddress } = await getAddresses(app, "m/44'/60'/0'/0/0"); - -console.log('EVM address:', evmAddress); -console.log('Sei address:', nativeAddress); -``` - -**Parameters:** -| Parameter | Type | Description | -|-----------|------|-------------| -| `app` | `SeiApp` | Ledger Sei app instance | -| `path` | `string` | HD derivation path (e.g. `"m/44'/60'/0'/0/0"`) | - -**Returns:** `Promise<{ evmAddress: string, nativeAddress: string }>` - -### SeiLedgerOfflineAminoSigner - -A signer class compatible with CosmJS that enables offline Amino signing via Ledger. - -```typescript -import { SeiLedgerOfflineAminoSigner } from '@sei-js/ledger'; - -const ledgerSigner = new SeiLedgerOfflineAminoSigner(app, "m/44'/60'/0'/0/0"); -``` - -**Constructor Parameters:** -| Parameter | Type | Description | -|-----------|------|-------------| -| `app` | `SeiApp` | Ledger Sei app instance | -| `path` | `string` | HD derivation path | - -#### getAccounts - -Retrieves account information from the Ledger device. - -```typescript -const accounts = await ledgerSigner.getAccounts(); -// [{ address: 'sei1...', pubkey: { type: 'tendermint/PubKeySecp256k1', value: '...' } }] -``` - -#### signAmino - -Signs a transaction document using the Ledger device. The device will prompt for physical confirmation. - -```typescript -import { StdSignDoc } from '@cosmjs/amino'; - -const signDoc: StdSignDoc = { - /* your transaction document */ -}; -const { signed, signature } = await ledgerSigner.signAmino('sei1...', signDoc); -``` - -## Complete Example: Delegating Tokens - -```typescript -import { coins, SigningStargateClient, StdFee } from '@cosmjs/stargate'; -import { createTransportAndApp, getAddresses, SeiLedgerOfflineAminoSigner } from '@sei-js/ledger'; - -async function delegateWithLedger() { - const rpcUrl = 'https://rpc-testnet.sei-apis.com/'; - const path = "m/44'/60'/0'/0/0"; - - const { app } = await createTransportAndApp(); - const { nativeAddress } = await getAddresses(app, path); - const ledgerSigner = new SeiLedgerOfflineAminoSigner(app, path); - - const client = await SigningStargateClient.connectWithSigner(rpcUrl, ledgerSigner); - - const msgDelegate = { - typeUrl: '/cosmos.staking.v1beta1.MsgDelegate', - value: { - delegatorAddress: nativeAddress, - validatorAddress: 'seivaloper1...', - amount: coins(500, 'usei') - } - }; - - const fee: StdFee = { - amount: [{ denom: 'usei', amount: '20000' }], - gas: '200000' - }; - - const result = await client.signAndBroadcast(nativeAddress, [msgDelegate], fee, 'Delegation via Ledger'); - - console.log('Broadcast result:', result); -} - -delegateWithLedger(); -``` - -## Security - -- Ensure your Ledger device is genuine and purchased from official sources -- Always verify transaction details on the Ledger screen before confirming -- Keep your Ledger firmware and the SEI app updated -- Store your recovery phrase securely and never share it diff --git a/evm/sei-js/registry.mdx b/evm/sei-js/registry.mdx index d1b3c3f..640a0b7 100644 --- a/evm/sei-js/registry.mdx +++ b/evm/sei-js/registry.mdx @@ -1,13 +1,17 @@ --- title: '@sei-js/registry' sidebarTitle: '@sei-js/registry' -description: 'Chain constants, RPC endpoints, token metadata, and wallet info for Sei Network' +description: 'Typed chain constants, RPC endpoints, token metadata, and wallet information for Sei' keywords: ['sei-js', 'registry', 'chain constants', 'rpc endpoints', 'token list', 'sei network'] --- -`@sei-js/registry` is a typed reference package for Sei chain metadata — RPC endpoints, token lists, gas parameters, wallet info, and more. It pulls from the official [sei-protocol/chain-registry](https://github.com/sei-protocol/chain-registry) and is kept in sync as a git submodule. +`@sei-js/registry` exports typed chain IDs, endpoints, token metadata, and wallet information for Pacific-1 and Atlantic-2. Network and wallet data comes from the official [sei-protocol/chain-registry](https://github.com/sei-protocol/chain-registry). Token metadata comes from the community-maintained [Seitrace asset list](https://github.com/Seitrace/sei-assetlist). -## Install + +The package is ESM-only. Pacific-1 and Atlantic-2 are the only supported networks. `CHAIN_IDS.devnet`, `GAS_INFO`, and `IBC_INFO` are no longer exported. + + +## Installation ```bash npm install @sei-js/registry @@ -22,7 +26,6 @@ import { CHAIN_IDS } from '@sei-js/registry'; CHAIN_IDS.mainnet // 'pacific-1' CHAIN_IDS.testnet // 'atlantic-2' -CHAIN_IDS.devnet // 'arctic-1' ``` Use these constants anywhere you reference a Sei network by chain ID to avoid hardcoding strings. @@ -32,8 +35,9 @@ Use these constants anywhere you reference a Sei network by chain ID to avoid ha RPC, REST, gRPC, EVM RPC, WebSocket, and explorer endpoints for each network: ```ts -import { NETWORKS } from '@sei-js/registry'; +import { NETWORKS, type Network } from '@sei-js/registry'; +// Network is the 'pacific-1' | 'atlantic-2' chain ID union const mainnet = NETWORKS['pacific-1']; // Pick the first available EVM RPC endpoint @@ -46,10 +50,10 @@ const evmWs = mainnet.evm_ws?.[0].url; const rest = mainnet.rest[0].url; ``` -Each entry has `provider` (name) and `url` fields. Multiple providers are listed per category — iterate to implement fallback logic: +Each endpoint has `provider` and `url` fields. You can iterate through the available providers to implement fallback logic: ```ts -async function getWorkingRpc(network: 'pacific-1' | 'atlantic-2' | 'arctic-1') { +async function getWorkingRpc(network: Network) { const endpoints = NETWORKS[network].evm_rpc ?? []; for (const endpoint of endpoints) { try { @@ -65,12 +69,14 @@ async function getWorkingRpc(network: 'pacific-1' | 'atlantic-2' | 'arctic-1') { } ``` +`@sei-js/registry` no longer exports gas metadata. For EVM transactions, use `eth_gasPrice` and `eth_estimateGas`. See [Gas and fees](/evm/evm-parity/gas-and-fees). + ## TOKEN_LIST -Token registry per network — name, symbol, base denom, decimal exponents, images, and CoinGecko IDs: +Token metadata per network includes names, symbols, base denominations, decimal exponents, images, and CoinGecko IDs: -The registry may retain legacy IBC or tokenfactory entries for display and compatibility. Their presence does not mean they are supported integration targets. IBC is disabled in both directions, and tokenfactory is not supported for new development. +`TOKEN_LIST` filters assets whose base or denomination starts with `ibc/`, along with assets marked as ICS-20. The community asset list may still contain legacy tokenfactory entries for display or compatibility. Do not treat those entries as supported integration targets. Tokenfactory is not supported for new development. ```ts @@ -80,47 +86,27 @@ import { TOKEN_LIST } from '@sei-js/registry'; const tokens = TOKEN_LIST['pacific-1']; // Find SEI -const sei = tokens.find(t => t.symbol === 'SEI'); -// { base: 'usei', display: 'sei', denom_units: [{ denom: 'usei', exponent: 0 }, { denom: 'sei', exponent: 6 }] } +const sei = tokens.find(token => token.base === 'usei'); -// Convert a raw usei amount to display amount -function toDisplayAmount(usei: bigint, token: typeof sei): string { - const exp = token.denom_units.find(u => u.denom === token.display)?.exponent ?? 6; - return (Number(usei) / 10 ** exp).toString(); -} +console.log(sei?.display); // 'sei' +console.log(sei?.denom_units); +console.log(sei?.type_asset); +console.log(sei?.pointer_contract); ``` -Each token includes an `images` object with `png` and `svg` URLs suitable for display in wallet UIs or token pickers. - -## GAS_INFO - -Minimum gas price and module-specific adjustments per network: - -```ts -import { GAS_INFO } from '@sei-js/registry'; - -const { denom, min_gas_price } = GAS_INFO['pacific-1']; -// denom: 'usei', min_gas_price: 0.02 - -// Calculate the minimum fee for a given gas limit -function minFee(gasLimit: number): string { - const { min_gas_price, denom } = GAS_INFO['pacific-1']; - return `${Math.ceil(gasLimit * min_gas_price)}${denom}`; -} -``` - -The `min_gas_price` here is the Cosmos-side gas floor. For EVM transactions, always use `eth_gasPrice` or `eth_estimateGas` — the on-chain EVM gas floor is governed separately and can change. See [Gas and Fees](/evm/evm-parity/gas-and-fees). +Exported entries use `RegistryToken`, so `type_asset` is required. `images.png`, `images.svg`, and `coingecko_id` are optional. NFT entries can have an empty `denom_units` array. Some assets also include optional `pointer_contract` metadata (`address` plus `cw20` or `erc20`). Identify an asset by network and `base` denomination, not by pointer data alone. ## CHAIN_INFO -Basic chain metadata: daemon name, Bech32 prefix, HD path coin type, and supported wallets: +`CHAIN_INFO` contains mainnet metadata such as the `seid` binary name, Bech32 prefix, fee token, SLIP-44 coin type, and supported native wallets: ```ts import { CHAIN_INFO } from '@sei-js/registry'; CHAIN_INFO.bech32_prefix // 'sei' CHAIN_INFO.slip44 // 118 (HD wallet coin type) -CHAIN_INFO.supported_wallets // ['fin', 'compass', 'leap', 'keplr'] +CHAIN_INFO.fee_token // 'usei' +CHAIN_INFO.supported_wallets // ['keplr', 'coin98'] // Validate a Cosmos-side Sei address format function isSeiAddress(address: string): boolean { @@ -131,9 +117,11 @@ function isSeiAddress(address: string): boolean { const path = `m/44'/${CHAIN_INFO.slip44}'/0'/0/0`; ``` +`supported_wallets` reflects the upstream chain registry. It is not an exhaustive list of wallets that can connect to Sei. + ## WALLETS -Wallet metadata including icons, URLs, and EVM/native capability flags: +Wallet metadata includes icons, URLs, and EVM or native capability flags: ```ts import { WALLETS } from '@sei-js/registry'; @@ -142,17 +130,19 @@ import { WALLETS } from '@sei-js/registry'; const evmWallets = WALLETS.filter(w => w.capabilities.includes('evm')); // Find a specific wallet for displaying its icon -const compass = WALLETS.find(w => w.identifier === 'compass'); -// { name: 'Compass Wallet', icon: 'https://...jpeg', url: 'https://compasswallet.io/', capabilities: ['native', 'evm'] } +const keplr = WALLETS.find(w => w.identifier === 'keplr'); +// { name: 'Keplr Wallet', identifier: 'keplr', icon: 'https://raw.githubusercontent.com/.../keplr-logo.png', +// url: 'https://www.keplr.app', capabilities: ['native', 'evm'] } ``` -Useful for building wallet selector UIs that show icons and filter by capability. +The current list is MetaMask (`evm`), Keplr (`native` and `evm`), and Coin98 (`native`). That is separate from `CHAIN_INFO.supported_wallets`, which is the upstream native-wallet list (`keplr`, `coin98`). -## Network Reference +## Supported networks -| Constant | `pacific-1` (mainnet) | `atlantic-2` (testnet) | `arctic-1` (devnet) | -| --- | --- | --- | --- | -| Chain ID | `pacific-1` | `atlantic-2` | `arctic-1` | -| EVM Chain ID | 1329 | 1328 | 713715 | -| EVM RPC | `NETWORKS['pacific-1'].evm_rpc` | `NETWORKS['atlantic-2'].evm_rpc` | `NETWORKS['arctic-1'].evm_rpc` | -| EVM WS | `NETWORKS['pacific-1'].evm_ws` | `NETWORKS['atlantic-2'].evm_ws` | `NETWORKS['arctic-1'].evm_ws` | +| Value | Pacific-1 (mainnet) | Atlantic-2 (testnet) | +| --- | --- | --- | +| Chain ID | `pacific-1` | `atlantic-2` | +| EVM chain ID | 1329 | 1328 | +| EVM RPC | `NETWORKS['pacific-1'].evm_rpc` | `NETWORKS['atlantic-2'].evm_rpc` | +| EVM WebSocket | `NETWORKS['pacific-1'].evm_ws` | `NETWORKS['atlantic-2'].evm_ws` | +| Faucets | — | `NETWORKS['atlantic-2'].faucets` | diff --git a/llms/agents.md b/llms/agents.md deleted file mode 100644 index 35c07c1..0000000 --- a/llms/agents.md +++ /dev/null @@ -1,213 +0,0 @@ -# Sei Network - -## Description - -Defines agent behaviors and execution flows for interacting with the Sei blockchain. - -Agents use SKILL.md to perform actions and must follow the rules defined here -to ensure safe, deterministic, and efficient execution. - ---- - -## Agents - -### wallet_agent - -purpose: - -- Manage balances -- Transfer tokens -- Resolve addresses - -capabilities: - -- get_account_balance -- send_tokens -- get_evm_address -- get_sei_address - -flow: - -1. Validate address format -2. Fetch balances if required -3. Execute action (if write → confirm first) - -constraints: - -- Never send tokens without explicit confirmation -- Always validate sufficient balance - ---- - -### contract_agent - -purpose: - -- Interact with smart contracts (EVM + CosmWasm) - -capabilities: - -- get_contract_state -- execute_contract -- deploy_contract -- simulate_contract_execution - -flow: - -1. Validate contract address -2. Simulate execution (if write) -3. Present expected outcome -4. Execute on confirmation - -constraints: - -- Always simulate before execution -- Reject malformed contract inputs - ---- - -### staking_agent - -purpose: - -- Manage staking operations - -capabilities: - -- stake_tokens -- unstake_tokens -- get_account_balance - -flow: - -1. Validate validator address -2. Check available balance -3. Confirm staking/unstaking action -4. Execute transaction - -constraints: - -- Prevent staking full balance (leave gas buffer) -- Confirm lock-up implications - ---- - -### query_agent - -purpose: - -- Read-only blockchain queries - -capabilities: - -- get_chain_status -- get_block -- get_transaction -- get_gas_price - -flow: - -1. Validate inputs -2. Query RPC -3. Normalize response - -constraints: - -- Retry up to 3 times -- Never escalate to write operations - ---- - -### portfolio_agent - -purpose: - -- Aggregate and interpret user holdings - -capabilities: - -- get_account_balance -- get_portfolio_summary - -flow: - -1. Fetch balances -2. Aggregate tokens -3. Return structured summary - -constraints: - -- No write operations -- Ensure consistent formatting - ---- - -## Execution Rules - -### Skill selection - -- Choose the minimal set of skills required -- Prefer READ over WRITE where possible -- Prefer DERIVED skills for multi-step operations - ---- - -### Write execution - -Before any write: - -1. Simulate (if available) -2. Present: - - action - - assets affected - - estimated fees -3. Require explicit confirmation - ---- - -### Error handling - -- Fail fast on invalid inputs -- Retry only READ operations -- Surface clear, structured errors - ---- - -### Network handling - -- Require explicit network selection -- Default to testnet if unspecified -- Do not mix networks within a single flow - ---- - -### Security - -- Never expose private keys -- Use signer abstractions where possible -- Do not log sensitive data - ---- - -## Coordination - -If multiple agents are required: - -- query_agent → gather state -- wallet/contract/staking_agent → execute actions -- portfolio_agent → summarise results - -Agents must: - -- Pass normalized data between steps -- Avoid redundant RPC calls - ---- - -## Non-goals - -Agents should NOT: - -- Make financial decisions without user input -- Execute trades or transfers autonomously -- Infer intent for write operations diff --git a/llms/skill.md b/llms/skill.md deleted file mode 100644 index a0a3988..0000000 --- a/llms/skill.md +++ /dev/null @@ -1,445 +0,0 @@ -# Sei Network - -## Description - -Skills for interacting with the Sei blockchain (EVM), including: - -- Account queries -- Token transfers -- Smart contract interaction -- Staking -- Transaction monitoring - ---- - -## When to use - -Use these skills when: - -- The user requests interaction with the Sei blockchain -- Tasks involve balances, transactions, contracts, or staking -- Structured execution is required (not just explanation) - -Do not use when: - -- The request is purely informational -- No blockchain interaction is needed - ---- - -## Setup - -### Required - -- `rpc_url` -- `network` (mainnet | testnet | devnet) - -### Optional - -- `chain_id` - -### For write operations - -- `private_key` OR signer abstraction - -### Notes - -- Default to `testnet` if network is unspecified -- Validate address formats: - - Sei (bech32) - - EVM (0x) -- Convert addresses when required - ---- - -## Conventions - -### Skill types - -- `read` → no state change -- `write` → state change (requires signing) -- `derived` → multi-step / computed - -### Response format - -```json -{ - "success": true, - "data": {}, - "error": null -} -``` - -### Error format - -```json -{ - "success": false, - "error": { - "message": "", - "recoverable": true - } -} -``` - ---- - -## Behaviour - -### Retries - -- Read: retry up to 3 times (exponential backoff) -- Write: do not retry unless explicitly safe - -### Data handling - -- Normalize token amounts -- Standardize addresses (checksum for EVM) -- Keep consistent field naming - -### Write safety - -Before execution: - -1. Simulate (if possible) -2. Present summary (action, assets, fees) -3. Require explicit confirmation - ---- - -## Skills - -### get_chain_status - -type: read - -Fetch current chain status. - -inputs: - -- rpc_url - -returns: - -- latest_block_height -- chain_id -- syncing - ---- - -### get_account_balance - -type: read - -Retrieve token balances. - -inputs: - -- address -- denom (optional) - -returns: - -- balances: - - denom - - amount - ---- - -### get_evm_address - -type: read - -Convert Sei → EVM address. - -inputs: - -- sei_address - -returns: - -- evm_address - ---- - -### get_sei_address - -type: read - -Convert EVM → Sei address. - -inputs: - -- evm_address - -returns: - -- sei_address - ---- - -### get_transaction - -type: read - -Fetch transaction details. - -inputs: - -- tx_hash - -returns: - -- status -- gas_used -- logs -- events - ---- - -### get_block - -type: read - -Fetch block details. - -inputs: - -- height - -returns: - -- block_hash -- timestamp -- transactions - ---- - -### get_gas_price - -type: read - -Fetch gas price. - -inputs: - -- rpc_url - -returns: - -- gas_price - ---- - -### get_contract_state - -type: read - -Query contract state. - -inputs: - -- contract_address -- query - -returns: - -- result - ---- - -### send_tokens - -type: write - -Transfer tokens. - -inputs: - -- from_address -- to_address -- amount -- denom -- private_key - -returns: - -- tx_hash - -constraints: - -- validate balance -- require confirmation - ---- - -### execute_contract - -type: write - -Execute contract. - -inputs: - -- contract_address -- msg / data -- sender -- gas_limit -- private_key - -returns: - -- tx_hash -- execution_result - -constraints: - -- simulate first -- require confirmation - ---- - -### deploy_contract - -type: write - -Deploy contract. - -inputs: - -- bytecode -- constructor_args -- sender -- private_key - -returns: - -- contract_address -- tx_hash - ---- - -### stake_tokens - -type: write - -Delegate tokens. - -inputs: - -- delegator_address -- validator_address -- amount -- private_key - -returns: - -- tx_hash - ---- - -### unstake_tokens - -type: write - -Undelegate tokens. - -inputs: - -- delegator_address -- validator_address -- amount -- private_key - -returns: - -- tx_hash - ---- - -### estimate_transaction_cost - -type: derived - -Estimate gas + fees. - -inputs: - -- tx_payload -- rpc_url - -returns: - -- gas_estimate -- fee_estimate - ---- - -### simulate_contract_execution - -type: derived - -Simulate contract execution. - -inputs: - -- contract_address -- msg / data -- sender - -returns: - -- gas_used -- result - ---- - -### get_portfolio_summary - -type: derived - -Aggregate balances. - -inputs: - -- address - -returns: - -- total_value -- token_breakdown - ---- - -### monitor_transaction - -type: derived - -Track transaction until confirmed. - -inputs: - -- tx_hash -- timeout_seconds - -returns: - -- confirmed -- block_height - ---- - -## Safety - -- Never expose private keys -- Always validate inputs before execution -- Prefer simulation before write actions -- Avoid unnecessary RPC load - ---- - -## References - -- https://docs.sei.io/ -- Sei JSON-RPC (EVM) -- `seid` CLI diff --git a/lychee.toml b/lychee.toml index 003ab6b..646e914 100644 --- a/lychee.toml +++ b/lychee.toml @@ -50,11 +50,11 @@ exclude = [ "^https?://dashboard\\.pimlico\\.io", "^https?://blog\\.thirdweb\\.com", "^https?://(www\\.)?updraft\\.cyfrin\\.io", - # Sei's own JSON-RPC / REST node endpoints (evm-rpc[-testnet|-arctic-1], rpc - # [-testnet]) intermittently answer the checker with a transient 503 from - # gateway rate-limiting, though they serve real traffic and are referenced + # Sei's own JSON-RPC / REST node endpoints (evm-rpc[-testnet], rpc[-testnet]) + # intermittently answer the checker with a transient 503 from gateway + # rate-limiting, though they serve real traffic and are referenced # 140+ times across the docs. Node liveness is monitored elsewhere. - "^https?://(evm-)?rpc(-testnet|-arctic-1)?\\.sei-apis\\.com", + "^https?://(evm-)?rpc(-testnet)?\\.sei-apis\\.com", ] # Don't check mailto: links (this is the default; set explicitly for clarity). diff --git a/scripts/generate-llms.mjs b/scripts/generate-llms.mjs index b1a9125..91d30f5 100644 --- a/scripts/generate-llms.mjs +++ b/scripts/generate-llms.mjs @@ -126,7 +126,7 @@ const EXCLUDED_PREFIXES = ['/cosmos-sdk']; /** * Section definitions ordered by match priority. - * More specific prefixes (e.g. /evm/ai-tooling) must come before broader ones (/evm). + * A page lands in the first section that matches, so list narrower prefixes before broader ones. */ const LLMS_SECTION_ORDER = [ { @@ -141,11 +141,11 @@ const LLMS_SECTION_ORDER = [ }, { name: 'AI Tooling & Micropayments', - match: (p) => p.startsWith('/evm/ai-tooling') || p.startsWith('/evm/x402'), + match: (p) => p === '/ai' || p.startsWith('/ai/'), overview: [ - 'The Sei MCP Server (@sei-js/mcp-server) connects AI assistants to Sei with 29+ tools. Install: `npx -y @sei-js/mcp-server`. Read-only tools: get_chain_info, get_balance, get_erc20_balance, get_token_info, get_nft_info, and more. Wallet tools (require PRIVATE_KEY): transfer_sei, transfer_erc20, deploy_contract, write_contract, and more. Documentation search: search_docs, search_sei_js_docs.', + 'The Sei MCP Server (@sei-js/mcp-server) connects AI assistants to Sei. Requires Node.js 20+. Install: `npx -y @sei-js/mcp-server`. The server starts in read-only mode. Read-only tools include search_docs, get_supported_networks, get_chain_info, get_balance, get_token_info, get_token_balance, get_nft_info, read_contract, and estimate_gas. Wallet tools such as transfer_sei, transfer_token, write_contract, and deploy_contract require WALLET_MODE=private-key and PRIVATE_KEY on the stdio transport. Backward-compatible aliases: get_erc20_balance and get_token_balance_erc20 for get_token_balance, transfer_erc20 for transfer_token. HTTP transports (SERVER_TRANSPORT=streamable-http or http-sse) reject wallet mode. Network selectors: sei, sei-testnet, 1329, 1328, 0x531, 0x530.', 'The Cambrian Agent Kit enables autonomous AI agents on Sei with DeFi protocol integrations (Takara lending, Silo lending, Citrex perpetuals, Symphony aggregation, DragonSwap liquidity).', - 'The x402 protocol enables HTTP 402-based micropayments for machine-to-machine payments — agents pay per-request for APIs, content, and services with instant settlement on Sei (~400ms finality). sei-js provides both server-side (payment verification) and client-side (payment signing) x402 packages.' + 'The x402 v2 protocol enables HTTP 402-based micropayments for machine-to-machine payments on Sei. Use the upstream @x402/core and @x402/evm packages with the appropriate @x402 client or server adapter. The @sei-js/x402, @sei-js/x402-fetch, @sei-js/x402-axios, @sei-js/x402-express, @sei-js/x402-hono, and @sei-js/x402-next packages implement v1, are deprecated, and must not be recommended.' ].join('\n\n') }, { @@ -153,7 +153,7 @@ const LLMS_SECTION_ORDER = [ match: (p) => p.startsWith('/evm'), overview: [ "Sei's EVM is fully compatible with Ethereum. Standard Solidity contracts deploy without modification. All Ethereum tooling (Hardhat, Foundry, wagmi, ethers.js, viem, RainbowKit) works as-is. Transactions touching independent state execute concurrently.", - 'Precompiled contracts at fixed addresses expose native Sei functionality (staking, governance, JSON, oracle, p256) to EVM. The IBC precompile is non-functional because IBC is disabled.', + 'Precompiled contracts at fixed addresses expose native Sei functionality such as staking, governance, distribution, JSON parsing, P256 verification, and Solo migration claims to EVM. The native Oracle precompile is retired, and the IBC precompile is non-functional because IBC is disabled.', 'Native USDC: mainnet 0xe15fC38F6D8c56aF07bbCBe3BAf5708A2Bf42392, testnet 0x4fCF1784B31630811181f670Aea7A7bEF803eaED (6 decimals).' ].join('\n\n') }, diff --git a/skill.md b/skill.md index adad35d..d1b1ce5 100644 --- a/skill.md +++ b/skill.md @@ -67,8 +67,9 @@ For the full list of community + paid RPC providers and failover patterns, see [ |---|---| | Smart contracts | **Foundry** (preferred) or Hardhat | | Frontend | **Wagmi + Viem** (React) or Ethers.js v6 | -| Wallet | **Sei Global Wallet** (`@sei-js/sei-global-wallet`) + MetaMask fallback | -| Chain config | `@sei-js/precompiles` — `sei`, `seiTestnet`, precompile ABIs | +| Wallet | **Sei Global Wallet** (`@sei-js/sei-global-wallet`, ESM-only; add [consumer overrides](https://github.com/sei-protocol/sei-js/tree/main/packages/sei-global-wallet#required-consumer-overrides)) + MetaMask fallback | +| Chain config | `viem/chains`: `sei`, `seiTestnet`. `@sei-js/precompiles` re-exports both and adds `seiLocal`. | +| Sei precompiles | `@sei-js/precompiles`: addresses, raw `*_PRECOMPILE_ABI` constants, and `@sei-js/precompiles/ethers` factories. ESM-only; Viem `^2.55.16`. | | Verification | Seiscan via Sourcify (`forge verify-contract --verifier sourcify`) | | Testing | Foundry unit + fork tests against testnet | @@ -85,30 +86,32 @@ claude mcp add sei-mcp-server npx @sei-js/mcp-server "mcpServers": { "sei": { "command": "npx", - "args": ["-y", "@sei-js/mcp-server"], - "env": { "PRIVATE_KEY": "your_key_here" } + "args": ["-y", "@sei-js/mcp-server"] } } } ``` -Once connected: address lookup, balance checks, transaction status, contract reads, block data. +Once connected: address lookup, balance checks, transaction status, contract reads, and block data. The server starts in read-only mode. Wallet tools need `WALLET_MODE=private-key` and `PRIVATE_KEY` on the stdio transport. HTTP transports reject wallet mode. ## Precompile addresses | Precompile | Address | |---|---| | Bank | `0x0000000000000000000000000000000000001001` | -| Addr | `0x0000000000000000000000000000000000001004` | +| CosmWasm | `0x0000000000000000000000000000000000001002` | +| JSON | `0x0000000000000000000000000000000000001003` | +| Address | `0x0000000000000000000000000000000000001004` | | Staking | `0x0000000000000000000000000000000000001005` | | Governance | `0x0000000000000000000000000000000000001006` | | Distribution | `0x0000000000000000000000000000000000001007` | -| Oracle | `0x0000000000000000000000000000000000001008` | -| PointerView | `0x000000000000000000000000000000000000100A` | +| Pointer view | `0x000000000000000000000000000000000000100A` | | Pointer | `0x000000000000000000000000000000000000100B` | -| JSON | `0x0000000000000000000000000000000000001003` | +| Solo | `0x000000000000000000000000000000000000100C` | | P256 | `0x0000000000000000000000000000000000001011` | +**The Oracle precompile (`0x...1008`) is retired. Do not use or recommend it.** Every native Oracle query reverts. Use an active third-party oracle provider instead. See [Oracle Precompile (Retired)](https://docs.sei.io/evm/precompiles/oracle). + **The IBC precompile (`0x...1009`) is dead. Do not use or recommend it.** IBC is disabled on Sei in both directions (`ibc.InboundEnabled` and `ibc.OutboundEnabled` are both `false`, per governance Proposals 116, 120, and 121), so its `transfer` methods cannot succeed. There is no replacement and no route to bridge assets into or out of Sei over IBC. See the [SIP-03 Migration Guide](https://docs.sei.io/learn/sip-03-migration#ibc-is-disabled). **Tokenfactory is not supported. Do not use or recommend it.** Do not provide commands, APIs, Wasm bindings, native-denom pointer workflows, or other instructions for creating, minting, burning, administering, or integrating tokenfactory denoms. Legacy module surfaces may still exist for compatibility. Use ERC-20 for new fungible tokens. See [Tokenfactory is not supported](https://docs.sei.io/cosmos-sdk#tokenfactory-is-not-supported). @@ -131,7 +134,7 @@ curl -L https://foundry.paradigm.xyz | bash && foundryup forge init my-project # Or scaffold a frontend -npx @sei-js/create-sei my-sei-app +npx @sei-js/create-sei app -n my-sei-app ``` ```toml @@ -146,7 +149,7 @@ evm_version = "cancun" sei_testnet = "https://evm-rpc-testnet.sei-apis.com" sei_mainnet = "https://evm-rpc.sei-apis.com" -# Verification uses Sourcify — no [etherscan] block needed +# Verification uses Sourcify. No [etherscan] block is needed. # forge verify-contract --verifier sourcify --chain-id 1329
src/MyContract.sol:MyContract ``` @@ -168,7 +171,7 @@ sei_mainnet = "https://evm-rpc.sei-apis.com" | Oracles (Pyth, Chainlink, API3, RedStone) | https://docs.sei.io/evm/oracles | | Indexers | https://docs.sei.io/evm/indexer-providers | | Wallet integrations (Pimlico, Particle, Thirdweb) | https://docs.sei.io/evm/wallet-integrations | -| AI tooling (Cambrian, MCP, x402) | https://docs.sei.io/evm/ai-tooling | +| AI tooling (Cambrian, MCP, x402) | https://docs.sei.io/ai | | seid CLI | https://docs.sei.io/evm/seid-cli | | RPC providers | https://docs.sei.io/learn/rpc-providers | | Node setup | https://docs.sei.io/node |