Referencia

Wallet Manager API Reference

Complete reference for the Wallet Manager REST API.

Base URL

https://api.sanpay.io/v1

Authentication

All API requests require authentication via Bearer token:

Authorization: Bearer YOUR_API_KEY

Wallets

Create Wallet

POST /wallets

Create a new wallet for monitoring.

Request Body

Field	Type	Required	Description
blockchain	string	✅	Blockchain type: `bitcoin`, `ethereum`
label	string	❌	Human-readable label

Example

curl -X POST https://api.sanpay.io/v1/wallets \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"blockchain": "bitcoin", "label": "Deposits"}'

Response 201 Created

{
  "id": "wal_abc123",
  "blockchain": "bitcoin",
  "label": "Deposits",
  "createdAt": "2024-01-15T10:30:00Z"
}

List Wallets

GET /wallets

Retrieve all wallets for your account.

Query Parameters

Field	Type	Description
blockchain	string	Filter by blockchain
limit	integer	Max results (default: 20, max: 100)
offset	integer	Pagination offset

Response 200 OK

{
  "data": [
    {
      "id": "wal_abc123",
      "blockchain": "bitcoin",
      "label": "Deposits",
      "addressCount": 42,
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "total": 5,
    "limit": 20,
    "offset": 0
  }
}

Get Wallet

GET /wallets/{walletId}

Retrieve a specific wallet.

Response 200 OK

{
  "id": "wal_abc123",
  "blockchain": "bitcoin",
  "label": "Deposits",
  "addressCount": 42,
  "createdAt": "2024-01-15T10:30:00Z"
}

Delete Wallet

DELETE /wallets/{walletId}

Delete a wallet and stop monitoring all its addresses.

Response 204 No Content

Addresses

Generate Address

POST /wallets/{walletId}/addresses

Generate a new address for a wallet.

Request Body

Field	Type	Required	Description
label	string	❌	Human-readable label
metadata	object	❌	Custom key-value pairs

Response 201 Created

{
  "id": "addr_xyz789",
  "address": "bc1qxy2kgdygjrsqvzq3rj...",
  "walletId": "wal_abc123",
  "label": null,
  "metadata": {},
  "createdAt": "2024-01-15T10:31:00Z"
}

List Addresses

GET /wallets/{walletId}/addresses

List all addresses for a wallet.

Response 200 OK

{
  "data": [
    {
      "id": "addr_xyz789",
      "address": "bc1qxy2kgdygjrsqvzq3rj...",
      "balance": "0.00150000",
      "transactionCount": 3,
      "createdAt": "2024-01-15T10:31:00Z"
    }
  ],
  "pagination": {
    "total": 42,
    "limit": 20,
    "offset": 0
  }
}

Transactions

List Transactions

GET /wallets/{walletId}/transactions

List transactions for a wallet.

Query Parameters

Field	Type	Description
address	string	Filter by specific address
status	string	Filter: `pending`, `confirmed`
since	string	ISO 8601 timestamp
limit	integer	Max results

Response 200 OK

{
  "data": [
    {
      "id": "tx_def456",
      "txHash": "abc123def456...",
      "address": "bc1qxy2kgdygjrsqvzq3rj...",
      "amount": "0.00150000",
      "direction": "incoming",
      "status": "confirmed",
      "confirmations": 6,
      "blockHeight": 823456,
      "timestamp": "2024-01-15T10:45:00Z"
    }
  ]
}

Error Responses

All errors return a consistent format:

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "The blockchain field is required",
    "details": {
      "field": "blockchain"
    }
  }
}

Error Codes

Code	Status	Description
UNAUTHORIZED	401	Invalid or missing API key
FORBIDDEN	403	Insufficient permissions
NOT_FOUND	404	Resource not found
INVALID_REQUEST	400	Invalid request parameters
RATE_LIMITED	429	Too many requests
INTERNAL_ERROR	500	Server error