Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.spherepay.co/llms.txt

Use this file to discover all available pages before exploring further.

Use this endpoint to register a customer’s existing blockchain wallet address with SpherePay. SpherePay does not create or custody wallets — it links an address your customer already owns to their SpherePay profile so that transfers can be routed to or from that address. You must register at least one wallet before creating a transfer that involves crypto. The wallet address must already exist on the target network before registration.

​
Endpoint

POST https://api.spherepay.co/v2/wallet

​
Authentication

All requests require a Bearer token in the Authorization header. 
Authorization: Bearer <token>

​
Request parameters

​
customerId
string
required
The unique identifier of the customer who owns this wallet.
​
address
string
required
The wallet address on the specified network. Must be a valid address format for the chosen network (e.g., a 44-character base58 string for Solana, or a 0x-prefixed 42-character hex string for EVM networks).
​
network
string
required
The blockchain network for this wallet. Must be one of:
ValueNetwork
"sol"Solana
"ethereum"Ethereum
"polygon"Polygon
"base"Base
"arbitrum"Arbitrum
"avalanche"Avalanche
"tron"Tron
"starknet"Starknet
  -H "Authorization: Bearer $SPHERE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "customer_66c4168d418a410eae282b83883bdc39",
    "address": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
    "network": "sol"
  }'

​
Response fields

​
id
string
Unique identifier for the registered wallet. Store this value and use it in transfer requests.
​
address
string
The blockchain address that was registered.
​
network
string
The network code this wallet is registered on (e.g., "sol", "ethereum").
​
customerId
string
ID of the customer who owns this wallet.
​
created
string
ISO 8601 timestamp of when the wallet was registered.
​
updated
string
ISO 8601 timestamp of the most recent update.
  "id": "wallet_ce745ef7f3df4b9a8bff1301ce24b045",
  "address": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
  "network": "sol",
  "customerId": "customer_66c4168d418a410eae282b83883bdc39",
  "created": "2025-01-01T00:00:00.000Z",
  "updated": "2025-01-01T00:00:00.000Z"
}

​
Error responses

StatusCodeDescription
400address/invalidThe wallet address is invalid for the specified network.
404resource/not-foundThe specified customer ID does not exist.
422validation/failedValidation failed. The response includes a per-field errors array.
Last modified on May 12, 2026