API Reference

Partner API Documentation

📚 Quick Navigation: Use the page outline in the right sidebar to jump to specific API endpoints.

🔑 Need an API Key? Contact partners@snowball.money to get started with Partner API access and receive your credit allocation.

Overview

The Partner API provides access to Snowball's identity resolution and cross-chain bridge services. Partners can integrate these APIs to offer naming service search and blockchain bridging capabilities to their users.

All API endpoints are credit-based, with each operation consuming a predetermined number of credits from your partner account balance.

🔐 Authentication

All Partner API endpoints require authentication using an API key passed in the request header.

Header Required

x-api-key: <your-partner-api-key>

Example Request

curl -X GET "https://api.snowball.money/partners/stats" \
  -H "x-api-key: your_api_key_here"

Error Responses

401 Unauthorized - Invalid or missing API key
400 Bad Request - Insufficient credits for the operation

📊 Account Management

Get Partner Stats

Retrieve your current credit balance, usage statistics, and account information.

Endpoint: GET /partners/stats Cost: Free (no credits consumed)

Request

GET /partners/stats
x-api-key: your_api_key_here

Response

{
  "email": "partner@example.com",
  "name": "Partner Name",
  "creditBalance": 1000,
  "creditUsage": 150
}

Response Fields

Field

Type

Description

email

string

Partner account email

name

string

Partner account name

creditBalance

number

Remaining credits available

creditUsage

number

Total credits consumed

🔍 Universal Usernames Resolution API

The Universal Usernames Resolution API allows you to search for usernames across multiple naming services including MNS (Modular Naming Service), ENS (Ethereum Name Service), and other supported providers.

Search Identities

Search for identities across all supported naming services with a single request.

Endpoint: GET /partners/cip/identity/search Cost: 1 credit per request

Request

GET /partners/cip/identity/search?query=vitalik&page=1&perPage=10
x-api-key: your_api_key_here

Query Parameters

Parameter

Type

Required

Default

Description

query

string

Yes

Identity name to search for

page

number

Page number for pagination

perPage

number

Results per page (max: 50)

Response

{
  "results": [
    {
      "name": "vitalik.eth",
      "ownerAddress": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
      "source": "ens",
      "provider": "ens",
      "providerName": "Ethereum Name Service",
      "caip2Id": "eip155:1",
      "avatar": "https://ipfs.io/ipfs/QmSP4nq9fnN9dAiCj42ug9Wa79rqmQerZXZch82VqpiH7U",
      "logoURI": "https://ens.domains/logo.png",
      "url": "https://ens.domains",
      "expireAt": "2032-05-04T07:20:02.000Z",
      "registeredAt": "2017-06-10T13:10:00.000Z",
      "multichainAddresses": [
        {
          "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
          "caip2Id": "eip155:1",
          "chainName": "Ethereum",
          "symbol": "ETH"
        },
        {
          "address": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
          "caip2Id": "bip122:000000000019d6689c085ae165831e93",
          "chainName": "Bitcoin",
          "symbol": "BTC"
        }
      ],
      "txtRecords": [
        {
          "key": "com.twitter",
          "value": "VitalikButerin",
          "type": "social"
        },
        {
          "key": "url",
          "value": "https://vitalik.ca",
          "type": "url"
        },
        {
          "key": "email",
          "value": "vitalik@ethereum.org",
          "type": "email"
        }
      ]
    }
  ],
  "pagination": {
    "page": 1,
    "perPage": 10,
    "total": 2,
    "totalPages": 1
  }
}

🌉 Cross-Chain Payments API

The Cross-Chain Payments API enables cross-chain token transfers by aggregating quotes from multiple bridge providers and tracking transaction status.

1. Get Supported Chains

Retrieve a list of all blockchain networks supported for cross-chain bridging.

Endpoint: GET /partners/bridge/chains Cost: 1 credit per request

Request

GET /partners/bridge/chains
x-api-key: your_api_key_here

Response

{
  "chains": [
    {
      "caip2Id": "eip155:1",
      "name": "Ethereum",
      "nativeToken": "ETH",
      "logoURI": "https://raw.githubusercontent.com/lifinance/types/main/src/assets/icons/chains/ethereum.svg",
      "isBridgeSupported": true
    },
    {
      "caip2Id": "solana:mainnet-beta",
      "name": "Solana",
      "nativeToken": "SOL",
      "logoURI": "https://raw.githubusercontent.com/lifinance/types/main/src/assets/icons/chains/solana.svg",
      "isBridgeSupported": true
    }
  ]
}

Response Fields

Chain Object:

Field

Type

Description

caip2Id

string

Chain identifier in CAIP-2 format

name

string

Human-readable chain name

nativeToken

string

Native token symbol (e.g., ETH, SOL)

logoURI

string

Chain logo image URL

isBridgeSupported

boolean

Whether bridging is supported on this chain

2. Get Tokens for a Chain

Retrieve a list of tokens available for bridging on a specific blockchain.

Endpoint: GET /partners/bridge/tokens Cost: 1 credit per request

Request

GET /partners/bridge/tokens?caip2Id=solana:mainnet-beta
x-api-key: your_api_key_here

Query Parameters

Parameter

Type

Required

Description

caip2Id

string

Yes

Chain identifier in CAIP-2 format

Common CAIP-2 IDs

Ethereum: eip155:1
Solana: solana:mainnet-beta
Polygon: eip155:137
Arbitrum: eip155:42161
Base: eip155:8453
Optimism: eip155:10
BSC: eip155:56
Avalanche: eip155:43114

Response

{
  "caip2Id": "solana:mainnet-beta",
  "tokens": [
    {
      "address": "11111111111111111111111111111111",
      "symbol": "SOL",
      "name": "SOL",
      "decimals": 9,
      "logoURI": "https://s2.coinmarketcap.com/static/img/coins/64x64/5426.png",
      "priceUSD": "135.33"
    },
    {
      "address": "Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB",
      "symbol": "USDT",
      "name": "USDT",
      "decimals": 6,
      "logoURI": "https://raw.githubusercontent.com/trustwallet/assets/master/blockchains/ethereum/assets/0xdAC17F958D2ee523a2206206994597C13D831ec7/logo.png",
      "priceUSD": "0.999111"
    }
  ]
}

3. Get Bridge Quote

Request quotes for bridging tokens from one chain to another. Returns available routes with pricing, fees, and transaction data needed for execution.

Endpoint: GET /partners/bridge/quote Cost: 2 credits per request

Request

GET /partners/bridge/quote?fromChain=solana:mainnet-beta&toChain=eip155:1&fromToken=11111111111111111111111111111111&toToken=0x0000000000000000000000000000000000000000&fromAmount=1000000000&fromAddress=SKJiUQWFe5b9hiLH2tjbypzWYARAxaBF3oovE46ToZ1&toAddress=0x5eda5cbcfcc5a4c7e6760436134bf0e10bc6f9b8&slippage=0.3
x-api-key: your_api_key_here

Query Parameters

Parameter

Type

Required

Default

Description

fromChain

string

Yes

Source chain CAIP-2 ID

toChain

string

Yes

Destination chain CAIP-2 ID

fromToken

string

Yes

Source token contract address

toToken

string

Yes

Destination token contract address

fromAmount

string

Yes

Amount to bridge in token's base units

fromAddress

string

Yes

Source wallet address

toAddress

string

fromAddress

Destination wallet address

slippage

number

0.03

Slippage tolerance (0.01 = 1%, 0.3 = 30%)

Amount Format: Amounts must be specified in the token's smallest unit (considering decimals):

For USDC (6 decimals): 1 USDC = 1000000
For SOL (9 decimals): 1 SOL = 1000000000
For ETH (18 decimals): 1 ETH = 1000000000000000000

Native Token Addresses:

EVM chains: Use 0x0000000000000000000000000000000000000000 for native tokens (ETH, BNB, etc.)
Solana: Use 11111111111111111111111111111111 for SOL

Response

{
  "routes": [
    {
      "id": "0x1234567890abcdef",
      "fromChain": "solana:mainnet-beta",
      "toChain": "eip155:1",
      "fromToken": "11111111111111111111111111111111",
      "toToken": "0x0000000000000000000000000000000000000000",
      "fromAmount": "1000000000",
      "toAmount": "135000000000000000",
      "toAmountMin": "130000000000000000",
      "gasCostUSD": "2.50",
      "feeCostUSD": "0.75",
      "fromAmountUSD": "135.33",
      "toAmountUSD": "135.00",
      "bridgeProvider": "lifi",
      "estimatedTimeSeconds": 300,
      "transactionData": {
        "from": "SKJiUQWFe5b9hiLH2tjbypzWYARAxaBF3oovE46ToZ1",
        "to": "BridgeContractAddress...",
        "data": "0xabcdef123456...",
        "value": "1000000000",
        "gasLimit": "250000",
        "gasPrice": "5000",
        "chainId": 1151111081099710
      }
    }
  ]
}

4. Check Bridge Transaction Status

Track the progress of a cross-chain bridge transaction from initiation to completion.

Endpoint: GET /partners/bridge/status Cost: 1 credit per request

Request

GET /partners/bridge/status?txHash=2o6c2MLhDAJrSA3kWgwxTDZ9YFbLtVoJANYBPxh5zLJ76PgxYf1gm55xnsfFAk3D3vfjk54HSw7TABGuY8UxJ9tU&bridge=lifi
x-api-key: your_api_key_here

Query Parameters

Parameter

Type

Required

Description

txHash

string

Yes

Source chain transaction hash

bridge

string

Bridge provider name (e.g., "lifi") for faster lookup

Response - Completed Transaction

{
  "status": "DONE",
  "bridge": "lifi",
  "fromTx": {
    "txHash": "2o6c2MLhDAJrSA3kWgwxTDZ9YFbLtVoJANYBPxh5zLJ76PgxYf1gm55xnsfFAk3D3vfjk54HSw7TABGuY8UxJ9tU",
    "txLink": "https://solscan.io/tx/2o6c2MLhDAJrSA3kWgwxTDZ9YFbLtVoJANYBPxh5zLJ76PgxYf1gm55xnsfFAk3D3vfjk54HSw7TABGuY8UxJ9tU",
    "chainId": 1151111081099710,
    "gasUsed": "17175",
    "gasPrice": "1",
    "timestamp": 1764153168
  },
  "toTx": {
    "txHash": "0x325e7362944ed4635531be76799fef55678a9c6b7cfff0b5e6c656758e216106",
    "txLink": "https://etherscan.io/tx/0x325e7362944ed4635531be76799fef55678a9c6b7cfff0b5e6c656758e216106",
    "chainId": 1,
    "gasUsed": "21000",
    "gasPrice": "84665546",
    "timestamp": 1764153179
  },
  "progress": 100,
  "message": "Transaction completed successfully"
}

Status Values:

NOT_FOUND: Transaction not found or not yet indexed
PENDING: Transaction in progress, waiting for confirmations
DONE: Transaction completed successfully on both chains
FAILED: Transaction failed or reverted

Polling Recommendations:

Poll every 10-30 seconds for pending transactions
Stop polling once status is DONE or FAILED
Bridge transactions typically take 2-10 minutes depending on chains

Credit Deduction Policy

Credits are deducted after a successful response (HTTP 200)
Failed requests (4xx, 5xx errors) do not consume credits
Requests with insufficient credits return 400 Bad Request before execution

Quick Start Examples

Example 1: Search for an Identity

curl -X GET \
  "https://api.snowball.money/partners/cip/identity/search?query=vitalik&page=1&perPage=10" \
  -H "x-api-key: your_api_key_here"

Example 2: Get Bridge Quote (Solana → Ethereum)

# Step 1: Get supported chains
curl -X GET \
  "https://api.snowball.money/partners/bridge/chains" \
  -H "x-api-key: your_api_key_here"

# Step 2: Get available tokens on Solana
curl -X GET \
  "https://api.snowball.money/partners/bridge/tokens?caip2Id=solana:mainnet-beta" \
  -H "x-api-key: your_api_key_here"

# Step 3: Get quote for bridging 1 SOL to ETH
curl -X GET \
  "https://api.snowball.money/partners/bridge/quote?fromChain=solana:mainnet-beta&toChain=eip155:1&fromToken=11111111111111111111111111111111&toToken=0x0000000000000000000000000000000000000000&fromAmount=1000000000&fromAddress=YOUR_SOLANA_ADDRESS&toAddress=YOUR_ETH_ADDRESS&slippage=0.3" \
  -H "x-api-key: your_api_key_here"

# Step 4: After executing the transaction, check status
curl -X GET \
  "https://api.snowball.money/partners/bridge/status?txHash=YOUR_TX_HASH&bridge=lifi" \
  -H "x-api-key: your_api_key_here"

Example 3: Check Your Credit Balance

curl -X GET \
  "https://api.snowball.money/partners/stats" \
  -H "x-api-key: your_api_key_here"

🔧 Error Handling

Standard Error Response Format

{
  "statusCode": 400,
  "message": "Error description",
  "error": "Bad Request"
}

Common Error Codes

Status Code

Error

Description

400

Bad Request

Invalid parameters or insufficient credits

401

Unauthorized

Invalid or missing API key

404

Not Found

Resource not found

429

Too Many Requests

Rate limit exceeded

500

Internal Server Error

Server-side error

503

Service Unavailable

Service temporarily unavailable or external API failure

Error Examples

Insufficient Credits

{
  "statusCode": 400,
  "message": "Insufficient credits. Required: 2 credits for BRIDGE_GET_QUOTE",
  "error": "Bad Request"
}

Invalid API Key

{
  "statusCode": 401,
  "message": "Invalid API key",
  "error": "Unauthorized"
}

📚 Additional Resources

CAIP-2 Format

CAIP-2 (Chain Agnostic Improvement Proposal) is a standard for blockchain identification.

Format: namespace:reference

Examples:

Ethereum: eip155:1
Polygon: eip155:137
Solana: solana:mainnet-beta
Bitcoin: bip122:000000000019d6689c085ae165831e93

Supported Naming Services

MNS (Modular Naming Service) - Snowball's native naming service
ENS (Ethereum Name Service) - Ethereum-based naming service
Additional providers coming soon

🆘 Support

For API support, integration assistance, or to request/increase credits:

Email: support@snowball.money
Documentation: https://snowball-mns.gitbook.io/snowball

📄 Terms of Service

By using the Partner API, you agree to:

Use credits responsibly and not attempt to abuse the service
Not resell API access without written permission
Properly attribute Snowball in your application
Comply with all applicable laws and regulations

Credits are non-refundable. Snowball reserves the right to suspend access for violations of the terms of service.

PreviousRoadmap NextReferral & Affiliate Systems

Last updated 10 days ago

hashtagPartner API Documentation

hashtagOverview

hashtag🔐 Authentication

hashtagHeader Required

hashtagExample Request

hashtagError Responses

hashtag📊 Account Management

hashtagGet Partner Stats

hashtag🔍 Universal Usernames Resolution API

hashtagSearch Identities

hashtag🌉 Cross-Chain Payments API

hashtag1. Get Supported Chains

hashtag2. Get Tokens for a Chain

hashtag3. Get Bridge Quote

hashtag4. Check Bridge Transaction Status

hashtagQuick Start Examples

hashtagExample 1: Search for an Identity

hashtagExample 2: Get Bridge Quote (Solana → Ethereum)

hashtagExample 3: Check Your Credit Balance

hashtag🔧 Error Handling

hashtagStandard Error Response Format

hashtagCommon Error Codes

hashtagError Examples

hashtag📚 Additional Resources

hashtagCAIP-2 Format

hashtagSupported Naming Services

hashtag🆘 Support

hashtag📄 Terms of Service

Partner API Documentation

Overview

🔐 Authentication

Header Required

Example Request

Error Responses

📊 Account Management

Get Partner Stats

🔍 Universal Usernames Resolution API

Search Identities

🌉 Cross-Chain Payments API

1. Get Supported Chains

2. Get Tokens for a Chain

3. Get Bridge Quote

4. Check Bridge Transaction Status

Quick Start Examples

Example 1: Search for an Identity

Example 2: Get Bridge Quote (Solana → Ethereum)

Example 3: Check Your Credit Balance

🔧 Error Handling

Standard Error Response Format

Common Error Codes

Error Examples

📚 Additional Resources

CAIP-2 Format

Supported Naming Services

🆘 Support

📄 Terms of Service