Quickstart Guide - XentFi API Documentation

This guide will help you make your first API call to XentFi and understand the core concepts.

Prerequisites

A XentFi account (Sign up)
Basic understanding of REST APIs
curl or a REST client (Postman, Insomnia, etc.)

Step 1: Get Your API Credentials

Log into Dashboard

Navigate to dashboard.xentfi.com and log in with your credentials.

Navigate to API Keys

Go to Settings → API Keys from the left sidebar.

Generate New Key

Click Generate New API Key, give it a name like “Development”, and select the environment.

Copy Credentials

Copy your apiKey and orgId. Store them securely - you won’t see the API key again!

Step 2: Set Up Environment Variables

Create a .env file or set environment variables:

export XENTFI_API_KEY="your-api-key"
export XENTFI_ORG_ID="your-org-Id"
export XENTFI_BASE_URL="https://api.xentfi.com/v1"

Step 3: Make Your First API Call

Let’s list all your master wallets:

curl -X GET https://api.xentfi.com/v1/master-wallets \
  -H "apiKey: $XENTFI_API_KEY" \
  -H "orgId: $XENTFI_ORG_ID"

const response = await fetch('https://api.xentfi.com/v1/master-wallets', {
  headers: {
    'apiKey': process.env.XENTFI_API_KEY,
    'orgId': process.env.XENTFI_ORG_ID
  }
});
const data = await response.json();
console.log(data);

import requests
import os

headers = {
    'apiKey': os.environ['XENTFI_API_KEY'],
    'orgId': os.environ['XENTFI_ORG_ID']
}

response = requests.get('https://api.xentfi.com/v1/master-wallets', headers=headers)
print(response.json())

{
    "data": {
        "items": [],
        "total": 0,
        "hasMore": false
    }
}

If you haven’t created any wallets yet, you’ll get an empty list.

Step 4: Create Your First Master Wallet

curl -X POST https://api.xentfi.com/v1/master-wallets \
  -H "apiKey: $XENTFI_API_KEY" \
  -H "orgId: $XENTFI_ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My First Wallet",
    "blockchainId": "eth-sepolia",
    "description": "Development wallet on Sepolia testnet"
  }'

const wallet = await fetch('https://api.xentfi.com/v1/master-wallets', {
  method: 'POST',
  headers: {
    'apiKey': process.env.XENTFI_API_KEY,
    'orgId': process.env.XENTFI_ORG_ID,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'My First Wallet',
    blockchainId: 'eth-sepolia',
    description: 'Development wallet on Sepolia testnet'
  })
}).then(res => res.json());

{
    =
    "data": {
        "id": "wallet_123e4567-e89b-12d3-a456-426614174000",
        "name": "My First Wallet",
        "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0",
        "blockchain": {
            "id": "eth-sepolia",
            "name": "Ethereum Sepolia",
            "chainId": 11155111
        },
        "description": "Development wallet on Sepolia testnet",
        "isActive": true,
        "createdAt": "2024-01-15T10:30:00.000Z"
    }
}

Step 5: Create a Deposit Address

Now let’s create a deposit address that customers can use to pay you:

curl -X POST https://api.xentfi.com/v1/addresses \
  -H "apiKey: $XENTFI_API_KEY" \
  -H "orgId: $XENTFI_ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "masterId": "your-master-wallet-id",
    "name": "Customer Payment Address"
  }'

{
    "data": {
        "id": "addr_123e4567-e89b-12d3-a456-426614174000",
        "name": "Customer Payment Address",
        "walletAddress": "0x8aBc123...",
        "masterWalletId": "your-master-wallet-id"
    }
}

Step 6: Create a Payment Link

Generate a hosted payment page:

curl -X POST https://api.xentfi.com/v1/payment/links \
  -H "apiKey: $XENTFI_API_KEY" \
  -H "orgId: $XENTFI_ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "masterId": "your-master-wallet-id",
    "name": "Product Purchase",
    "amount": "100",
    "currency": "USD",
    "redirectUrl": "https://yourapp.com/success"
  }'

{
    "data": {
        "id": "link_123e4567-e89b-12d3-a456-426614174000",
        "name": "Product Purchase",
        "amount": "100",
        "currency": "USD",
        "url": "https://pay.xentfi.com/link_123e4567",
        "redirectUrl": "https://yourapp.com/success"
    }
}

Step 7: Set Up a Webhook (Optional)

Receive real-time payment notifications:

curl -X POST https://api.xentfi.com/v1/webhooks \
  -H "apiKey: $XENTFI_API_KEY" \
  -H "orgId: $XENTFI_ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhooks/xentfi",
    "events": ["payment.completed", "payment.failed"],
    "secret": "your-webhook-secret"
  }'

Success! 🎉

You’ve successfully:

✅ Made your first API call
✅ Created a master wallet
✅ Generated a deposit address
✅ Created a payment link
✅ (Optional) Set up a webhook

Common Error Handling

Invalid API Key (401)

{
    "error": {
        "code": "UNAUTHORIZED",
        "message": "Invalid API key"
    }
}

Solution: Verify your API key and App ID are correct.

Rate Limit Exceeded (429)

{
    "error": {
        "code": "RATE_LIMIT_EXCEEDED",
        "message": "Too many requests"
    }
}

Solution: Implement exponential backoff or upgrade your plan.

Validation Error (400)

{
    "error": {
        "code": "VALIDATION_ERROR",
        "message": "Missing required field: name"
    }
}

Solution: Check your request body for required fields.

Next Steps

Development Environment

Set up local development with testnets

Authentication Deep Dive

Learn about API security best practices

Explore Products

Discover all XentFi products

API Reference

Browse complete API documentation

​Prerequisites

​Step 1: Get Your API Credentials

​Step 2: Set Up Environment Variables

​Step 3: Make Your First API Call

​Step 4: Create Your First Master Wallet

​Step 5: Create a Deposit Address

​Step 6: Create a Payment Link

​Step 7: Set Up a Webhook (Optional)

​Success! 🎉

​Common Error Handling

​Next Steps