# API Reference

## Partner API Documentation

{% hint style="info" %}
**📚 Quick Navigation:** Use the page outline in the right sidebar to jump to specific API endpoints.
{% endhint %}

{% hint style="warning" %}
**🔑 Need an API Key?** Contact <partners@snowball.money> to get started with Partner API access and receive your credit allocation.
{% endhint %}

### 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

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

#### Example Request

```bash
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**

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

**Response**

```json
{
  "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**

```http
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**

```json
{
  "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**

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

**Response**

```json
{
  "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**

```http
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**

```json
{
  "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**

```http
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%) |

{% hint style="warning" %}
**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
  {% endhint %}

**Response**

```json
{
  "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**

```http
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**

```json
{
  "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"
}
```

{% hint style="info" %}
**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
  {% endhint %}

***

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

```bash
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)

```bash
# 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

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

***

### 🔧 Error Handling

#### Standard Error Response Format

```json
{
  "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**

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

**Invalid API Key**

```json
{
  "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

{% hint style="success" %}

### 🆘 Support

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

* **Email:** s[upport@snowball.money](mailto:Support@snowball.money)
* **Documentation:** <https://snowball-mns.gitbook.io/snowball>
  {% endhint %}

***

### 📄 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://snowball-mns.gitbook.io/snowball/partner-api/api-reference.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.