HedgePayments - SideBet, CoverPay, Bankroll

Create Wallet

curl --request POST \
  --url https://api.hedgepayments.com/v1/v1/wallets \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "userId": "<string>",
  "currency": "<string>",
  "label": "<string>",
  "initialBalance": 123
}
'

import requests

url = "https://api.hedgepayments.com/v1/v1/wallets"

payload = {
    "userId": "<string>",
    "currency": "<string>",
    "label": "<string>",
    "initialBalance": 123
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    userId: '<string>',
    currency: '<string>',
    label: '<string>',
    initialBalance: 123
  })
};

fetch('https://api.hedgepayments.com/v1/v1/wallets', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.hedgepayments.com/v1/v1/wallets",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'userId' => '<string>',
    'currency' => '<string>',
    'label' => '<string>',
    'initialBalance' => 123
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.hedgepayments.com/v1/v1/wallets"

	payload := strings.NewReader("{\n  \"userId\": \"<string>\",\n  \"currency\": \"<string>\",\n  \"label\": \"<string>\",\n  \"initialBalance\": 123\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.hedgepayments.com/v1/v1/wallets")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"userId\": \"<string>\",\n  \"currency\": \"<string>\",\n  \"label\": \"<string>\",\n  \"initialBalance\": 123\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.hedgepayments.com/v1/v1/wallets")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"userId\": \"<string>\",\n  \"currency\": \"<string>\",\n  \"label\": \"<string>\",\n  \"initialBalance\": 123\n}"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "userId": "<string>",
  "currency": "<string>",
  "balance": {
    "available": 123,
    "pending": 123,
    "reserved": 123,
    "total": 123
  },
  "status": "<string>",
  "label": "<string>",
  "limits": {
    "daily": 123,
    "monthly": 123,
    "transaction": 123
  },
  "createdAt": "<string>",
  "updatedAt": "<string>"
}

POST

wallets

Create Wallet

curl --request POST \
  --url https://api.hedgepayments.com/v1/v1/wallets \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "userId": "<string>",
  "currency": "<string>",
  "label": "<string>",
  "initialBalance": 123
}
'

import requests

url = "https://api.hedgepayments.com/v1/v1/wallets"

payload = {
    "userId": "<string>",
    "currency": "<string>",
    "label": "<string>",
    "initialBalance": 123
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    userId: '<string>',
    currency: '<string>',
    label: '<string>',
    initialBalance: 123
  })
};

fetch('https://api.hedgepayments.com/v1/v1/wallets', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.hedgepayments.com/v1/v1/wallets",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'userId' => '<string>',
    'currency' => '<string>',
    'label' => '<string>',
    'initialBalance' => 123
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.hedgepayments.com/v1/v1/wallets"

	payload := strings.NewReader("{\n  \"userId\": \"<string>\",\n  \"currency\": \"<string>\",\n  \"label\": \"<string>\",\n  \"initialBalance\": 123\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.hedgepayments.com/v1/v1/wallets")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"userId\": \"<string>\",\n  \"currency\": \"<string>\",\n  \"label\": \"<string>\",\n  \"initialBalance\": 123\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.hedgepayments.com/v1/v1/wallets")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"userId\": \"<string>\",\n  \"currency\": \"<string>\",\n  \"label\": \"<string>\",\n  \"initialBalance\": 123\n}"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "userId": "<string>",
  "currency": "<string>",
  "balance": {
    "available": 123,
    "pending": 123,
    "reserved": 123,
    "total": 123
  },
  "status": "<string>",
  "label": "<string>",
  "limits": {
    "daily": 123,
    "monthly": 123,
    "transaction": 123
  },
  "createdAt": "<string>",
  "updatedAt": "<string>"
}

Overview

Create a new digital wallet for storing and managing user funds. Each wallet is tied to a specific user and currency, supporting both fiat currencies (USD, EUR, GBP) and cryptocurrencies (BTC, ETH, SOL, USDC). Use Cases:

Onboarding new users with their first wallet
Creating multi-currency wallets for international users
Setting up merchant settlement wallets
Establishing escrow or custody wallets

Authentication

curl -X POST https://api.hedgepayments.com/v1/wallets \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

const response = await fetch('https://api.hedgepayments.com/v1/wallets', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
});

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
}
response = requests.post('https://api.hedgepayments.com/v1/wallets', headers=headers)

Request Body

string

required

The unique identifier of the user who will own this wallet. Must be a valid user ID from your system.Example: "user_1a2b3c4d5e"

string

required

The currency code for this wallet. Supports ISO 4217 codes for fiat currencies and standard crypto ticker symbols.Supported Fiat: USD, EUR, GBP, CAD, AUD, JPY, CHF, CNY, INR, BRL, MXNSupported Crypto: BTC, ETH, SOL, USDC, USDT, MATIC, AVAX, NEARExample: "USD" or "USDC"

string

A human-readable label for the wallet to help users identify it. Maximum 50 characters.Examples:

"Primary Wallet"
"Savings Account"
"Business Operations"

number

Optional initial balance to credit to the wallet in the smallest currency unit (cents for USD, wei for ETH, etc.). Only available for sandbox environments or with special permissions.Example: 10000 (represents $100.00 for USD)

Request Examples

{
  "userId": "user_1a2b3c4d5e",
  "currency": "USD",
  "label": "Primary Wallet"
}

{
  "userId": "user_1a2b3c4d5e",
  "currency": "USDC",
  "label": "Crypto Holdings"
}

{
  "userId": "user_1a2b3c4d5e",
  "currency": "EUR",
  "label": "European Operations",
  "initialBalance": 50000
}

{
  "userId": "user_1a2b3c4d5e",
  "currency": "SOL",
  "label": "Solana Staking"
}

Response

string

Unique identifier for the wallet

string

The user who owns this wallet

string

The wallet’s currency code

object

Current balance information

Show balance

number

Funds available for immediate use

number

Funds in pending transactions

number

Funds held for authorizations

number

Total wallet balance (available + pending + reserved)

string

Current wallet status: pending_verification, active, suspended, frozen, or closed

string

Human-readable wallet label

object

Transaction limits for this wallet

Show limits

number

Maximum daily transaction volume

number

Maximum monthly transaction volume

number

Maximum single transaction amount

string

ISO 8601 timestamp of wallet creation

string

ISO 8601 timestamp of last update

Response Examples

{
  "id": "wallet_9x8y7z6a5b",
  "userId": "user_1a2b3c4d5e",
  "currency": "USD",
  "balance": {
    "available": 0,
    "pending": 0,
    "reserved": 0,
    "total": 0,
    "currency": "USD"
  },
  "status": "active",
  "label": "Primary Wallet",
  "limits": {
    "daily": 1000000,
    "monthly": 5000000,
    "transaction": 100000
  },
  "createdAt": "2025-11-18T22:30:00Z",
  "updatedAt": "2025-11-18T22:30:00Z"
}

{
  "error": "validation_error",
  "message": "Invalid currency code",
  "code": "INVALID_CURRENCY",
  "details": {
    "field": "currency",
    "value": "XYZ",
    "supported": ["USD", "EUR", "GBP", "BTC", "ETH", "SOL", "USDC"]
  }
}

{
  "error": "unauthorized",
  "message": "Invalid or expired API key",
  "code": "INVALID_API_KEY"
}

{
  "error": "duplicate_wallet",
  "message": "User already has a wallet in this currency",
  "code": "WALLET_EXISTS",
  "details": {
    "existingWalletId": "wallet_abc123",
    "userId": "user_1a2b3c4d5e",
    "currency": "USD"
  }
}

Code Examples

import { HedgePayments } from '@hedgepayments/sdk';

const hedge = new HedgePayments(process.env.HEDGE_API_KEY);

async function createUserWallet() {
  try {
    const wallet = await hedge.wallets.create({
      userId: 'user_1a2b3c4d5e',
      currency: 'USD',
      label: 'Primary Wallet'
    });

    console.log('Wallet created:', wallet.id);
    console.log('Current balance:', wallet.balance.available);

    return wallet;
  } catch (error) {
    if (error.code === 'WALLET_EXISTS') {
      console.log('User already has a USD wallet');
      // Retrieve existing wallet
      const existing = await hedge.wallets.list({
        userId: 'user_1a2b3c4d5e',
        currency: 'USD'
      });
      return existing.wallets[0];
    }
    throw error;
  }
}

from hedgepayments import HedgePayments

hedge = HedgePayments(api_key=os.environ['HEDGE_API_KEY'])

def create_user_wallet():
    try:
        wallet = hedge.wallets.create(
            user_id='user_1a2b3c4d5e',
            currency='USD',
            label='Primary Wallet'
        )

        print(f'Wallet created: {wallet.id}')
        print(f'Current balance: {wallet.balance.available}')

        return wallet
    except HedgePayments.WalletExistsError as e:
        print('User already has a USD wallet')
        # Retrieve existing wallet
        existing = hedge.wallets.list(
            user_id='user_1a2b3c4d5e',
            currency='USD'
        )
        return existing.wallets[0]

curl -X POST https://api.hedgepayments.com/v1/wallets \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user_1a2b3c4d5e",
    "currency": "USD",
    "label": "Primary Wallet"
  }'

require 'hedgepayments'

hedge = HedgePayments::Client.new(api_key: ENV['HEDGE_API_KEY'])

def create_user_wallet
  begin
    wallet = hedge.wallets.create(
      user_id: 'user_1a2b3c4d5e',
      currency: 'USD',
      label: 'Primary Wallet'
    )

    puts "Wallet created: #{wallet.id}"
    puts "Current balance: #{wallet.balance.available}"

    wallet
  rescue HedgePayments::WalletExistsError => e
    puts 'User already has a USD wallet'
    # Retrieve existing wallet
    existing = hedge.wallets.list(
      user_id: 'user_1a2b3c4d5e',
      currency: 'USD'
    )
    existing.wallets.first
  end
end

package main

import (
    "context"
    "fmt"
    "os"

    hedgepayments "github.com/hedgepayments/go-sdk"
)

func createUserWallet() (*hedgepayments.Wallet, error) {
    client := hedgepayments.NewClient(os.Getenv("HEDGE_API_KEY"))

    wallet, err := client.Wallets.Create(context.Background(), &hedgepayments.CreateWalletRequest{
        UserID:   "user_1a2b3c4d5e",
        Currency: "USD",
        Label:    "Primary Wallet",
    })

    if err != nil {
        if hedgepayments.IsWalletExistsError(err) {
            fmt.Println("User already has a USD wallet")
            // Retrieve existing wallet
            wallets, _ := client.Wallets.List(context.Background(), &hedgepayments.ListWalletsRequest{
                UserID:   "user_1a2b3c4d5e",
                Currency: "USD",
            })
            return &wallets.Wallets[0], nil
        }
        return nil, err
    }

    fmt.Printf("Wallet created: %s\n", wallet.ID)
    fmt.Printf("Current balance: %.2f\n", wallet.Balance.Available)

    return wallet, nil
}

Error Handling

Error Code	HTTP Status	Description	Resolution
`INVALID_CURRENCY`	400	Unsupported currency code	Use a supported currency from the list
`INVALID_USER_ID`	400	User ID not found	Verify the user exists in your system
`WALLET_EXISTS`	409	User already has wallet in this currency	Retrieve the existing wallet instead
`INVALID_API_KEY`	401	Authentication failed	Check your API key is valid
`RATE_LIMIT_EXCEEDED`	429	Too many requests	Implement exponential backoff
`INSUFFICIENT_PERMISSIONS`	403	API key lacks permissions	Use a key with wallet creation permissions

Best Practices

1. One Wallet Per Currency Per User

Users should have only one wallet per currency. Always check for existing wallets before creating new ones:

// Good: Check first
const existing = await hedge.wallets.list({ userId, currency: 'USD' });
const wallet = existing.wallets[0] || await hedge.wallets.create({ userId, currency: 'USD' });

// Bad: Always create
const wallet = await hedge.wallets.create({ userId, currency: 'USD' }); // May fail

2. Use Descriptive Labels

Help users identify their wallets with clear labels:

// Good
{ label: 'Business Operations' }
{ label: 'Personal Savings' }
{ label: 'Crypto Holdings' }

// Bad
{ label: 'Wallet 1' }
{ label: 'Account' }

3. Handle Errors Gracefully

Always implement proper error handling:

try {
  const wallet = await createWallet(userId, 'USD');
} catch (error) {
  if (error.code === 'WALLET_EXISTS') {
    // Use existing wallet
  } else if (error.code === 'INVALID_USER_ID') {
    // Create user first
  } else {
    // Log and notify
    logger.error('Wallet creation failed', { error, userId });
  }
}

4. Implement Idempotency

Use idempotency keys for safe retries:

const wallet = await hedge.wallets.create({
  userId: 'user_123',
  currency: 'USD',
  idempotencyKey: `wallet-creation-${userId}-${Date.now()}`
});

Webhooks

When a wallet is created, the following webhook event is triggered:

{
  "event": "wallet.created",
  "data": {
    "id": "wallet_9x8y7z6a5b",
    "userId": "user_1a2b3c4d5e",
    "currency": "USD",
    "status": "active",
    "createdAt": "2025-11-18T22:30:00Z"
  },
  "timestamp": "2025-11-18T22:30:00Z"
}

Learn more about webhooks →

Rate Limits

100 requests per minute per API key
1000 wallet creations per day per merchant

List Wallets - Retrieve all wallets for a user
Get Wallet - Get details of a specific wallet
Update Wallet - Modify wallet settings
Get Balance - Check current wallet balance

Support

Need help? Contact us:

API Reference

SideBet API

CoverPay API

Bankroll API

Wallets & Users

Create Wallet

Overview

Authentication

Request Body

Request Examples

Response

Response Examples

Code Examples

Error Handling

Best Practices

1. One Wallet Per Currency Per User

2. Use Descriptive Labels

3. Handle Errors Gracefully

4. Implement Idempotency

Webhooks

Rate Limits

Support

​Overview

​Authentication

​Request Body

​Request Examples

​Response

​Response Examples

​Code Examples

​Error Handling

​Best Practices

​1. One Wallet Per Currency Per User

​2. Use Descriptive Labels

​3. Handle Errors Gracefully

​4. Implement Idempotency

​Webhooks

​Rate Limits

​Related Endpoints

​Support

Overview

Authentication

Request Body

Request Examples

Response

Response Examples

Code Examples

Error Handling

Best Practices

1. One Wallet Per Currency Per User

2. Use Descriptive Labels

3. Handle Errors Gracefully

4. Implement Idempotency

Webhooks

Rate Limits

Related Endpoints

Support