API Reference

Complete reference for MCP Wallet API tools and endpoints.

Overview

MCP Wallet exposes its functionality through:

MCP Tools - For AI assistants using Model Context Protocol
REST API - For direct HTTP integration (advanced)
OAuth 2.1 - For secure authentication

Base URL: http://localhost:8580

Default Port: 8580

Authentication

All API requests require OAuth 2.1 authentication.

OAuth 2.1 Flow

See OAuth 2.1 Guide for complete implementation details.

Quick Summary:

Authorization Request

GET /oauth/authorize
?client_id=your_client_id
&redirect_uri=http://localhost:8080/callback
&response_type=code
&scope=wallet:read wallet:write wallet:transaction
&code_challenge=BASE64URL(SHA256(code_verifier))
&code_challenge_method=S256

Token Exchange

POST https://mcp-wallet-oauth.dev-taoist.workers.dev/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code={authorization_code}
&redirect_uri={redirect_uri}
&client_id={client_id}
&code_verifier={code_verifier}

Use Access Token

GET /mcp
Authorization: Bearer {access_token}

Scopes

Scope	Description	Permissions
`wallet:read`	Read-only access	View balances, addresses, history
`wallet:write`	Modify settings	Change account names, settings
`wallet:transaction`	Send transactions	Create and broadcast transactions

MCP Tools

MCP Wallet implements the Model Context Protocol specification.

Connection

Endpoint: http://localhost:8580/mcp

Protocol: JSON-RPC 2.0 over HTTP

Authentication: Bearer token in Authorization header

Tool: wallet_getAddress

Get the active wallet address.

Request:

json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "wallet_getAddress",
    "arguments": {}
  }
}

Response:

json

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"
      }
    ]
  }
}

Permissions: wallet:read

Errors:

401 - Unauthorized (invalid token)
403 - Forbidden (insufficient permissions)

Tool: wallet_getBalance

Get balance for a specific token.

Request:

json

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "wallet_getBalance",
    "arguments": {
      "token": "BNB"
    }
  }
}

Parameters:

Name	Type	Required	Description
`token`	string	No	Token symbol (BNB, USDT). Omit for all balances.

Response (Single Token):

json

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Balance: 0.892 BNB\nAddress: 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"
      }
    ]
  }
}

Response (All Tokens):

json

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Balances:\n- BNB: 0.892\n- USDT: 50.00\n\nAddress: 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"
      }
    ]
  }
}

Permissions: wallet:read

Errors:

400 - Bad Request (invalid token symbol)
401 - Unauthorized
403 - Forbidden

Tool: wallet_proposeTransaction

Propose and execute a transaction.

Request:

json

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "wallet_proposeTransaction",
    "arguments": {
      "to": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
      "amount": "100000000000000000",
      "token": "BNB"
    }
  }
}

Parameters:

Name	Type	Required	Description
`to`	string	Yes	Recipient address (0x...)
`amount`	string	Yes	Amount in Wei (BNB) or smallest unit (USDT)
`token`	string	No	Token symbol (BNB, USDT). Default: USDT

Amount Format:

javascript

// BNB uses 18 decimals
1 BNB = "1000000000000000000" Wei

// USDT uses 6 decimals
1 USDT = "1000000" units

// Examples
0.1 BNB = "100000000000000000"
10 USDT = "10000000"

Response (Success):

json

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Transaction sent successfully!\nTx Hash: 0x4952c33d1689cd57090d537052a1bc2efbc206cd65e36be048f04e4840cc75b7\nAmount: 0.1 BNB\nRecipient: 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb\nStatus: Pending\nView on BSCScan: https://bscscan.com/tx/0x4952c3..."
      }
    ]
  }
}

Response (Insufficient Funds):

json

{
  "jsonrpc": "2.0",
  "id": 3,
  "error": {
    "code": -32001,
    "message": "Insufficient funds: Need 0.1005 BNB (0.1 + 0.0005 gas), have 0.05 BNB"
  }
}

Permissions: wallet:transaction

Validation Checks:

✅ OAuth token is valid
✅ Sufficient balance (amount + gas)
✅ Valid recipient address
✅ Valid amount

Coming Soon: Spending Limits

Automatic spending limit validation will be added in a future update.

Errors:

Code	Message	Description
`-32001`	Insufficient funds	Not enough balance for amount + gas
`-32002`	Invalid address	Recipient address invalid
`-32003`	Invalid amount	Amount is zero or negative
`401`	Unauthorized	Invalid or expired token
`403`	Forbidden	Missing `wallet:transaction` permission

Tool: wallet_getTransactionStatus

Get status of a transaction by hash.

Request:

json

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "wallet_getTransactionStatus",
    "arguments": {
      "tx_hash": "0x4952c33d1689cd57090d537052a1bc2efbc206cd65e36be048f04e4840cc75b7"
    }
  }
}

Parameters:

Name	Type	Required	Description
`tx_hash`	string	Yes	Transaction hash (0x...)

Response (Pending):

json

{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Transaction Status: Pending\nTx Hash: 0x4952c3...\nConfirmations: 0\nWaiting for network confirmation..."
      }
    ]
  }
}

Response (Confirmed):

json

{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Transaction Status: Confirmed\nTx Hash: 0x4952c3...\nBlock: 45234567\nConfirmations: 15\nGas Used: 21000\nView on BSCScan: https://bscscan.com/tx/0x4952c3..."
      }
    ]
  }
}

Response (Failed):

json

{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Transaction Status: Failed\nTx Hash: 0x4952c3...\nBlock: 45234567\nError: Execution reverted\nGas Used: 21000 (gas fee still paid)"
      }
    ]
  }
}

Permissions: wallet:read

Errors:

400 - Bad Request (invalid tx hash format)
404 - Not Found (transaction not found)
401 - Unauthorized
403 - Forbidden

REST API Endpoints

For non-MCP integrations, these REST endpoints are available.

Health Check

Endpoint: GET /health

Authentication: None

Response:

json

{
  "status": "ok",
  "version": "1.0.0",
  "mcp_server": "running",
  "oauth_server": "https://mcp-wallet-oauth.dev-taoist.workers.dev"
}

Get Wallet Info

Endpoint: GET /api/wallet/info

Authentication: Bearer token

Response:

json

{
  "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "network": "BSC Mainnet",
  "chainId": 56
}

Get Balances

Endpoint: GET /api/wallet/balances

Authentication: Bearer token

Response:

json

{
  "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "balances": [
    {
      "token": "BNB",
      "balance": "0.892",
      "decimals": 18,
      "valueUSD": "267.60"
    },
    {
      "token": "USDT",
      "balance": "50.00",
      "decimals": 6,
      "valueUSD": "50.00"
    }
  ]
}

Get Transaction History

Endpoint: GET /api/wallet/transactions

Authentication: Bearer token

Query Parameters:

Name	Type	Default	Description
`limit`	number	20	Number of transactions
`offset`	number	0	Pagination offset
`type`	string	all	Filter: `all`, `sent`, `received`, `ai`

Response:

json

{
  "transactions": [
    {
      "hash": "0x4952c33d...",
      "from": "0x742d35Cc...",
      "to": "0x838aff4...",
      "value": "0.1",
      "token": "BNB",
      "timestamp": 1705330200,
      "status": "confirmed",
      "type": "ai-initiated",
      "blockNumber": 45234567,
      "gasUsed": "21000"
    }
  ],
  "total": 150,
  "limit": 20,
  "offset": 0
}

Send Transaction

Endpoint: POST /api/wallet/transaction

Authentication: Bearer token

Request Body:

json

{
  "to": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "amount": "100000000000000000",
  "token": "BNB"
}

Response (Success):

json

{
  "success": true,
  "txHash": "0x4952c33d1689cd57090d537052a1bc2efbc206cd65e36be048f04e4840cc75b7",
  "status": "pending"
}

Response (Error):

json

{
  "success": false,
  "error": "Exceeds spending limit",
  "details": "Amount 0.15 BNB exceeds per-transaction limit of 0.1 BNB"
}

Error Handling

Error Response Format

json

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32000,
    "message": "Error message",
    "data": {
      "details": "Additional error details"
    }
  }
}

Error Codes

Code	Name	Description
`-32700`	Parse error	Invalid JSON
`-32600`	Invalid request	Invalid JSON-RPC
`-32601`	Method not found	Tool doesn't exist
`-32602`	Invalid params	Invalid parameters
`-32603`	Internal error	Server error
`-32001`	Insufficient funds	Not enough balance
`-32002`	Invalid address	Malformed address
`-32003`	Invalid amount	Invalid amount value
`401`	Unauthorized	Invalid/expired token
`403`	Forbidden	Insufficient permissions

Rate Limits

Per Access Token:

100 requests per minute
1000 requests per hour

Per IP Address:

200 requests per minute
2000 requests per hour

Headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1705330260

Webhooks

(Coming soon)

Receive notifications for:

Transaction confirmations
Balance changes
Spending limit alerts

SDK Libraries

JavaScript/TypeScript

(Coming soon)

bash

npm install @mcp-wallet/sdk

typescript

import { MCPWallet } from '@mcp-wallet/sdk';

const wallet = new MCPWallet({
  accessToken: 'your_access_token'
});

const balance = await wallet.getBalance('BNB');
console.log(balance); // "0.892"

Python

(Coming soon)

bash

pip install mcp-wallet

python

from mcp_wallet import MCPWallet

wallet = MCPWallet(access_token='your_access_token')
balance = wallet.get_balance('BNB')
print(balance)  # 0.892

Examples

Example: Check Balance (cURL)

bash

curl -X POST http://localhost:8580/mcp \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "wallet_getBalance",
      "arguments": {
        "token": "BNB"
      }
    }
  }'

Example: Send Transaction (JavaScript)

javascript

const response = await fetch('http://localhost:8580/mcp', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    jsonrpc: '2.0',
    id: 1,
    method: 'tools/call',
    params: {
      name: 'wallet_proposeTransaction',
      arguments: {
        to: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
        amount: '100000000000000000', // 0.1 BNB
        token: 'BNB'
      }
    }
  })
});

const result = await response.json();
console.log(result);

Example: Monitor Transaction (Python)

python

import requests
import time

def wait_for_confirmation(tx_hash, access_token):
    while True:
        response = requests.post(
            'http://localhost:8580/mcp',
            headers={'Authorization': f'Bearer {access_token}'},
            json={
                'jsonrpc': '2.0',
                'id': 1,
                'method': 'tools/call',
                'params': {
                    'name': 'wallet_getTransactionStatus',
                    'arguments': {
                        'tx_hash': tx_hash
                    }
                }
            }
        )

        result = response.json()
        status = result['result']['content'][0]['text']

        if 'Confirmed' in status or 'Failed' in status:
            return status

        print('Waiting for confirmation...')
        time.sleep(3)

# Usage
status = wait_for_confirmation(
    '0x4952c33d1689cd57090d537052a1bc2efbc206cd65e36be048f04e4840cc75b7',
    'your_access_token'
)
print(status)

Testing

Test on Testnet

Use BSC Testnet for development:

Switch network in MCP Wallet
Get testnet BNB from faucet:
- BSC Testnet Faucet
Test all operations with testnet tokens

Mock Server

(Coming soon)

Run local mock server for testing without blockchain:

bash

npm install -g @mcp-wallet/mock-server
mcp-wallet-mock --port 8580

Best Practices

Security

✅ Never log access tokens
✅ Use HTTPS in production (when available)
✅ Rotate tokens regularly
✅ Implement rate limiting on your side
✅ Validate all addresses before transactions

Performance

✅ Cache balance requests (update every 10s)
✅ Batch requests when possible
✅ Use webhooks instead of polling (when available)
✅ Handle rate limits gracefully

Error Handling

✅ Retry on 429 (rate limit)
✅ Re-authenticate on 401
✅ Handle network errors
✅ Validate inputs before API calls
✅ Show user-friendly errors

Changelog

v1.0.0 (2025-01-15)

Initial release
MCP Tools implementation
OAuth 2.1 with PKCE
Spending limits
BNB and USDT support

Coming Soon

Webhook support
SDK libraries
Additional tokens
Multi-chain support

Questions? Join Telegram Community or open GitHub issue.

API Reference ​

Overview ​

Authentication ​

OAuth 2.1 Flow ​

Scopes ​

MCP Tools ​

Connection ​

Tool: wallet_getAddress ​

Tool: wallet_getBalance ​

Tool: wallet_proposeTransaction ​

Tool: wallet_getTransactionStatus ​

REST API Endpoints ​

Health Check ​

Get Wallet Info ​

Get Balances ​

Get Transaction History ​

Send Transaction ​

Error Handling ​

Error Response Format ​

Error Codes ​

Rate Limits ​

Webhooks ​

SDK Libraries ​

JavaScript/TypeScript ​

Python ​

Examples ​

Example: Check Balance (cURL) ​

Example: Send Transaction (JavaScript) ​

Example: Monitor Transaction (Python) ​

Testing ​

Test on Testnet ​

Mock Server ​

Best Practices ​

Security ​

Performance ​

Error Handling ​

Changelog ​

v1.0.0 (2025-01-15) ​

Coming Soon ​

API Reference

Overview

Authentication

OAuth 2.1 Flow

Scopes

MCP Tools

Connection

Tool: wallet_getAddress

Tool: wallet_getBalance

Tool: wallet_proposeTransaction

Tool: wallet_getTransactionStatus

REST API Endpoints

Health Check

Get Wallet Info

Get Balances

Get Transaction History

Send Transaction

Error Handling

Error Response Format

Error Codes

Rate Limits

Webhooks

SDK Libraries

JavaScript/TypeScript

Python

Examples

Example: Check Balance (cURL)

Example: Send Transaction (JavaScript)

Example: Monitor Transaction (Python)

Testing

Test on Testnet

Mock Server

Best Practices

Security

Performance

Error Handling

Changelog

v1.0.0 (2025-01-15)

Coming Soon