Send Crypto from PeerPesa Balance

Use the PeerPesa Send API to move crypto from your wallet balance to an external blockchain address or to another PeerPesa user. On-chain sends are irreversible and carry network fees from GET /currencies. Internal transfers to other PeerPesa users are always free and settle instantly. Use POST /wallet/send to execute a send, or POST /wallet/send/estimate to preview fees and net amounts before committing.

On-chain to address
Internal to PeerPesa user

Sending to an external address requires a valid address and, for some networks, a memo. For Bitcoin, you can also send over Lightning using an invoice or a Lightning address.

Internal transfers do not touch the blockchain, so they are instant and have no network fee. You target the recipient by email, phone_number, or user_id.

All send examples use the Sandbox base URL:

https://sandbox-api.peerpesa.co/v1

Send production requests to:

https://api.peerpesa.co/v1

Estimate a Send

Before executing a send, you can preview the network fee and net amount the recipient will receive. This is useful for on-chain sends where fees vary by network.

Endpoint

POST /wallet/send/estimate

Request

Headers

Header	Required	Description
`Authorization`	Yes	`Bearer <token>` from your dashboard.
`Content-Type`	Yes	`application/json`
`Idempotency-Key`	Optional	UUID to safely retry the same request without double spending.

Body Parameters

string

required

Asset symbol. For example: USDC, XLM, BTC, CELO, USDT.

string

required

Network code from GET /currencies. For example: STELLAR, CELO, BITCOIN.

string

required

Amount to send as a decimal string; must respect min_withdraw and max_withdraw from GET /currencies.

object

required

Show destination fields

string

required

Either address or peerpesa_user.

string

Required when type is address. The on-chain wallet address.

string

Required for Stellar when sending to exchanges or custodial wallets; optional otherwise.

string

Required when type is peerpesa_user. Can be used instead of phone_number or user_id.

string

Required when type is peerpesa_user. Can be used instead of email or user_id.

string

Required when type is peerpesa_user. Can be used instead of email or phone_number.

Response

string

Asset symbol.

string

Network code.

string

Amount you are sending.

object

Fee breakdown.

Show fee fields

string

Total fee deducted from your balance.

string

Currency or symbol the fee is expressed in.

string

PeerPesa application fee.

string

Blockchain network fee.

string

Amount the recipient receives after fees.

Example Request

curl -X POST https://sandbox-api.peerpesa.co/v1/wallet/send/estimate \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "symbol": "USDC",
    "network": "CELO",
    "amount": "50.00",
    "destination": {
      "type": "address",
      "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f8dEe"
    }
  }'

const sendEstimate = async () => {
  const res = await fetch('https://sandbox-api.peerpesa.co/v1/wallet/send/estimate', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_TOKEN',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      symbol: 'USDC',
      network: 'CELO',
      amount: '50.00',
      destination: {
        type: 'address',
        address: '0x742d35Cc6634C0532925a3b844Bc9e7595f8dEe',
      },
    }),
  });

  const data = await res.json();
  console.log(data);
};

sendEstimate();

Example Response

{
  "symbol": "USDC",
  "network": "CELO",
  "amount": "50.00",
  "fee": {
    "total": "0.50",
    "currency": "USDC",
    "app_fee": "0.30",
    "network_fee": "0.20"
  },
  "net_amount": "49.50"
}

Execute a Send

Initiate a send from your wallet balance. The response is a wallet transaction object with status: pending or processing.

Endpoint

POST /wallet/send

Request

Headers

Header	Required	Description
`Authorization`	Yes	`Bearer <token>` from your dashboard.
`Content-Type`	Yes	`application/json`
`Idempotency-Key`	Optional	UUID to safely retry without double spending.

Body Parameters

string

required

Asset symbol. For example: USDC, XLM, BTC.

string

required

Network code from GET /currencies.

string

required

Amount to send as a decimal string.

object

required

Show destination fields

string

required

address for on-chain sends; peerpesa_user for internal transfers.

string

Required when type is address.

string

Required for Stellar when the destination is an exchange or custodial wallet; optional otherwise.

string

Exactly one of email, phone_number, or user_id when type is peerpesa_user.

string

Exactly one of email, phone_number, or user_id when type is peerpesa_user.

string

Exactly one of email, phone_number, or user_id when type is peerpesa_user.

string

Your own reference or ID for the transaction.

string

Optional memo or note for your records.

Response

A wallet transaction object.

string

Unique transaction ID prefixed with txn_.

string

Always send.

string

One of pending, processing, completed, failed, refunded.

string

Asset symbol.

string

Network code.

string

Amount sent.

object

Fee breakdown.

Show fee fields

string

Total fee.

string

Fee currency.

string

Application fee.

string

Blockchain network fee.

string

Amount received after fees.

string|null

Your optional reference.

string|null

On-chain transaction hash; null for internal transfers.

string

ISO 8601 creation timestamp.

string

ISO 8601 last update timestamp.

Send to an On-chain Address

Follow these steps to send cryptocurrency to an external wallet address.

Check supported coins and withdrawal limits

Call GET /currencies to fetch the latest send_fees, min_withdraw, and max_withdraw for your chosen symbol and network. Only networks with status: active can be used.

Estimate the fee

Call POST /wallet/send/estimate with the same parameters you plan to use for the send so you know the exact fee and net amount before committing.

Execute the send

Call POST /wallet/send with the destination type set to address, the recipient address, and a memo if required. Save the returned id and poll GET /orders/{order_id} or listen to webhooks to track status.

Stellar USDC with memo
CELO USDC

curl -X POST https://sandbox-api.peerpesa.co/v1/wallet/send \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -d '{
    "symbol": "USDC",
    "network": "STELLAR",
    "amount": "100.00",
    "destination": {
      "type": "address",
      "address": "GB3KJPLFUYN5LGTGOD3OZ...",
      "memo": "123456"
    },
    "reference": "ref-send-001",
    "description": "Stellar USDC to exchange"
  }'

const sendStellar = async () => {
  const res = await fetch('https://sandbox-api.peerpesa.co/v1/wallet/send', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_TOKEN',
      'Content-Type': 'application/json',
      'Idempotency-Key': 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
    },
    body: JSON.stringify({
      symbol: 'USDC',
      network: 'STELLAR',
      amount: '100.00',
      destination: {
        type: 'address',
        address: 'GB3KJPLFUYN5LGTGOD3OZ...',
        memo: '123456',
      },
      reference: 'ref-send-001',
      description: 'Stellar USDC to exchange',
    }),
  });

  const data = await res.json();
  console.log(data);
};

sendStellar();

curl -X POST https://sandbox-api.peerpesa.co/v1/wallet/send \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "symbol": "USDC",
    "network": "CELO",
    "amount": "50.00",
    "destination": {
      "type": "address",
      "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f8dEe"
    },
    "reference": "ref-send-002"
  }'

const sendCelo = async () => {
  const res = await fetch('https://sandbox-api.peerpesa.co/v1/wallet/send', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_TOKEN',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      symbol: 'USDC',
      network: 'CELO',
      amount: '50.00',
      destination: {
        type: 'address',
        address: '0x742d35Cc6634C0532925a3b844Bc9e7595f8dEe',
      },
      reference: 'ref-send-002',
    }),
  });

  const data = await res.json();
  console.log(data);
};

sendCelo();

When sending to a Stellar exchange or custodial wallet, the memo field is required. Omitting it can result in lost funds because these services use a single shared address to credit accounts by memo.

Send via Lightning

For Bitcoin (symbol: BTC, network: BITCOIN), you can send over the Lightning Network by passing a Lightning destination.

Body Parameters

object

required

Show Lightning destination fields

string

required

For Lightning, use lightning.

string

A BOLT11 payment request (invoice) string. Required if lightning_address is not provided.

string

A Lightning address (for example, alice@walletofsatoshi.com). Required if invoice is not provided.

Example Request

curl -X POST https://sandbox-api.peerpesa.co/v1/wallet/send \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "symbol": "BTC",
    "network": "BITCOIN",
    "amount": "0.001",
    "destination": {
      "type": "lightning",
      "invoice": "lnbc1m1p3..."
    },
    "reference": "ref-lightning-001"
  }'

const sendLightning = async () => {
  const res = await fetch('https://sandbox-api.peerpesa.co/v1/wallet/send', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_TOKEN',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      symbol: 'BTC',
      network: 'BITCOIN',
      amount: '0.001',
      destination: {
        type: 'lightning',
        invoice: 'lnbc1m1p3...',
      },
      reference: 'ref-lightning-001',
    }),
  });

  const data = await res.json();
  console.log(data);
};

sendLightning();

If you provide both invoice and lightning_address, the API prefers the invoice.

Send to a PeerPesa User

Transfer crypto instantly and fee-free to another PeerPesa account.

Body Parameters

object

required

Show PeerPesa user destination fields

string

required

Must be peerpesa_user.

string

Recipient email address. Exactly one of email, phone_number, or user_id is required.

string

Recipient phone number in E.164 format. Exactly one of email, phone_number, or user_id is required.

string

PeerPesa user UUID. Exactly one of email, phone_number, or user_id is required.

Example Request

curl -X POST https://sandbox-api.peerpesa.co/v1/wallet/send \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "symbol": "USDC",
    "network": "CELO",
    "amount": "200.00",
    "destination": {
      "type": "peerpesa_user",
      "email": "alice@example.com"
    },
    "reference": "ref-internal-001",
    "description": "Payment for invoice 1234"
  }'

const sendInternal = async () => {
  const res = await fetch('https://sandbox-api.peerpesa.co/v1/wallet/send', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_TOKEN',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      symbol: 'USDC',
      network: 'CELO',
      amount: '200.00',
      destination: {
        type: 'peerpesa_user',
        email: 'alice@example.com',
      },
      reference: 'ref-internal-001',
      description: 'Payment for invoice 1234',
    }),
  });

  const data = await res.json();
  console.log(data);
};

sendInternal();

Track a Send

After creating a send, track its status by polling or listening to webhooks.

Poll the transaction

Use GET /orders/{order_id} with the id from the send response.

Listen to webhooks

Configure your webhook endpoint to receive transaction events:

transaction.processing: the send is being broadcast to the network
transaction.completed: confirmations received; the send is final
transaction.failed: the send could not complete; funds remain in your balance

Error Codes

Code	Status	Meaning
`insufficient_balance`	422	The wallet balance for this symbol and network is too low to cover the amount plus fee.
`amount_too_low`	422	The amount is below the network `min_withdraw` from GET /currencies.
`amount_too_high`	422	The amount exceeds the network `max_withdraw` from GET /currencies.
`unsupported_network`	422	The `network` is inactive or not supported. Check GET /currencies.
`unsupported_asset`	422	The `symbol` is not supported on the requested network.
`invalid_wallet_address`	422	The provided `address` is not valid for the network.
`network_unavailable`	503	The network is temporarily unavailable. Retry with exponential backoff.
`recipient_not_found`	404	The specified `email`, `phone_number`, or `user_id` does not match a PeerPesa user.
`beneficiary_mismatch`	422	The transfer details do not match the beneficiary record.

All errors are returned in this shape:

{
  "error": {
    "code": "invalid_wallet_address",
    "message": "The provided address is not valid for the selected network.",
    "param": "destination.address",
    "request_id": "req_abc123"
  }
}

On-chain Irreversibility Warning

On-chain blockchain transactions are irreversible. Always verify the destination address and, for Stellar, include a memo when required. PeerPesa cannot recover funds sent to the wrong address.

​Estimate a Send

​Endpoint

​Request

Headers

Body Parameters

​Response

​Example Request

​Example Response

​Execute a Send

​Endpoint

​Request

Headers

Body Parameters

​Response

​Send to an On-chain Address

​Send via Lightning

​Body Parameters

​Example Request

​Send to a PeerPesa User

​Body Parameters

​Example Request

​Track a Send

​Error Codes

​On-chain Irreversibility Warning

Estimate a Send

Endpoint

Request

Response

Example Request

Example Response

Execute a Send

Endpoint

Request

Response

Send to an On-chain Address

Send via Lightning

Body Parameters

Example Request

Send to a PeerPesa User

Body Parameters

Example Request

Track a Send

Error Codes

On-chain Irreversibility Warning