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 [e-mail] 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": "[e-mail]",
  "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	No	1	Page number for pagination
perPage	number	No	10	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": "[e-mail]",
          "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	No	fromAddress	Destination wallet address
slippage	number	No	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	No	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: [e-mail]

• 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.