Wallet Block

Complete digital wallet and payment infrastructure for modern applications

The Wallet Block provides a comprehensive fintech solution for managing digital wallets, processing payments, handling transfers, and tracking transactions. Build marketplace payments, in-app currencies, loyalty programs, and digital banking features with enterprise-grade security and PCI compliance.

Key Features

Digital Wallets - Create and manage user wallets with multiple currency support
Payment Processing - Accept payments via credit cards, bank transfers, and digital methods
Balance Management - Real-time balance tracking with credits, points, and currencies
Transaction History - Complete audit trail with searchable history and exports
Transfers & Payouts - Peer-to-peer transfers and automated disbursements
Fraud Prevention - Built-in fraud detection with risk scoring and velocity checks
Multi-Currency - Support for fiat currencies and virtual tokens
Escrow & Holds - Hold funds for marketplace transactions and disputes

API Endpoint

Service	URL
Wallet	`https://wallets.api.us.23blocks.com`

Environment Routing: One URL, one environment. All shared-platform API keys are live keys:

pk_live_* / sk_live_* → your production tenant. Need a separate staging environment? It is available as a paid add-on on deployments in your own cloud account — see 23blocks in a Box.

Quick Start

Installation

npm install @23blocks/sdk

Basic Usage

import { create23BlocksClient } from '@23blocks/sdk';

const client = create23BlocksClient({
  urls: { wallet: 'https://wallets.api.us.23blocks.com' },
  apiKey: 'your-api-key',
});

// Create a wallet for a user
const wallet = await client.wallets.create({
  user_id: 'user_123',
  currency: 'USD'
});

// Add funds to wallet
const deposit = await client.wallets.deposit(wallet.id, {
  amount: 10000, // $100.00 in cents
  source: 'card',
  source_id: 'card_abc123'
});

// Check balance
const balance = await client.wallets.getBalance(wallet.id);
console.log(`Balance: $${balance.available / 100}`);

// Transfer funds
const transfer = await client.wallets.transfer({
  from_wallet_id: 'wallet_abc',
  to_wallet_id: 'wallet_xyz',
  amount: 2500, // $25.00
  description: 'Payment for services'
});

Authentication

Required Headers

All API requests require authentication:

Authorization: Bearer [JWT_TOKEN]
X-API-Key: [COMPANY_API_KEY]
Content-Type: application/json

PCI Compliance

For handling card data, use our PCI-compliant tokenization endpoints or client-side SDKs. Never send raw card numbers through the API.

API Reference

Create Wallet

Create a new digital wallet for a user.

curl -X POST https://wallets.api.us.23blocks.com/wallets \
  -H "Authorization: Bearer your-jwt-token" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "type": "wallet",
      "attributes": {
        "user_id": "user_123",
        "currency": "USD",
        "name": "Primary Wallet",
        "metadata": {
          "account_type": "personal"
        }
      }
    }
  }'

Response:

{
  "data": {
    "id": "wallet_abc123",
    "type": "wallet",
    "attributes": {
      "unique_id": "wallet_abc123",
      "user_id": "user_123",
      "currency": "USD",
      "name": "Primary Wallet",
      "balance": {
        "available": 0,
        "pending": 0,
        "held": 0
      },
      "status": "active",
      "metadata": {
        "account_type": "personal"
      },
      "created_at": "2024-01-15T10:30:00Z"
    }
  }
}

Get Wallet

Retrieve wallet details and balance.

curl -X GET https://wallets.api.us.23blocks.com/wallets/wallet_abc123 \
  -H "Authorization: Bearer your-jwt-token" \
  -H "X-API-Key: your-api-key"

List User Wallets

Get all wallets for a user.

curl -X GET "https://wallets.api.us.23blocks.com/wallets?user_id=user_123" \
  -H "Authorization: Bearer your-jwt-token" \
  -H "X-API-Key: your-api-key"

Deposit Funds

Add funds to a wallet from an external source.

curl -X POST https://wallets.api.us.23blocks.com/wallets/wallet_abc123/deposit \
  -H "Authorization: Bearer your-jwt-token" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10000,
    "currency": "USD",
    "source": "card",
    "source_id": "pm_card_abc123",
    "description": "Add funds to wallet",
    "metadata": {
      "order_id": "order_xyz"
    }
  }'

Response:

{
  "data": {
    "id": "txn_dep123",
    "type": "transaction",
    "attributes": {
      "unique_id": "txn_dep123",
      "wallet_id": "wallet_abc123",
      "type": "deposit",
      "amount": 10000,
      "currency": "USD",
      "status": "completed",
      "balance_after": 10000,
      "source": {
        "type": "card",
        "id": "pm_card_abc123",
        "last4": "4242"
      },
      "description": "Add funds to wallet",
      "created_at": "2024-01-15T10:35:00Z"
    }
  }
}

Withdraw Funds

Withdraw funds from a wallet to an external account.

curl -X POST https://wallets.api.us.23blocks.com/wallets/wallet_abc123/withdraw \
  -H "Authorization: Bearer your-jwt-token" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000,
    "destination": "bank_account",
    "destination_id": "ba_xyz789",
    "description": "Withdrawal to bank"
  }'

Transfer Between Wallets

Transfer funds between wallets (peer-to-peer).

curl -X POST https://wallets.api.us.23blocks.com/transfers \
  -H "Authorization: Bearer your-jwt-token" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "type": "transfer",
      "attributes": {
        "from_wallet_id": "wallet_abc123",
        "to_wallet_id": "wallet_xyz789",
        "amount": 2500,
        "currency": "USD",
        "description": "Payment for freelance work",
        "metadata": {
          "invoice_id": "inv_123"
        }
      }
    }
  }'

Response:

{
  "data": {
    "id": "transfer_abc123",
    "type": "transfer",
    "attributes": {
      "unique_id": "transfer_abc123",
      "from_wallet_id": "wallet_abc123",
      "to_wallet_id": "wallet_xyz789",
      "amount": 2500,
      "currency": "USD",
      "status": "completed",
      "description": "Payment for freelance work",
      "transactions": [
        {"id": "txn_debit_abc", "type": "debit", "wallet_id": "wallet_abc123"},
        {"id": "txn_credit_xyz", "type": "credit", "wallet_id": "wallet_xyz789"}
      ],
      "created_at": "2024-01-15T11:00:00Z"
    }
  }
}

Hold Funds (Escrow)

Place a hold on funds for marketplace transactions.

curl -X POST https://wallets.api.us.23blocks.com/wallets/wallet_abc123/holds \
  -H "Authorization: Bearer your-jwt-token" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 15000,
    "description": "Order #12345 - Pending delivery",
    "expires_at": "2024-01-22T10:30:00Z",
    "metadata": {
      "order_id": "order_12345",
      "seller_wallet_id": "wallet_seller_xyz"
    }
  }'

Response:

{
  "data": {
    "id": "hold_abc123",
    "type": "hold",
    "attributes": {
      "unique_id": "hold_abc123",
      "wallet_id": "wallet_abc123",
      "amount": 15000,
      "status": "active",
      "description": "Order #12345 - Pending delivery",
      "expires_at": "2024-01-22T10:30:00Z",
      "balance_after": {
        "available": 5000,
        "pending": 0,
        "held": 15000
      },
      "created_at": "2024-01-15T11:30:00Z"
    }
  }
}

Release Hold

Release held funds (capture for seller or refund to buyer).

curl -X POST https://wallets.api.us.23blocks.com/holds/hold_abc123/release \
  -H "Authorization: Bearer your-jwt-token" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "capture",
    "destination_wallet_id": "wallet_seller_xyz",
    "amount": 15000,
    "description": "Order #12345 - Delivered successfully"
  }'

Cancel Hold

Cancel a hold and return funds to available balance.

curl -X POST https://wallets.api.us.23blocks.com/holds/hold_abc123/cancel \
  -H "Authorization: Bearer your-jwt-token" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Order cancelled by customer"
  }'

Transaction History

Get transaction history for a wallet.

curl -X GET "https://wallets.api.us.23blocks.com/wallets/wallet_abc123/transactions?page=1&per_page=20" \
  -H "Authorization: Bearer your-jwt-token" \
  -H "X-API-Key: your-api-key"

Query Parameters:

Parameter	Type	Description
`type`	string	Filter by type (`deposit`, `withdrawal`, `transfer`, `hold`, `release`)
`status`	string	Filter by status (`pending`, `completed`, `failed`, `cancelled`)
`from_date`	datetime	Start date filter
`to_date`	datetime	End date filter
`min_amount`	integer	Minimum amount filter (in cents)
`max_amount`	integer	Maximum amount filter
`sort`	string	Sort field (`created_at`, `amount`)
`order`	string	Sort order (`asc` or `desc`)
`page`	integer	Page number
`per_page`	integer	Items per page (max: 100)

Export Transactions

Export transaction history as CSV or PDF.

curl -X POST https://wallets.api.us.23blocks.com/wallets/wallet_abc123/transactions/export \
  -H "Authorization: Bearer your-jwt-token" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "format": "csv",
    "from_date": "2024-01-01T00:00:00Z",
    "to_date": "2024-01-31T23:59:59Z",
    "email": "user@example.com"
  }'

Payment Processing

Add Payment Method

Tokenize a payment method for future use.

curl -X POST https://wallets.api.us.23blocks.com/payment_methods \
  -H "Authorization: Bearer your-jwt-token" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "type": "payment_method",
      "attributes": {
        "user_id": "user_123",
        "type": "card",
        "token": "tok_card_abc123",
        "billing_address": {
          "line1": "123 Main St",
          "city": "San Francisco",
          "state": "CA",
          "postal_code": "94102",
          "country": "US"
        }
      }
    }
  }'

List Payment Methods

curl -X GET "https://wallets.api.us.23blocks.com/payment_methods?user_id=user_123" \
  -H "Authorization: Bearer your-jwt-token" \
  -H "X-API-Key: your-api-key"

Process Payment

Charge a payment method directly (without wallet).

curl -X POST https://wallets.api.us.23blocks.com/payments \
  -H "Authorization: Bearer your-jwt-token" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "type": "payment",
      "attributes": {
        "amount": 9999,
        "currency": "USD",
        "payment_method_id": "pm_card_abc123",
        "description": "Order #12345",
        "metadata": {
          "order_id": "order_12345",
          "customer_email": "user@example.com"
        }
      }
    }
  }'

Refund Payment

Issue a full or partial refund.

curl -X POST https://wallets.api.us.23blocks.com/payments/pay_abc123/refund \
  -H "Authorization: Bearer your-jwt-token" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000,
    "reason": "Customer requested refund"
  }'

Payouts

Create Payout

Send money to an external bank account.

curl -X POST https://wallets.api.us.23blocks.com/payouts \
  -H "Authorization: Bearer your-jwt-token" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "type": "payout",
      "attributes": {
        "wallet_id": "wallet_abc123",
        "amount": 50000,
        "currency": "USD",
        "destination": {
          "type": "bank_account",
          "id": "ba_xyz789"
        },
        "description": "Weekly seller payout",
        "arrival_date": "2024-01-17"
      }
    }
  }'

Payout Status

Status	Description
`pending`	Payout created, awaiting processing
`processing`	Being processed by bank
`in_transit`	Funds in transit to destination
`completed`	Successfully deposited
`failed`	Failed to process
`cancelled`	Cancelled before processing

Virtual Currencies & Points

Create Currency

Define a custom virtual currency or points system.

curl -X POST https://wallets.api.us.23blocks.com/currencies \
  -H "Authorization: Bearer your-jwt-token" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "type": "currency",
      "attributes": {
        "code": "POINTS",
        "name": "Reward Points",
        "symbol": "pts",
        "decimals": 0,
        "exchange_rate": 0.01,
        "exchange_currency": "USD"
      }
    }
  }'

Award Points

Credit points to a user's wallet.

curl -X POST https://wallets.api.us.23blocks.com/wallets/wallet_points_abc/credit \
  -H "Authorization: Bearer your-jwt-token" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 500,
    "currency": "POINTS",
    "description": "Purchase reward - Order #12345",
    "metadata": {
      "source": "purchase",
      "order_id": "order_12345"
    }
  }'

Redeem Points

Convert points to store credit or cash.

curl -X POST https://wallets.api.us.23blocks.com/wallets/wallet_points_abc/redeem \
  -H "Authorization: Bearer your-jwt-token" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "points": 1000,
    "redemption_type": "cash",
    "destination_wallet_id": "wallet_cash_abc"
  }'

Fraud Prevention

Risk Assessment

Get risk score for a transaction before processing.

curl -X POST https://wallets.api.us.23blocks.com/risk/assess \
  -H "Authorization: Bearer your-jwt-token" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction": {
      "type": "transfer",
      "amount": 50000,
      "from_wallet_id": "wallet_abc123",
      "to_wallet_id": "wallet_xyz789"
    },
    "context": {
      "ip_address": "192.168.1.1",
      "user_agent": "Mozilla/5.0...",
      "device_id": "device_abc123"
    }
  }'

Response:

{
  "data": {
    "risk_score": 35,
    "risk_level": "low",
    "signals": [
      {"type": "velocity", "score": 10, "details": "Normal transaction frequency"},
      {"type": "amount", "score": 15, "details": "Higher than usual amount"},
      {"type": "device", "score": 10, "details": "Known device"}
    ],
    "recommendation": "allow",
    "requires_verification": false
  }
}

Configure Fraud Rules

curl -X POST https://wallets.api.us.23blocks.com/risk/rules \
  -H "Authorization: Bearer your-jwt-token" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "type": "fraud_rule",
      "attributes": {
        "name": "Large Transfer Limit",
        "condition": "amount > 100000",
        "action": "require_verification",
        "enabled": true
      }
    }
  }'

Webhooks

Subscribe to wallet events for real-time notifications.

Available Events

Event	Description
`wallet.created`	New wallet created
`wallet.updated`	Wallet settings updated
`transaction.created`	New transaction initiated
`transaction.completed`	Transaction completed
`transaction.failed`	Transaction failed
`transfer.completed`	Transfer completed
`hold.created`	Funds placed on hold
`hold.released`	Hold released
`payout.completed`	Payout deposited
`payout.failed`	Payout failed
`payment.completed`	Payment processed
`payment.refunded`	Payment refunded

Webhook Payload

{
  "event": "transaction.completed",
  "timestamp": "2024-01-15T10:35:00Z",
  "data": {
    "id": "txn_abc123",
    "type": "transaction",
    "attributes": {
      "wallet_id": "wallet_abc123",
      "type": "deposit",
      "amount": 10000,
      "currency": "USD",
      "status": "completed"
    }
  }
}

SDK Reference

TypeScript/JavaScript

import { create23BlocksClient } from '@23blocks/sdk';

const client = create23BlocksClient({
  urls: { wallet: 'https://wallets.api.us.23blocks.com' },
  apiKey: 'your-api-key',
});

// Marketplace split payment example
const payment = await client.payments.create({
  amount: 10000, // $100.00
  payment_method_id: 'pm_card_abc',
  splits: [
    { wallet_id: 'wallet_seller', amount: 8500 },  // 85% to seller
    { wallet_id: 'wallet_platform', amount: 1500 } // 15% platform fee
  ]
});

// Get wallet with real-time balance
const wallet = await client.wallets.get('wallet_abc123', {
  include: ['pending_transactions', 'recent_activity']
});

React Hook

import { useWallet } from '@23blocks/react';

function WalletDashboard({ userId }) {
  const { wallet, balance, transactions, transfer, loading } = useWallet(userId);

  const handleTransfer = async () => {
    await transfer({
      to_wallet_id: 'wallet_recipient',
      amount: 2500,
      description: 'Payment'
    });
  };

  return (
    <div>
      <h2>Balance: ${balance.available / 100}</h2>
      <button onClick={handleTransfer} disabled={loading}>
        Send $25
      </button>
      <ul>
        {transactions.map(txn => (
          <li key={txn.id}>
            {txn.type}: ${txn.amount / 100}
          </li>
        ))}
      </ul>
    </div>
  );
}

Error Handling

Status Code	Error Type	Description
400	`validation_error`	Invalid request parameters
401	`authentication_error`	Invalid or missing credentials
402	`insufficient_funds`	Wallet balance too low
403	`authorization_error`	Insufficient permissions
404	`not_found`	Wallet or transaction not found
409	`conflict`	Duplicate transaction or wallet exists
422	`processing_error`	Payment processing failed
429	`rate_limit_exceeded`	Too many requests
500	`internal_error`	Server error

Rate Limits

Plan	Transactions/min	API Calls/min
Free	50	1,000
Pro	500	10,000
Enterprise	Unlimited	Custom

Security & Compliance

PCI DSS Level 1 - Highest level of payment security certification
SOC 2 Type II - Security, availability, and confidentiality controls
AML/KYC - Built-in compliance tools for identity verification
Encryption - All data encrypted at rest and in transit

Marketing Page - Feature overview
API Reference - Interactive API documentation
Platform Status - Service uptime monitoring

Use This Block with AI Agents

This block ships an official Claude Code plugin from the public 23blocks marketplace (19 plugins, 205 skills). Your agent gets full working knowledge of this API — endpoints, identity registration, and conventions.

# one-time: add the 23blocks marketplace
claude plugin marketplace add https://github.com/23blocks-OS/ai-agents

# install this block's plugin
claude plugin install wallet-block

Configure BLOCKS_API_URL, BLOCKS_API_KEY, and BLOCKS_AUTH_TOKEN. Register identity first: each block is autonomous — register the user with this block's identity endpoint before private calls (only user_unique_id is required; email/phone are optional notification-routing fields).

Full reference: AI Agents & Claude Code Plugins · github.com/23blocks-OS/ai-agents

Key Features​

API Endpoint​

Quick Start​

Installation​

Basic Usage​

Authentication​

Required Headers​

PCI Compliance​

API Reference​

Create Wallet​

Get Wallet​

List User Wallets​

Deposit Funds​

Withdraw Funds​

Transfer Between Wallets​

Hold Funds (Escrow)​

Release Hold​

Cancel Hold​

Transaction History​

Export Transactions​

Payment Processing​

Add Payment Method​

List Payment Methods​

Process Payment​

Refund Payment​

Payouts​

Create Payout​

Payout Status​

Virtual Currencies & Points​

Create Currency​

Award Points​

Redeem Points​

Fraud Prevention​

Risk Assessment​

Configure Fraud Rules​

Webhooks​

Available Events​

Webhook Payload​

SDK Reference​

TypeScript/JavaScript​

React Hook​

Error Handling​

Rate Limits​

Security & Compliance​

Related Resources​

Use This Block with AI Agents​

Key Features

API Endpoint

Quick Start

Installation

Basic Usage

Authentication

Required Headers

PCI Compliance

API Reference

Create Wallet

Get Wallet

List User Wallets

Deposit Funds

Withdraw Funds

Transfer Between Wallets

Hold Funds (Escrow)

Release Hold

Cancel Hold

Transaction History

Export Transactions

Payment Processing

Add Payment Method

List Payment Methods

Process Payment

Refund Payment

Payouts

Create Payout

Payout Status

Virtual Currencies & Points

Create Currency

Award Points

Redeem Points

Fraud Prevention

Risk Assessment

Configure Fraud Rules

Webhooks

Available Events

Webhook Payload

SDK Reference

TypeScript/JavaScript

React Hook

Error Handling

Rate Limits

Security & Compliance

Related Resources

Use This Block with AI Agents