Wallets

The Wallet API allows you to create and manage stablecoin wallets on the Solana network (USDC).
Each wallet is a secure account managed by Tsara and synchronized with on-chain data.

You can:

Create new wallets for users or purposes
Retrieve wallet details and balances
Check balance history
Transfer funds between wallets or to on-chain addresses
View all transaction history
Generate multiple deposit addresses per wallet

Overview

Feature	Description
Supported Networks	Solana (mainnet & devnet)
Supported Assets	USDC
Address Type	Solana public keys (base58 encoded)
Balance Updates	Real-time synchronization with blockchain
Transaction Finality	30-60 seconds (blockchain confirmations)
Internal Transfers	Free & instant between Tsara wallets
External Transfers	Standard Solana network fees apply

Wallet Types

Type	Purpose	Use Case
User Wallet	Individual customer wallet	E-commerce, remittance
Business Wallet	Merchant collection wallet	Payment aggregation
Hot Wallet	High-frequency transaction wallet	Trading, automated payments
Cold Storage	Long-term holding wallet	Treasury management

Create a Wallet

Generate a new stablecoin wallet with optional metadata for tracking.

Endpoint

POST /wallets

Headers

Header	Value	Required
`Authorization`	Bearer YOUR_SECRET_KEY	Yes
`Content-Type`	application/json	Yes

Request Parameters

Parameter	Type	Required	Description	Example
`type`	string	Yes	Wallet type. Must be `"stablecoin"`	`"stablecoin"`
`network`	string	Yes	Blockchain network. Must be `"solana"`	`"solana"`
`asset`	string	Yes	Digital asset. Must be `"USDC"`	`"USDC"`
`reference`	string	No	Your unique reference for this wallet (max 100 chars, alphanumeric, hyphen, underscore)	`"user_123_wallet"`
`label`	string	No	Human-readable wallet name (max 100 chars)	`"John Doe - Main Wallet"`
`metadata`	object	No	Custom key-value data for tracking (max 10 keys, 500 chars per value)	`{"user_id": "usr_123"}`

Important: Reference Field

The reference field is your unique identifier for the wallet:

Use it to associate wallets with your users/orders
Must be unique across all your wallets
Once set, cannot be changed
Use for retrieving wallet details via API
Recommended format: user_USER_ID_wallet or order_{order_id}_escrow

Request Example

{
  "type": "stablecoin",
  "network": "solana",
  "asset": "USDC",
  "reference": "user_123_main_wallet",
  "label": "John Doe - Main Wallet",
  "metadata": {
    "user_id": "usr_123",
    "user_email": "[email protected]",
    "wallet_purpose": "trading"
  }
}

curl -X POST "https://sandbox.tsara.ng/v1/wallets" \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "stablecoin",
    "network": "solana",
    "asset": "USDC",
    "reference": "user_123_main_wallet",
    "label": "John Doe - Main Wallet",
    "metadata": {
      "user_id": "usr_123"
    }
  }'

Response

{
  "success": true,
  "status": "success",
  "status_code": 200,
  "message": "Wallet created successfully",
  "data": {
    "id": "wal_695fc9b9d4e992",
    "uid": "uid_8189120642",
    "reference": "user_123_main_wallet",
    "label": "John Doe - Main Wallet",
    "type": "stablecoin",
    "network": "solana",
    "asset": "USDC",
    "primary_address": "7Dg225beKzTqwMrRYnScksD9K5Zgu9ciPqqynL1pWk24",
    "status": "active",
    "balance": 0,
    "metadata": {
      "user_id": "usr_123",
      "user_email": "[email protected]",
      "wallet_purpose": "trading"
    },
    "created_at": "2025-01-31T12:00:00Z",
    "updated_at": "2025-01-31T12:00:00Z"
  }
}

Response Fields

Field	Type	Description
`success`	boolean	Request success status
`status`	string	Request status text
`status_code`	number	HTTP status code
`message`	string	Human-readable message
`data.id`	string	Wallet ID (format: `wal_*`)
`data.uid`	string	Wallet UID (legacy format, use `id` instead)
`data.reference`	string	Your custom reference
`data.label`	string	Wallet label/name
`data.type`	string	Wallet type
`data.network`	string	Blockchain network
`data.asset`	string	Asset held in wallet
`data.primary_address`	string	Main Solana address for this wallet
`data.status`	string	Wallet status: `active`, `suspended`, `closed`
`data.balance`	number	Current USDC balance (full units, not decimals)
`data.metadata`	object	Custom metadata attached to wallet
`data.created_at`	string	Creation timestamp (ISO 8601)
`data.updated_at`	string	Last update timestamp

Wallet Status Values

Status	Description
`active`	Wallet is operational, can send and receive
`suspended`	Wallet temporarily disabled (contact support)
`closed`	Wallet permanently closed, cannot be reactivated

Error Responses

{
  "success": false,
  "status_code": 400,
  "error": {
    "code": "validation_error",
    "message": "Invalid request parameters",
    "details": [
      {
        "field": "reference",
        "message": "Reference already exists"
      }
    ]
  }
}

Common Errors

Status Code	Error Code	Description
400	`validation_error`	Invalid request parameters
400	`duplicate_reference`	Reference already in use
400	`invalid_network`	Network not supported (use `solana`)
400	`invalid_asset`	Asset not supported (use `USDC`)
401	`unauthorized`	Invalid or missing API key
429	`rate_limit_exceeded`	Too many requests

Retrieve a Wallet

Get wallet details by reference or wallet ID.

Endpoint

GET /wallets?reference={reference}

GET /wallets?id={wallet_id}

Query Parameters

Parameter	Type	Required	Description
`reference`	string	No*	Your wallet reference
`id`	string	No*	Wallet ID (format: `wal_` or `uid_`)

*At least one parameter required

Example Request

curl -X GET "https://sandbox.tsara.ng/v1/wallets?reference=user_123_main_wallet" \
  -H "Authorization: Bearer YOUR_SECRET_KEY"

Response

{
  "success": true,
  "status": "success",
  "status_code": 200,
  "message": "Wallet retrieved",
  "data": {
    "id": "wal_695fc9b9d4e992",
    "uid": "uid_8189120642",
    "reference": "user_123_main_wallet",
    "label": "John Doe - Main Wallet",
    "type": "stablecoin",
    "network": "solana",
    "asset": "USDC",
    "primary_address": "7Dg225beKzTqwMrRYnScksD9K5Zgu9ciPqqynL1pWk24",
    "status": "active",
    "balance": 150.50,
    "addresses": [
      {
        "address": "7Dg225beKzTqwMrRYnScksD9K5Zgu9ciPqqynL1pWk24",
        "label": "Primary",
        "is_primary": true
      },
      {
        "address": "BqECHoJQFppNELkPpsviEpuFjCZmKGBkhaZtzV1rA2uw",
        "label": "Deposit Address 1",
        "is_primary": false
      }
    ],
    "metadata": {
      "user_id": "usr_123"
    },
    "created_at": "2025-01-31T12:00:00Z",
    "updated_at": "2025-01-31T14:30:00Z"
  }
}

Get Wallet Balance

Retrieve current balance and balance breakdown for all addresses in a wallet.

Endpoint

GET /wallets/balance?reference={reference}

Query Parameters

Parameter	Type	Required	Description
`reference`	string	Yes	Your wallet reference

Example Request

curl -X GET "https://sandbox.tsara.ng/v1/wallets/balance?reference=user_123_main_wallet" \
  -H "Authorization: Bearer YOUR_SECRET_KEY"

Response

{
  "success": true,
  "status": "success",
  "status_code": 200,
  "message": "Wallet Balance",
  "data": [
    {
      "uid": "uid_8189120642",
      "address": "7Dg225beKzTqwMrRYnScksD9K5Zgu9ciPqqynL1pWk24",
      "balance": 100.50,
      "updated_at": "2025-01-31T14:30:00Z",
      "wallet_reference": "user_123_main_wallet",
      "type": "stablecoin",
      "network": "solana",
      "asset": "USDC"
    },
    {
      "uid": "uid_6368244658",
      "address": "BqECHoJQFppNELkPpsviEpuFjCZmKGBkhaZtzV1rA2uw",
      "balance": 50.00,
      "updated_at": "2025-01-31T13:00:00Z",
      "wallet_reference": "user_123_main_wallet",
      "type": "stablecoin",
      "network": "solana",
      "asset": "USDC"
    }
  ],
  "counter": {
    "total_addresses": 2,
    "total_balance": 150.50
  }
}

Balance Response Fields

Field	Type	Description
`data[].address`	string	Solana address
`data[].balance`	number	USDC balance for this address (full units)
`data[].updated_at`	string	Last balance update timestamp
`counter.total_addresses`	number	Number of addresses in wallet
`counter.total_balance`	number	Combined balance across all addresses

Balance Updates

Balances update automatically when transactions are confirmed on-chain
Typical update time: 30-60 seconds after transaction
Use webhooks for real-time balance change notifications
Balance query is free and can be called frequently

Transfer Funds

Send USDC from one wallet to another Tsara wallet or to any external Solana address.

Endpoint

POST /wallets/transfer

Headers

Header	Value	Required
`Authorization`	Bearer YOUR_SECRET_KEY	Yes
`Content-Type`	application/json	Yes

Request Parameters

Parameter	Type	Required	Description	Example
`from_address`	string	Yes	Source Solana address (must be owned by your wallet)	`"7Dg225b..."`
`to_address`	string	Yes	Destination Solana address (Tsara wallet or external)	`"BqECHoJ..."`
`amount`	number	Yes	Amount to transfer in USDC (full units, min: 0.01)	`25.50`
`network`	string	Yes	Blockchain network. Must be `"Solana"`	`"Solana"`
`asset`	string	Yes	Asset to transfer. Must be `"USDC"`	`"USDC"`
`reference`	string	No	Your unique transfer reference (max 100 chars)	`"payment_123"`
`memo`	string	No	Transfer description/note (max 200 chars)	`"Invoice #1012"`
`metadata`	object	No	Custom tracking data (max 10 keys)	`{"order_id": "ORD-123"}`

Transfer Types

Type	Description	Fees	Speed
Internal	Between Tsara wallets	Free	Instant
External	To non-Tsara Solana address	~0.005 USDC network fee	30-60 seconds

Tsara automatically detects transfer type based on destination address.

Request Example

{
  "from_address": "7Dg225beKzTqwMrRYnScksD9K5Zgu9ciPqqynL1pWk24",
  "to_address": "BqECHoJQFppNELkPpsviEpuFjCZmKGBkhaZtzV1rA2uw",
  "amount": 25.50,
  "network": "Solana",
  "asset": "USDC",
  "reference": "payment_invoice_1012",
  "memo": "Payment for Invoice #1012",
  "metadata": {
    "order_id": "ORD-123",
    "customer_id": "cus_456"
  }
}

curl -X POST "https://sandbox.tsara.ng/v1/wallets/transfer" \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_address": "7Dg225beKzTqwMrRYnScksD9K5Zgu9ciPqqynL1pWk24",
    "to_address": "BqECHoJQFppNELkPpsviEpuFjCZmKGBkhaZtzV1rA2uw",
    "amount": 25.50,
    "network": "Solana",
    "asset": "USDC",
    "reference": "payment_invoice_1012"
  }'

Response

{
  "success": true,
  "status": "success",
  "status_code": 200,
  "message": "25.5 USDC Sent Successfully",
  "data": {
    "id": "trx_3365345301",
    "uid": "trx_3365345301",
    "reference": "payment_invoice_1012",
    "source_wallet_id": "uid_8189120642",
    "source_wallet_reference": "user_123_main_wallet",
    "from_address": "7Dg225beKzTqwMrRYnScksD9K5Zgu9ciPqqynL1pWk24",
    "to_address": "BqECHoJQFppNELkPpsviEpuFjCZmKGBkhaZtzV1rA2uw",
    "amount": 25.50,
    "asset": "USDC",
    "network": "Solana",
    "status": "success",
    "transfer_type": "external",
    "fees": {
      "network_fee": 0.005,
      "total_fees": 0.005
    },
    "onchain_tx": "K4uAzbsksSWS7pq9PNU99vz4xZyeeAKp35F4kDYouayQbWsF86Zd37L9rxQf1EE69QLyo2Yqc62wLvmthC5LEjS",
    "url": "https://explorer.solana.com/tx/K4uAzbsksSWS7pq9PNU99vz4xZyeeAKp35F4kDYouayQbWsF86Zd37L9rxQf1EE69QLyo2Yqc62wLvmthC5LEjS",
    "metadata": {
      "order_id": "ORD-123"
    },
    "created_at": "2025-01-31T15:00:00Z",
    "confirmed_at": "2025-01-31T15:00:45Z"
  },
  "url": "https://explorer.solana.com/tx/K4uAzbsksSWS7pq9PNU99vz4xZyeeAKp35F4kDYouayQbWsF86Zd37L9rxQf1EE69QLyo2Yqc62wLvmthC5LEjS",
  "transaction_hash": "K4uAzbsksSWS7pq9PNU99vz4xZyeeAKp35F4kDYouayQbWsF86Zd37L9rxQf1EE69QLyo2Yqc62wLvmthC5LEjS"
}

Transfer Response Fields

Field	Type	Description
`data.id`	string	Transfer transaction ID
`data.reference`	string	Your transfer reference
`data.transfer_type`	string	`internal` or `external`
`data.status`	string	Transfer status: `pending`, `success`, `failed`
`data.fees`	object	Fee breakdown
`data.fees.network_fee`	number	Solana network fee (0 for internal transfers)
`data.onchain_tx`	string	Solana transaction hash
`data.url`	string	Solana Explorer link
`data.confirmed_at`	string	Blockchain confirmation timestamp

Transfer Status Values

Status	Description	Next Action
`pending`	Transaction submitted to blockchain	Wait for confirmation (30-60s)
`success`	Transaction confirmed on-chain	Transfer complete
`failed`	Transaction failed (insufficient balance, invalid address)	Check error and retry

Fee Calculation

Internal Transfer (Tsara to Tsara):
- Amount sent: 25.50 USDC
- Network fee: 0 USDC
- Recipient receives: 25.50 USDC

External Transfer (to non-Tsara address):
- Amount sent: 25.50 USDC
- Network fee: ~0.005 USDC (paid by sender)
- Recipient receives: 25.50 USDC
- Total deducted from sender: 25.505 USDC

Error Responses

{
  "success": false,
  "status_code": 400,
  "error": {
    "code": "insufficient_balance",
    "message": "Insufficient balance in wallet",
    "details": {
      "available": 10.00,
      "required": 25.50
    }
  }
}

Common Transfer Errors

Error Code	Description	Solution
`insufficient_balance`	Not enough USDC in source address	Add funds or reduce amount
`invalid_address`	Destination address is invalid	Verify Solana address format
`duplicate_reference`	Transfer reference already used	Use unique reference per transfer
`address_not_owned`	Source address not owned by your account	Use correct wallet address
`amount_too_low`	Amount below minimum (0.01 USDC)	Increase transfer amount

List Wallet Transactions

Retrieve transaction history for all wallets or a specific wallet.

Endpoint

GET /wallets/transfers?page={page}&limit={limit}

Query Parameters

Parameter	Type	Required	Default	Description
`page`	number	No	`1`	Page number (starts at 1)
`limit`	number	No	`25`	Items per page (max: 100)
`reference`	string	No	-	Filter by wallet reference
`status`	string	No	-	Filter by status: `pending`, `success`, `failed`
`type`	string	No	-	Filter by type: `IN` (incoming), `OUT` (outgoing)
`from_date`	string	No	-	Start date (ISO 8601: `2025-01-01T00:00:00Z`)
`to_date`	string	No	-	End date (ISO 8601: `2025-01-31T23:59:59Z`)

Example Request

curl -X GET "https://sandbox.tsara.ng/v1/wallets/transfers?page=1&limit=20&status=success" \
  -H "Authorization: Bearer YOUR_SECRET_KEY"

Response

{
  "success": true,
  "status": "success",
  "status_code": 200,
  "message": "Transactions",
  "data": [
    {
      "uid": "trx_3365345301",
      "reference": "payment_invoice_1012",
      "trx_type": "OUT",
      "from_address": "7Dg225beKzTqwMrRYnScksD9K5Zgu9ciPqqynL1pWk24",
      "to_address": "BqECHoJQFppNELkPpsviEpuFjCZmKGBkhaZtzV1rA2uw",
      "amount": 25.50,
      "balance_before": 150.50,
      "balance_after": 124.995,
      "network_fee": 0.005,
      "status": "success",
      "transactionHash": "K4uAzbsksSWS7pq9PNU99vz4xZyeeAKp35F4kDYouayQbWsF86Zd37L9rxQf1EE69QLyo2Yqc62wLvmthC5LEjS",
      "url": "https://explorer.solana.com/tx/K4uAzbsksSWS7pq9PNU99vz4xZyeeAKp35F4kDYouayQbWsF86Zd37L9rxQf1EE69QLyo2Yqc62wLvmthC5LEjS",
      "created_at": "2025-01-31T15:00:00Z",
      "confirmed_at": "2025-01-31T15:00:45Z",
      "network": "solana",
      "asset": "USDC"
    },
    {
      "uid": "trx_1624070676",
      "reference": "deposit_external",
      "trx_type": "IN",
      "from_address": "CfuQhBTFXtHDVDyWpAjhQXmuN1PRLtAne5sppz9D19d",
      "to_address": "7Dg225beKzTqwMrRYnScksD9K5Zgu9ciPqqynL1pWk24",
      "amount": 100.00,
      "balance_before": 50.50,
      "balance_after": 150.50,
      "status": "success",
      "transactionHash": "4o8oKyLwg9uWzzEnWgRynRcKM9qDeokmNAKsnSgP39gx7WMApWfeTCUbmQsEpjDUR7BUK14nKtawCqkLmxgQ6e38",
      "url": "https://explorer.solana.com/tx/4o8oKyLwg9uWzzEnWgRynRcKM9qDeokmNAKsnSgP39gx7WMApWfeTCUbmQsEpjDUR7BUK14nKtawCqkLmxgQ6e38",
      "created_at": "2025-01-31T14:00:00Z",
      "confirmed_at": "2025-01-31T14:00:35Z",
      "network": "solana",
      "asset": "USDC"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 45,
    "total_pages": 3,
    "has_more": true
  }
}

Transaction Fields

Field	Type	Description
`trx_type`	string	`IN` (incoming) or `OUT` (outgoing)
`balance_before`	number	Wallet balance before transaction
`balance_after`	number	Wallet balance after transaction
`network_fee`	number	Network fee paid (only for outgoing transactions)
`confirmed_at`	string	Blockchain confirmation timestamp

Get Specific Transaction

Retrieve details of a single transaction by reference.

Endpoint

GET /wallets/transfers?reference={transfer_reference}

Query Parameters

Parameter	Type	Required	Description
`reference`	string	Yes	Transfer reference

Example Request

curl -X GET "https://sandbox.tsara.ng/v1/wallets/transfers?reference=payment_invoice_1012" \
  -H "Authorization: Bearer YOUR_SECRET_KEY"

Response

{
  "success": true,
  "status": "success",
  "status_code": 200,
  "message": "Transaction",
  "data": {
    "uid": "trx_3365345301",
    "reference": "payment_invoice_1012",
    "trx_type": "OUT",
    "from_address": "7Dg225beKzTqwMrRYnScksD9K5Zgu9ciPqqynL1pWk24",
    "to_address": "BqECHoJQFppNELkPpsviEpuFjCZmKGBkhaZtzV1rA2uw",
    "amount": 25.50,
    "balance_before": 150.50,
    "balance_after": 124.995,
    "network_fee": 0.005,
    "status": "success",
    "transactionHash": "K4uAzbsksSWS7pq9PNU99vz4xZyeeAKp35F4kDYouayQbWsF86Zd37L9rxQf1EE69QLyo2Yqc62wLvmthC5LEjS",
    "url": "https://explorer.solana.com/tx/K4uAzbsksSWS7pq9PNU99vz4xZyeeAKp35F4kDYouayQbWsF86Zd37L9rxQf1EE69QLyo2Yqc62wLvmthC5LEjS",
    "created_at": "2025-01-31T15:00:00Z",
    "confirmed_at": "2025-01-31T15:00:45Z",
    "network": "solana",
    "asset": "USDC"
  }
}

Use Cases & Examples

User Wallet System

async function createUserWallet(userId, userEmail) {
  const response = await fetch('https://sandbox.tsara.ng/v1/wallets', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${SECRET_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      type: 'stablecoin',
      network: 'solana',
      asset: 'USDC',
      reference: `user_$USERID_wallet`,
      label: `$USEREMAIL - Main Wallet`,
      metadata: {
        user_id: userId,
        user_email: userEmail,
        created_via: 'api'
      }
    })
  });

  const data = await response.json();

  await db.users.update(userId, {
    wallet_id: data.data.id,
    wallet_reference: data.data.reference,
    wallet_address: data.data.primary_address
  });

  return data.data;
}

Withdrawal Processing

async function processWithdrawal(userId, amount, destinationAddress) {
  const user = await db.users.findById(userId);

  const balance = await getWalletBalance(user.wallet_reference);

  if (balance.counter.total_balance < amount) {
    throw new Error('Insufficient balance');
  }

  const transfer = await fetch('https://sandbox.tsara.ng/v1/wallets/transfer', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${SECRET_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      from_address: user.wallet_address,
      to_address: destinationAddress,
      amount: amount,
      network: 'Solana',
      asset: 'USDC',
      reference: `withdrawal_$USERID_${Date.now()}`,
      metadata: {
        user_id: userId,
        type: 'withdrawal'
      }
    })
  });

  const data = await transfer.json();

  await db.withdrawals.create({
    user_id: userId,
    amount: amount,
    transaction_hash: data.transaction_hash,
    status: data.data.status,
    reference: data.data.reference
  });

  return data.data;
}

Payment Collection

async function collectPayment(fromWalletRef, toBusinessWallet, amount, orderId) {
  const transfer = await fetch('https://sandbox.tsara.ng/v1/wallets/transfer', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${SECRET_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      from_address: fromWalletRef,
      to_address: toBusinessWallet,
      amount: amount,
      network: 'Solana',
      asset: 'USDC',
      reference: `order_payment_${orderId}`,
      memo: `Payment for Order #${orderId}`,
      metadata: {
        order_id: orderId,
        payment_type: 'order_payment'
      }
    })
  });

  const data = await transfer.json();

  if (data.success) {
    await fulfillOrder(orderId);
  }

  return data.data;
}

Balance Monitoring

async function monitorWalletBalance(walletReference, threshold) {
  const balance = await fetch(
    `https://sandbox.tsara.ng/v1/wallets/balance?reference=${walletReference}`,
    {
      headers: {
        'Authorization': `Bearer ${SECRET_KEY}`
      }
    }
  );

  const data = await balance.json();
  const totalBalance = data.counter.total_balance;

  if (totalBalance < threshold) {
    await notifyLowBalance(walletReference, totalBalance, threshold);
  }

  return totalBalance;
}

Tips & Best Practices

Use meaningful references
```
const reference = `user_$USERID_${walletPurpose}`;
```
Makes wallet management and debugging easier.

Store wallet data

await db.wallets.create({
  wallet_id: wallet.id,
  reference: wallet.reference,
  primary_address: wallet.primary_address,
  user_id: userId,
  created_at: wallet.created_at
});

Check balance before transfers

const balance = await getWalletBalance(reference);
if (balance.counter.total_balance < amount + estimatedFee) {
  throw new Error('Insufficient balance including fees');
}

Use unique transfer references

const transferRef = `${type}_$USERID_${Date.now()}_${randomString()}`;

Monitor for incoming transfers

app.post('/webhooks/tsara', (req, res) => {
  if (req.body.type === 'stablecoin.received') {
    const transfer = req.body.data;
    await creditUserAccount(transfer.to_address, transfer.amount);
  }
  res.sendStatus(200);
});

Implement retry logic for failed transfers

async function transferWithRetry(params, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await createTransfer(params);
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      await sleep(2000 * (i + 1));
    }
  }
}

Cache wallet addresses

const addressCache = new Map();

async function getWalletAddress(reference) {
  if (addressCache.has(reference)) {
    return addressCache.get(reference);
  }

  const wallet = await fetchWallet(reference);
  addressCache.set(reference, wallet.primary_address);
  return wallet.primary_address;
}

Troubleshooting

Transfer shows pending for too long

Cause: Solana network congestion or confirmation delays.

Solution:

Check Solana network status
Wait up to 2 minutes for confirmation
Verify transaction on Solana Explorer using transaction hash
Contact support if pending > 5 minutes

Insufficient balance error despite having funds

Cause: Balance spread across multiple addresses or network fees not accounted for.

Solution:

const balance = await getWalletBalance(reference);
const available = balance.counter.total_balance;
const networkFee = 0.005;
const maxTransfer = available - networkFee;

Wallet not receiving deposits

Cause: Wrong address shared or address not generated yet.

Solution:

Verify address belongs to wallet
Generate deposit address if needed (see Addresses API)
Check address on Solana Explorer
Ensure USDC (not SOL) is being sent

Duplicate reference error

Cause: Reference already used for another wallet/transfer.

Solution:

const reference = `${baseRef}_${timestamp}_${randomId}`;

Balance showing 0 after deposit

Cause: Blockchain confirmation pending or wrong asset sent.

Solution:

Wait 30-60 seconds for confirmation
Verify USDC (not SOL) was sent
Check transaction on Solana Explorer
Ensure sent to correct address

Addresses — Generate multiple deposit addresses per wallet
Webhooks — Receive real-time transfer notifications
Checkout — Accept USDC payments via checkout
Errors & Status Codes — Complete error reference

Overview

Create a Wallet

Retrieve a Wallet

Get Wallet Balance

Transfer Funds

List Wallet Transactions

Get Specific Transaction

Use Cases & Examples

User Wallet System

Withdrawal Processing

Payment Collection

Balance Monitoring

Tips & Best Practices

Troubleshooting

Transfer shows pending for too long

Insufficient balance error despite having funds

Wallet not receiving deposits

Duplicate reference error

Balance showing 0 after deposit

Related Pages