Getting Started

The SovX API lets you onboard users, provision wallets, and move crypto behind a single REST interface. This guide walks the path end to end—confirm connectivity, log in, create a user, give them a wallet, and generate a deposit address—so you go from zero to a funded address in minutes. You log in for a Bearer token, then send your owner x-api-key over HTTPS for SX Connect calls.

Prerequisites

You'll need:

1. A Sovera account — your login email and password. Log in for a Bearer token, then mint your customer API credentials (your owner x-api-key) from it. See Authentication for the full three-tier flow.
2. Development Environment
   • cURL, Postman, or your preferred HTTP client
   • Basic understanding of REST APIs
   • JSON knowledge

Quick Start

Step 1: Test Connectivity

Hit the health endpoint to confirm you can reach the API. It needs no authentication and returns status: "ok" when the service is up—a quick way to rule out network or base-URL problems before you debug credentials.

curl -X GET "https://api.sandbox.sovera.io/sovx/v1/health" \
  -H "accept: application/json"

Expected Response:

{
  "status": "ok",
  "timestamp": "2026-03-12T00:00:00.000Z",
  "uptime": 123456
}

Step 2: Log in

Authenticate with your Sovera account email and password. Login returns a Bearer session token—send it as Authorization: Bearer <token> to manage your Connect APIs, and use it to mint your customer API credentials (your owner x-api-key) and per-user tokens. See Authentication for the full three-tier flow.

curl -X POST "https://api.sandbox.sovera.io/sovx/v1/auth/login" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "your-password"
  }'

Expected Response: a Bearer session token to send on Connect API calls.

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires": "2026-03-12T01:00:00.000Z"
}

Step 3: Create a Customer

Register the customer that anchors your integration. Authenticate with the Bearer token from Step 2. The response returns the customer_id you'll need to mint credentials next. See Create Customer for the full schema.

curl -X POST "https://api.sandbox.sovera.io/sovx/v1/customers" \
  -H "accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -d '{
    "email": "[email protected]",
    "customer_id": "corp-redundant-firewall",
    "entity_name": "Hedge Fund e-commerce"
  }'

Expected Response:

{
  "success": true,
  "data": {
    "email": "[email protected]",
    "customer_id": "corp-redundant-firewall",
    "entity_name": "Hedge Fund e-commerce"
  },
  "meta": {
    "timestamp": "2026-03-12T00:00:00.000Z",
    "version": "v1",
    "trace_id": "abc-123-def-456"
  }
}

Step 4: Generate API Credentials

Mint the customer's API key. Authenticate with the Bearer token from Step 2 and pass the customer_id from Step 3. The response returns a customer_secret—this is the owner x-api-key you'll send on every User API call below. It's shown only once, so capture it now.

curl -X POST "https://api.sandbox.sovera.io/sovx/v1/customers/corp-redundant-firewall/credentials" \
  -H "accept: application/json" \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN"

Expected Response:

{
  "success": true,
  "data": {
    "customer_id": "corp-redundant-firewall",
    "customer_secret": "uiFkvaYbt1YfBO2NiXyi1txbdysIxa8H"
  },
  "meta": {
    "timestamp": "2026-03-12T00:00:00.000Z",
    "version": "v1",
    "trace_id": "abc-123-def-456"
  }
}

Step 5: Create Your First User

Using your owner x-api-key (the customer_secret from Step 4), create the user who'll own the wallet. The response returns a user_id—you'll pass it in the path for every wallet and address call that follows, so hold on to it.

curl -X POST "https://api.sandbox.sovera.io/sovx/v1/users" \
  -H "accept: application/json" \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key-here" \
  -d '{
    "user_type": "individual",
    "email": "[email protected]",
    "first_name": "John",
    "last_name": "Doe",
    "phone": "+1234567890",
    "date_of_birth": "1990-01-01",
    "country": "US"
  }'

Expected Response:

{
  "success": true,
  "data": {
    "user_id": "f4057807-52cf-4083-9ecb-283ef354fb2b",
    "email": "[email protected]",
    "user_type": "individual",
    "status": "active",
    "created_at": "2026-03-12T00:00:00.000Z"
  },
  "meta": {
    "timestamp": "2026-03-12T00:00:00.000Z",
    "version": "v1",
    "trace_id": "abc-123-def-456"
  }
}

Step 6: Create a Wallet

Give the user a wallet for the currency they'll hold. Pass the user_id from Step 5 in the path and name the wallet so it's easy to recognize later. The response returns a wallet_id you'll need in the next step.

curl -X POST "https://api.sandbox.sovera.io/sovx/v1/users/f4057807-52cf-4083-9ecb-283ef354fb2b/wallets" \
  -H "accept: application/json" \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key-here" \
  -d '{
    "name": "My BTC Wallet",
    "currency": "BTC"
  }'

Step 7: Generate Deposit Address

Generate an on-chain address for the wallet. Plug in the wallet_id from the previous step and the currency and network you want to accept, and the user can receive deposits at the returned address. That's the full path—from a health check to a funded address.

curl -X POST "https://api.sandbox.sovera.io/sovx/v1/wallets/{wallet_id}/address" \
  -H "accept: application/json" \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key-here" \
  -d '{
    "currency": "btc",
    "network": "bitcoin-testnet"
  }'

Next Steps

Explore further:

1. User Onboarding Workflow — Complete user setup process
2. Trading Operations — Execute trades
3. Withdrawal Flow — Process withdrawals
4. API Reference — Full endpoint documentation

Common Issues

Every error returns the standard envelope—read errors[0].code and errors[0].message to see exactly what failed, and check Error Codes for the full list.

Authentication Failed (401)

Problem: Invalid or missing API key.

Solution:

• Verify your API key is correct
• Ensure the header is x-api-key (lowercase)
• Check that your API key hasn't expired

Rate Limit Exceeded (429)

Problem: Too many requests.

Solution:

• Check rate limit headers in the response
• Implement exponential backoff
• Contact support for higher limits

Validation Error (400)

Problem: Invalid request data.

Solution:

• Check the error message for specific field issues
• Verify all required fields are present
• Ensure data types match the schema

Support

Need help? Reach out:

• Email: [email protected]
• Documentation: https://docs.sovera.io
• API Status: https://status.sovera.io