Merge branch 'main' into humanagent/feature-20251018-122308

humanagent · web-flow · commit 96ecc5cc6035 · 2025-10-27T20:19:40.000-03:00
diff --git a/docs/pages/*.mdx b/docs/pages/*.mdx
@@ -0,0 +1,9 @@
+# Page not found
+
+This page may have been moved, renamed, or removed. Our docs are actively maintained, so URLs occasionally change.
+
+Please use the search field or links in the header to find what you need.
+
+To request help or report a bug, please [open an issue](https://github.com/xmtp/docs-xmtp-org/issues).
+
+We know how important it is to have reliable documentation and we appreciate your patience.
diff --git a/docs/pages/agents/build-agents/groups.mdx b/docs/pages/agents/build-agents/groups.mdx
@@ -34,26 +34,42 @@ To learn more, see the [Gated group example](https://github.com/ephemeraHQ/xmtp-
 
 The maximum group chat size is 250 members.
 
+### Add members
+
+You can add members directly by their Ethereum addresses or by their inbox IDs
+
 ```js [Node]
-// Get inbox IDs for identities
-const inboxId = await client.getInboxIdByIdentities([
-  bo.identity,
-  caro.identity,
-]);
+// Add members by Ethereum address
+await ctx.addMembersWithAddresses(group, [ address1, address2 ]);
 
-// Add/remove members
+
+// Add members using inbox IDs
 await group.addMembers([inboxId]);
+```
+
+### Remove members
+
+Remove members from the group by their Ethereum addresses or by their inbox IDs:
+
+```js [Node]
+// Remove members by address
+//needs to send the group to the context
+await ctx.removeMembersWithAddresses(group, [ address1, address2 ]);
+
+// Remove members by inbox ID
 await group.removeMembers([inboxId]);
+```
 
-// Get member information
+### Get member information
+
+Retrieve and work with member data:
+
+```js [Node]
+// Sync group data to get latest member information
 await group.sync();
-const members = group.members;
-const addedByInboxId = group.addedByInboxId;
 
-// Map inbox ID to account identity
-const inboxIdIdentityMap = new Map(
-  members.map((member) => [member.inboxId, member.accountIdentity])
-);
+// Get all members
+const members = await group.members();
 ```
 
 ## Manage group chat admins
@@ -74,7 +90,7 @@ await group.removeAdmin(inboxId);
 await group.removeSuperAdmin(inboxId);
 ```
 
-## Member information
+## Example usage
 
 Get detailed information about group members:
 
diff --git a/docs/pages/agents/build-agents/local-database.mdx b/docs/pages/agents/build-agents/local-database.mdx
@@ -2,6 +2,12 @@
 
 Each XMTP agent installation maintains its own local database containing message history, conversation state, and cryptographic material. When you delete this database (or use an in-memory database), you create a new installation that counts toward your [installation limits](/chat-apps/core-messaging/manage-inboxes#inbox-update-and-installation-limits).
 
+:::danger[CRITICAL FOR PRODUCTION]
+
+Each time you run your agent, XMTP creates local database files that must be **kept between restarts and between deployments**. Without persistent volumes, each restart creates a new installation and you're **limited to 10 installations per inbox**.
+
+:::
+
 ## Installation limits and revocation rules
 
 Understanding XMTP's installation and inbox limits is critical for production deployments:
@@ -12,6 +18,7 @@ Understanding XMTP's installation and inbox limits is critical for production de
 
 These limits protect inbox integrity and prevent unbounded key state growth across devices. For production environments, always use persistent volumes to back up and preserve your database across agent restarts.
 
+
 ## Understand local database files
 
 The Agent SDK creates database files in the `dbPath` directory (default is `'/'`). These files store your agent's identity and message history.
@@ -30,22 +37,6 @@ xmtp-production-62ff7c82fa2e8c9a0a0c9e58e7247704d102c41e5ceb4dc3573792d7d7a1c688
 - `62ff7c82fa2e8c9a0a0c9e58e7247704d102c41e5ceb4dc3573792d7d7a1c688`: Inbox ID (Your xmtp identity)
 - `.db3`: SQLite database file extension
 
-**Keep these files between deployments:**
-
-- Deleting them creates a new installation each time
-- Reusing them maintains the same installation
-- Each inbox can have up to 10 installations
-
-**For production deployments:**
-
-- Use persistent volumes (Railway volumes, Render disks, etc.)
-- The database needs to persist across restarts
-
-:::warning[Note]
-
-If you hit the 10 installation limit, use [this script](https://github.com/ephemeraHQ/xmtp-agent-examples?tab=readme-ov-file#revoke-installations) to revoke installations.
-
-:::
 
 ## Understand installations
 
@@ -89,45 +80,18 @@ If you deploy your agent to this same network environment, you have 1 inbox with
   />
 </div>
 
-Here are some best practices for agent installation management:
-
-- Configure your deployments to preserve the agent's database
-- Consider how many platforms you'll need before hitting the 10 installation limit
-- Keep track of which installation corresponds to which platform
-- Regularly [check how many installations your agent has](/agents/deploy/debug-agents)
-- [Revoke installations](#revoke-agent-installations) from platforms you no longer use
-
-## Common agent installation scenarios
-
-### Deploy to a new platform
-
-When you deploy your agent to a new platform (e.g., from Railway to Fly.io):
-
-- Your agent creates a new installation for the new platform
-- If you already have 10 installations, you'll need to [revoke one first](#revoke-agent-installations)
-- The new installation will start fresh without conversation history
-
-### Update an existing deployment
-
-When you redeploy your agent to the same platform:
-
-- If the platform preserves the database, the same installation continues working
-- If the platform doesn't preserve the database, a new installation is created
-
 ## Revoke agent installations
 
-:::warning[Important]
+When you revoke an agent installation, it can no longer send or receive messages. However, you can still access the local database. Your agent can still run from any active installations on other deployment platforms.
 
+:::danger[Important]
 Revoking an installation is permanent. You cannot recover access to a revoked installation.
-
 :::
 
-When you revoke an agent installation, it can no longer send or receive messages. However, you can still access the local database.
+1. Web tool: [xmtp.chat/inbox-tools](https://xmtp.chat/inbox-tools)
+2. CLI script: [revokeInstallations.ts](https://github.com/ephemeraHQ/xmtp-agent-examples/blob/eb1dc17e99570b77de906ba0d58094586a4af844/scripts/revokeInstallations.ts) in the xmtp-agent-examples repo
 
-Your agent can still run from any active installations on other deployment platforms.
+  ```bash
+  yarn revoke <inbox-id> <installations-to-exclude>
+  ```
 
-To revoke an agent installation, use [revokeInstallations.ts](https://github.com/ephemeraHQ/xmtp-agent-examples/blob/eb1dc17e99570b77de906ba0d58094586a4af844/scripts/revokeInstallations.ts) in the xmtp-agent-examples repo. For example:
-
-```bash
-yarn revoke <inbox-id> <installations-to-exclude>
-```
diff --git a/docs/pages/agents/concepts/context.mdx b/docs/pages/agents/concepts/context.mdx
@@ -73,6 +73,15 @@ agent.on('text', async (ctx) => {
 });
 ```
 
+### Get inbox ID by identifier
+
+```typescript
+const inboxId = await ctx.client.getInboxIdByIdentifier({
+  identifier: targetAddress,
+  identifierKind: IdentifierKind.Ethereum,
+});
+```
+
 ### getSenderAddress()
 
 Get the Ethereum address of the message sender:
diff --git a/docs/pages/agents/get-started/build-an-agent.mdx b/docs/pages/agents/get-started/build-an-agent.mdx
@@ -60,9 +60,11 @@ await agent.start();
 
 Each time you run your agent, XMTP creates local database files that must be **kept between restarts and between deployments**. Without persistent volumes, each restart creates a new installation and you're **limited to 10 installations per inbox**.
 
+To learn more, see [Manage agent local database files and installations](/agents/build-agents/local-database).
+
 :::
 
-XMTP creates local database files in the `dbPath` (default is `'/'`) directory. These files store your device identity and message history. To learn more, see [Manage agent local database files and installations](/agents/build-agents/local-database).
+XMTP creates local database files in the `dbPath` (default is `'/'`) directory. These files store your device identity and message history. 
 
 ### Set environment variables
 
diff --git a/docs/pages/agents/get-started/faq.mdx b/docs/pages/agents/get-started/faq.mdx
@@ -96,6 +96,47 @@ Yes, messages are limited to just under 1MB. For larger content, use [remote att
 
 No messaging fees currently. Messages are stored off-chain on the XMTP network.
 
+
+## Domains
+
+### How do I register a domain for my agent?
+
+#### 1. Register a new ENS domain
+
+1. Go to https://app.ens.domains/
+2. Search for your desired name (e.g., "myagent.eth")
+3. If available, click "Request to register" → Complete registration (requires ETH for registration + gas fees)
+4. Wait ~1 minute for registration to complete
+
+#### 2. Create agent wallet in MetaMask
+
+1. Open MetaMask → Account selector → "Add account or hardware wallet" → "Add a new account"
+2. Name it (e.g., "Agent Wallet") → Create
+3. Click three dots → "Account details" → "Show private key" → enter password → **copy and save private key**
+4. Copy the wallet address
+
+#### 3. Link ENS domain to agent wallet
+
+1. Go to https://app.ens.domains/yourdomain.eth
+2. Click "Edit profile" → Under "ETH Address" → paste agent wallet address → Save
+3. Sign the transaction
+
+#### 4. Set as primary name
+
+1. Switch MetaMask to the agent wallet account
+2. Go to https://app.ens.domains/
+3. Click "My account" → Find your domain → Click "Set as primary name"
+4. Sign the transaction
+
+#### 5. Transfer ownership (optional)
+
+1. Switch back to owner account in MetaMask
+2. On the ENS page, click "Transfer" → paste agent address → sign transaction
+3. Agent now owns the domain (can update records using private key)
+
+**Result**: Your agent can now use the private key to control the wallet/domain, reverse resolution works (address → name), and people can send funds to yourdomain.eth
+
+
 ## Framework integration
 
 ### Does XMTP work with ElizaOS?
diff --git a/docs/pages/fund-agents-apps/calculate-fees.mdx b/docs/pages/fund-agents-apps/calculate-fees.mdx
@@ -43,7 +43,7 @@ Use this guide to understand XMTP fees and how to calculate estimated XMTP fees
 
 ## Understand XMTP fees
 
-To support a decentralized and sustainable network, XMTP operates on a usage-based fee model. The fees paid by apps and agents (payers) directly compensate the independent node operators who run the infrastructure, ensuring the network remains resilient, secure, and censorship-resistant.
+To support a decentralized and sustainable network, XMTP operates on a usage-based fee model. **All XMTP network fees are paid in USDC** (USD Coin, a stablecoin pegged to the US dollar). The fees paid by apps and agents (payers) directly compensate the independent node operators who run the infrastructure, ensuring the network remains resilient, secure, and censorship-resistant.
 
 :::tip[How to estimate your costs]
 
@@ -70,7 +70,7 @@ Messages sent through the **XMTP Broadcast Network** incur these types of **mess
 - **Storage fee**: A fee charged per-byte-day of storage required.
 - **Congestion fee**: A dynamic fee computed by looking at the recent activity of an originator. Added only during periods of high network activity.
 
-The fee rates for the base fee, storage fee, and congestion fee are denominated in dollars and stored as constants in a smart contract. These rates are set and adjusted through protocol governance and remain constant for a specified period of time.
+The fee rates for the base fee, storage fee, and congestion fee are denominated in USDC and stored as constants in a smart contract. These rates are set and adjusted through protocol governance and remain constant for a specified period of time.
 
 Every message an app or agent sends through the XMTP Broadcast Network counts against its message allowance. These message types include:
 
diff --git a/docs/pages/fund-agents-apps/run-gateway.mdx b/docs/pages/fund-agents-apps/run-gateway.mdx
@@ -159,10 +159,11 @@ You can provide the configuration options for your XMTP Gateway Service either d
 | Name                     | Required | Command line flag                      | Environment variable             | Info                                                                                                                                                                                                      |
 | ------------------------ | -------- | -------------------------------------- | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | Payer Private Key        | `true`   | `--payer.private-key`                  | `XMTPD_PAYER_PRIVATE_KEY`        | The `secp256k1` private key of the Ethereum Account you have already funded in the Funding Portal. Used to sign transactions and pay fees from your payer allowance in the Payer Registry smart contract. |
+| App Chain RPC URL        | `true`   | `--contracts.app-chain.rpc-url`        | `XMTPD_APP_CHAIN_RPC_URL`        | The RPC URL of your Blockchain RPC provider's endpoint for XMTP Chain                                                                                                                               |
+| Settlement Chain RPC URL | `true`   | `--contracts.settlement-chain.rpc-url` | `XMTPD_SETTLEMENT_CHAIN_RPC_URL` | The RPC URL of your Blockchain RPC provider's endpoint for the Base chain                                                                                                                           |
 | App Chain WSS URL        | `true`   | `--contracts.app-chain.wss-url`        | `XMTPD_APP_CHAIN_WSS_URL`        | The websocket URL of your Blockchain RPC provider's endpoint for XMTP Chain                                                                                                                               |
 | Settlement Chain WSS URL | `true`   | `--contracts.settlement-chain.wss-url` | `XMTPD_SETTLEMENT_CHAIN_WSS_URL` | The websocket URL of your Blockchain RPC provider's endpoint for the Base chain                                                                                                                           |
-| Environment              | `true`   | `--contracts.environment`              | `XMTPD_CONTRACTS_ENVIRONMENT`    | The environment your XMTP Gateway Service will run in. Valid values are `local`, `testnet`, and `mainnet`                                                                                                 |
-| Enable Redis             | `true`   | `--redis.enable`                       | `XMTPD_REDIS_ENABLE`             | Use Redis for nonce management and rate limiting.                                                                                                                                                         |
+| Environment              | `true`   | `--contracts.environment`              | `XMTPD_CONTRACTS_ENVIRONMENT`    | The environment your XMTP Gateway Service will run in. Valid values are `anvil`, `testnet`, and `mainnet`                                                                                                 |
 | Redis Connection String  | `false`  | `--redis.connection-string`            | `XMTPD_REDIS_CONNECTION_STRING`  | The connection string for your Redis instance                                                                                                                                                             |
 
 </div>
@@ -392,6 +393,48 @@ func main() {
 
 ```
 
+```go [Rate Limiting]
+package main
+
+import (
+	"context"
+	"log"
+	"time"
+
+	"github.com/xmtp/xmtpd/pkg/gateway"
+	"github.com/xmtp/xmtpd/pkg/gateway/authorizers"
+)
+
+func main() {
+	cfg := gateway.MustLoadConfig()
+	redis := gateway.MustSetupRedisClient(context.Background(), cfg.Redis)
+
+	authorizer := authorizers.NewRateLimitBuilder().
+		WithLogger(gateway.MustCreateLogger(cfg)).
+		WithRedis(redis).
+		// Set rate limits to 50 requests/minute and 250 requests/hour
+		WithLimits(authorizers.RateLimit{
+			Capacity:    50,
+			RefillEvery: time.Minute,
+		}, authorizers.RateLimit{
+			Capacity:    250,
+			RefillEvery: time.Hour,
+		}).
+		MustBuild()
+
+	gatewayService, err := gateway.NewGatewayServiceBuilder(cfg).
+		WithRedisClient(redis).
+		WithAuthorizers(authorizer).
+		Build()
+	if err != nil {
+		log.Fatalf("Failed to build gateway service: %v", err)
+	}
+
+	gatewayService.WaitForShutdown()
+}
+
+```
+
 :::
 
 ## Authorize requests
@@ -443,7 +486,7 @@ We provide a Docker image that corresponds to the bare bones example above that
 docker run -p 5050:5050 -p 5055:5055 -e XMTPD_PAYER_PRIVATE_KEY=... xmtp/xmtpd-gateway:main
 ```
 
-Most production apps will require some level of customization to authorize user requests. We provide a sample Dockerfile in the xmtpd [`dev/docker`](https://github.com/xmtp/xmtpd/blob/main/dev/docker/gateway.Dockerfile) directory that you can use as a starting point.
+Most production apps will require some level of customization to authorize user requests. You can fork our [example repository](https://github.com/xmtp/gateway-service-example), which includes a Dockerfile and a sample configuration.
 
 The system is able to run without any external dependencies, but we recommend configuring a Redis instance to use for nonce management and rate limiting.
 
diff --git a/llms/llms-full.txt b/llms/llms-full.txt
