home / skills / merit-systems / x402scan-skills / wallet

wallet skill

safe

This skill helps you manage x402 wallet for paid API calls by checking balance, redeeming invites, and obtaining USDC deposits.

npx playbooks add skill merit-systems/x402scan-skills --skill wallet

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

1.8 KB

---
name: wallet
description: |
  Manage x402 wallet for paid API calls. Check balance, redeem invite codes, deposit USDC.

  USE FOR:
  - Checking wallet balance before API calls
  - Redeeming invite codes for free credits
  - Getting deposit address for USDC
  - Troubleshooting payment failures

  TRIGGERS:
  - "balance", "wallet", "funds", "credits"
  - "redeem", "invite code", "promo code"
  - "deposit", "add funds", "top up"
  - "insufficient balance", "payment failed"
mcp:
  - x402
---

# x402 Wallet Management

Your wallet is auto-created on first use and stored at `~/.x402scan-mcp/wallet.json`.

## Quick Reference

| Task | Tool | Notes |
|------|------|-------|
| Check balance | `x402.get_wallet_info` | Shows address + USDC balance |
| Redeem code | `x402.redeem_invite(code="...")` | One-time use per code |
| Deposit | Send USDC to wallet address | Base network only |

## Check Balance

```mcp
x402.get_wallet_info
```

Returns:
- Wallet address (Base network)
- USDC balance
- Deposit link

Always check balance before expensive operations.

## Redeem Invite Code

```mcp
x402.redeem_invite(code="YOUR_CODE")
```

- One-time use per code
- Credits added instantly
- Run `x402.get_wallet_info` after to verify

## Deposit USDC

1. Get your wallet address: `x402.get_wallet_info`
2. Use it to add funds in the deposit UI (point the user towards this URL: https://x402scan.com/mcp/deposit/<their-wallet-address>)

**Important**: Only Base network USDC. Other networks or tokens will be lost.

## Troubleshooting

| Issue | Solution |
|-------|----------|
| "Insufficient balance" | Check balance, deposit or redeem code |
| "Payment failed" | Transient error, retry the request |
| "Invalid invite code" | Code already used or doesn't exist |
| Balance not updating | Wait for Base network confirmation (~2 sec) |

Overview

This skill manages an x402 wallet used for paid API calls. It lets you check USDC balance, redeem one-time invite codes for credits, and obtain the deposit address for adding funds on the Base network. Use it to avoid failed requests from insufficient funds and to troubleshoot basic payment issues.

How this skill works

The wallet is auto-created on first use and stored locally. The skill queries wallet info to return the Base network address, current USDC balance, and a deposit link. It can redeem invite codes once each to add credits instantly and provides guidance for depositing USDC to the wallet address.

When to use it

Before expensive API calls to verify sufficient USDC balance
When you have an invite or promo code to redeem for free credits
To get the Base network deposit address or deposit link for adding funds
If an API request fails due to 'insufficient balance' or 'payment failed'
When balance changes seem delayed and you need confirmation

Best practices

Always run a balance check (get_wallet_info) before initiating costly operations
Only deposit USDC on the Base network; other networks or tokens are irreversible
Redeem invite codes via redeem_invite and then recheck balance to confirm credit
If a payment fails, retry after confirming balance and waiting a few seconds for network confirmation
Store and back up your local wallet file securely if you need recovery

Example use cases

Check wallet balance before sending a large batch of paid API requests
Redeem a promo invite code to cover the cost of a single expensive operation
Retrieve the deposit link/address to top up USDC from an exchange or wallet
Diagnose a 'payment failed' error by confirming balance, retrying, and checking network confirmations

FAQ

How do I check my wallet balance?

Call the wallet info function to retrieve your Base address, current USDC balance, and deposit link.

Can I redeem an invite code more than once?

No. Invite codes are one-time use; if a code is invalid it may already have been redeemed.

What networks are supported for deposits?

Only USDC on the Base network is supported. Deposits on other networks or tokens will be lost.