Quickstart

Connect an AI app to the remote server in a minute. Use the desktop agent if your AI app runs local programs on a Mac and you want small payments to go through without a tap.

What you need

• The OpenWallet extension with a wallet created in it (or imported from recovery words). Wallets imported from a family seed cannot make agent wallets.
• An AI app that supports MCP.

Remote: connect an AI app

1. In your AI app, add a remote MCP server (often under connectors or integrations) with this URL:

   https://mcp.opensync.network/mcp

2. The app discovers the server's OAuth metadata and opens its authorise page. The page shows the app's declared name, the scopes (pay within limits; read balance and history) and a connection code such as KJ7M-2QXP.
3. In the extension: Agents → Approve a connection. Type or match the code, choose the agent wallet this app may use and its limits, and approve with Touch ID or the password.
4. The authorise page completes the OAuth code flow and the app is connected. Access tokens last 1 hour; refresh tokens rotate and last 30 days.

The authorise page never asks for an email code, an authenticator code, a recovery code or a password. The connection code expires after 10 minutes and works once.

A first paid request

Ask the agent for something behind an x402 paywall, such as "Get the report at https://api.example.com/v1/report". It calls:

// tools/call → openwallet_pay_x402
{ "url": "https://api.example.com/v1/report" }

// If the user has not approved within 60 s:
// → { "status": "pending", "request_id": "…" }

// tools/call → openwallet_payment_status
{ "request_id": "…" }
// → { "status": "approved", "http": { … }, "receipt": { … } }

The user sees the request in the extension (with a system notification), approves it, and the result comes back to the waiting call or to the next status check. The model should poll with openwallet_payment_status, not repeat the payment.

Desktop: OpenWallet Agent on a Mac

The desktop agent is a local MCP server. Always pin a version.

claude mcp add openwallet -- npx -y @openwallet/agent@1.0.0 mcp

{
  "mcpServers": {
    "openwallet": {
      "command": "npx",
      "args": [
        "-y",
        "@openwallet/agent@1.0.0",
        "mcp"
      ]
    }
  }
}

{
  "mcpServers": {
    "openwallet": {
      "command": "npx",
      "args": [
        "-y",
        "@openwallet/agent@1.0.0",
        "mcp"
      ]
    }
  }
}

code --add-mcp '{"name":"openwallet","command":"npx","args":["-y","@openwallet/agent@1.0.0","mcp"]}'

In .vscode/mcp.json the key is servers, not mcpServers. Codex, Gemini CLI, Windsurf, Zed and custom agents take the same stdio command, npx -y @openwallet/agent@1.0.0 mcp, in their mcpServers-style configuration. The agent also ships as a Homebrew cask (openwallet-agent) and a notarised disk image.

The npm launcher has no install scripts. Before it starts the program, it checks the app's code signature against the pinned publisher.

Pair it with your wallet

# In a terminal, not in the chat.
openwallet-agent pair --network mainnet --label "Claude Code on MacBook"

1. The program prints a pair request (owpair1.…) and five words.
2. In the extension: Agents → Add agent. Paste the request and check that the five words match.
3. Set the limits and the budget. The extension creates and funds the agent wallet and gives the agent's key permission to spend from it.
4. The extension shows a grant token (owgrant1.…) and a second set of words. Paste the token at the program's prompt and compare the words.

The MCP tools never show pairing material, because a model could rewrite a token and its words together. Clients that auto-approve tool calls do not weaken payments: approvals happen in the agent, not in the client.