Snag

https://docs.snagsolutions.io
Admin
Snag is a white-label onchain loyalty and engagement platform that enables Web3 brands to track,...
Tokens:365,629
Snippets:3,389
Trust Score:6.9
Update:5 months ago
Show doc for...
Tokens:
Raw
### API Request Example

Source: https://docs.snagsolutions.io/loyalty/custom-rewards-api

This is an example of a GET request to retrieve rewards from a custom API endpoint. Ensure your API key is correctly included in the headers.

```bash
curl -X GET 'https://your-api.com/rewards' \
  -H 'x-api-key: YOUR_API_KEY'
```

--------------------------------

### Install Mintlify CLI

Source: https://docs.snagsolutions.io/mintlify/development

Install the Mintlify CLI globally using npm or yarn. Ensure Node.js version 19 or higher is installed.

```bash
npm i -g mintlify
```

```bash
yarn global add mintlify
```

--------------------------------

### Example HTTP Request with API Key

Source: https://docs.snagsolutions.io/api-reference/introduction

An example of an HTTP GET request including the `Host` header and the `x-api-key` for authentication. Ensure the `Host` header matches your configured API endpoint.

```http
GET /api/v1/your-endpoint HTTP/1.1
Host: api.snag.com
x-api-key: <YOUR_API_KEY>
Content-Type: application/json

{ /* Request body if applicable */ }
```

--------------------------------

### Install viem Library

Source: https://docs.snagsolutions.io/loyalty/development/generate-wallet-addresses

Install the viem library using npm. This is required for generating EVM wallet addresses on the backend.

```bash
npm install viem
```

--------------------------------

### Install Mintlify CLI

Source: https://docs.snagsolutions.io/mintlify/README

Install the Mintlify CLI globally to manage your documentation locally. This is required for local development.

```bash
npm i -g mintlify
```

--------------------------------

### Install Dependencies with PNPM

Source: https://docs.snagsolutions.io/loyalty/nextjs-template

Installs project dependencies using PNPM. Ensure Node.js and PNPM are installed before running.

```bash
pnpm install
```

--------------------------------

### Example Badge Response

Source: https://docs.snagsolutions.io/create/badges

This is an example response from the GET /api/loyalty/badges endpoint, illustrating the structure of a fetched badge. It includes details like ID, name, description, image URL, and loyalty conditions.

```json
{
  "data": [
    {
      "id": "b1b1b1b1-b1b1-b1b1-b1b1-b1b1b1b1b1b1",
      "name": "Example Badge",
      "description": "This is an example badge",
      "imageUrl": "https://example.com/image.png",
      "loyaltyConditions": [
        {
          "id": "c1c1c1c1-c1c1-c1c1-c1c1-c1c1c1c1c1c1",
          "type": "rule",
          "description": "Rule completion: Link Click",
          "amount": null,
          "repeatCount": null,
          "requiredCount": null,
          "loyaltyRuleGroupId": null,
          "association": [
            {
              "loyaltyRule": {
                "id": "r1r1r1r1-r1r1-r1r1-r1r1-r1r1r1r1r1r1",
                "name": "Link Click"
              },
              "loyaltyBadge": null,
              "loyaltyRuleGroup": null,
              "loyaltyCurrency": null,
              "loyaltyLeaderboardView": null
            }
          ],
          "loyaltyCurrencyId": null,
          "csvUrl": null
        }
      ]
    }
  ],
  "hasNextPage": "false"
}
```

--------------------------------

### Example Function

Source: https://docs.snagsolutions.io/stratus/functions

An example of how to use the Output class methods within a Stratus function.

```APIDOC
## Example Function

```javascript theme={null}
const axios = require('axios');

module.exports.handler = async (input, output) => {
  try {
    // Make an external API call
    const response = await axios.get('https://api.example.com/data');
    
    // Set the result
    output.setResult({
      data: response.data,
      timestamp: Date.now()
    });

    // Add a transaction if needed
    output.addTransaction({
      to: '0x123...',
      data: '0x456...',
      value: '0'
    });

    // Return the built output
    return output.buildOutput();
  } catch (error) {
    output.setError(`Function failed: ${error.message}`);
    return output.buildOutput();
  }
};
```
```

--------------------------------

### SDK Installation

Source: https://docs.snagsolutions.io/api-reference/sdk

Install the Snag TypeScript SDK using npm.

```APIDOC
## Installation

```sh
npm install @snagsolutions/sdk
```
```

--------------------------------

### Frontend Integration Example (TypeScript)

Source: https://docs.snagsolutions.io/create/rewards-shop

A comprehensive TypeScript example demonstrating the frontend integration flow, including API calls for minting and status polling, and onchain execution for both EVM and Solana.

```typescript
import { sendTransaction, getContract, waitForReceipt } from "thirdweb";
import axios from "axios";

// Assuming necessary imports for UMI, chain definitions, etc.

const buyToken = async (
  props?: BuyTokenProps
): Promise<string | undefined> => {
  const res = await axios.post(`/api/minting/contracts/mint`, {
    quantity,
    assetId,
    shippingId: props?.shippingId,
    shippingOrderType: props?.shippingOrderType,
    emailAddress: props?.emailAddress,
    contractId: contractAddress,
    agreedToSendW9: props?.agreedToSendW9,
    customInputValue: props?.customInputValue,
  });

  if (res.status !== 202) {
    return undefined;
  }

  const mintStatusId = res.data.mintingContractAssetMintStatusId;

  while (true) {
    const { data } = await axios.get(`/api/minting/status/${mintStatusId}`);

    if (data.relayerTxId && data.status === MintStatus.minted) {
      return data.txHash;
    }

    if (data.signature) {
      const signature = JSON.parse(data.signature);

      if (network === NetworkType.solana) {
        // Solana specific execution
        const umi = createUmi();
        const { signature: txSig } = await executeBase64Txn(
          umi,
          signature.signature,
          signature.latest
        );
        await updateMintStatus(mintStatusId, { status: MintStatus.minted, txHash: txSig });
        return txSig;
      } else {
        // EVM specific execution
        const contract = getContract({
          address: contractAddress,
          client: thirdwebClient,
          chain: defineThirdwebChain(chainId),
        });
        const fnToUse = tokenType === 'erc721' ? mintWithSignatureErc721 : mintWithSignatureErc1155;
        const preparedTx = fnToUse({
          contract,
          signature: signature.signature,
          payload: signature.payload,
        });
        const sentTx = await sendTransaction({ account, transaction: preparedTx });
        await waitForReceipt({ client: thirdwebClient, chain: defineThirdwebChain(chainId), transactionHash: sentTx.transactionHash });
        await axios.post(`/api/minting/status/${mintStatusId}`, { status: 'minted', txHash: sentTx.transactionHash });
        return sentTx.transactionHash;
      }
    }
    // Add a delay before polling again
    await new Promise(resolve => setTimeout(resolve, 2000));
  }
};

```

--------------------------------

### Install Snag SDK

Source: https://docs.snagsolutions.io/api-reference/sdk

Install the Snag TypeScript SDK using npm.

```sh
npm install @snagsolutions/sdk
```

--------------------------------

### Example HTTP Request

Source: https://docs.snagsolutions.io/api-reference/introduction

An example of an HTTP request demonstrating how to include the API key and specify the host.

```APIDOC
Here’s an example of an HTTP request with the API key:

```http
GET /api/v1/your-endpoint HTTP/1.1
Host: api.snag.com
x-api-key: <YOUR_API_KEY>
Content-Type: application/json

{ /* Request body if applicable */ }
```
```

--------------------------------

### Example HTTP Request

Source: https://docs.snagsolutions.io/api-reference

An example of an HTTP request demonstrating the inclusion of the API key in the headers and the general structure for making API calls.

```APIDOC
Here’s an example of an HTTP request with the API key:

```
GET /api/v1/your-endpoint HTTP/1.1
Host: api.snag.com
x-api-key: <YOUR_API_KEY>
Content-Type: application/json

{ /* Request body if applicable */ }

```
```

--------------------------------

### Loyalty Accounts Response Example

Source: https://docs.snagsolutions.io/api-reference/loyalty

Example JSON response when successfully retrieving loyalty accounts. It contains an array of account objects, each with user details and loyalty amounts.

```json
{
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174050",
      "loyaltyCurrencyId": "123e4567-e89b-12d3-a456-426614174090",
      "userId": "123e4567-e89b-12d3-a456-426614174000",
      "user": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "walletAddress": "0x1234567890abcdef1234567890abcdef12345678",
        "userMetadata": [
          {
            "walletGroupIdentifier": "group123",
            "twitterUser": "@user123",
            "discordUser": "user123#4567",
            "logoUrl": "https://example.com/logo.png",
            "displayName": "John Doe"
          }
        ],
        "websiteUserAttributeValues": [
          {
            "value": "Website User Attribute Value",
            "websiteUserAttribute": {
              "id": "123e4567-e89b-12d3-a456-426614174004",
              "label": "Website User Attribute Label"
            }
          }
        ]
      },
      "amount": 1500,
      "lockVersion": 1
    }
  ],
  "hasNextPage": true,
  "message": "Success"
}
```

--------------------------------

### Complete Integration Example: Create User with Generated Wallet

Source: https://docs.snagsolutions.io/loyalty/development/generate-wallet-addresses

A full example demonstrating how to generate a new wallet using viem, securely store its private key, and then create a Snag user with the generated wallet address. Ensure private keys are encrypted before storage.

```typescript
import SnagSolutions from '@snagsolutions/sdk'
import { generatePrivateKey, privateKeyToAccount } from 'viem/accounts'

const client = new SnagSolutions({
  apiKey: 'your-api-key-here',
})

async function createUserWithWallet(userId: string, email: string) {
  // Generate new wallet
  const privateKey = generatePrivateKey()
  const account = privateKeyToAccount(privateKey)
  
  // Store private key securely in your database
  await yourDatabase.savePrivateKey({
    userId: userId,
    encryptedPrivateKey: await encryptPrivateKey(privateKey),
  })
  
  // Create Snag user with the generated wallet address
  const user = await client.users.createMetadata({
    walletAddress: account.address,
    externalIdentifier: userId,
    emailAddress: email,
  })
  
  return user
}
```

--------------------------------

### Start Mintlify Development Server

Source: https://docs.snagsolutions.io/mintlify/README

Run the Mintlify development server from the root of your documentation project. Ensure mint.json is present.

```bash
mintlify dev
```

--------------------------------

### Example Social Account Authentication Request

Source: https://docs.snagsolutions.io/loyalty/managing-social-accounts

This is an example of a GET request to the Twitter authentication endpoint. It includes the required `userId` and a `redirect` URL for post-authentication redirection.

```http
GET /api/twitter/auth?userId=123e4567-e89b-12d3-a456-426614174001&redirect=https://your-app.com/auth-callback
```

--------------------------------

### Start Development Server

Source: https://docs.snagsolutions.io/loyalty/nextjs-template

Launches the development server for the Next.js application. Visit http://localhost:3000 to view the app.

```bash
pnpm dev
```

--------------------------------

### Basic Usage

Source: https://docs.snagsolutions.io/api-reference/sdk

Initialize the client with your API key and make a call to create an asset.

```APIDOC
## Usage

```js
import SnagSolutions from '@snagsolutions/sdk';

const client = new SnagSolutions({apiKey: <YOUR_API_KEY>});

async function main() {
  const asset = await client.assets.create({ fileName: 'REPLACE_ME' });

  console.log(asset.signedUrl);
}

main();
```
```

--------------------------------

### Custom OAuth Flow for Twitter Handle Update

Source: https://docs.snagsolutions.io/loyalty/development/connect-social-accounts

Example of a custom OAuth flow where you exchange a code for tokens, get user info, and then update the user's Twitter handle in Snag.

```javascript
// Your custom OAuth flow
async function handleTwitterOAuth(code) {
  // Your OAuth implementation
  const twitterData = await exchangeCodeForToken(code)
  const userInfo = await getTwitterUserInfo(twitterData.access_token)

  // Pass the Twitter handle to Snag
  await client.users.createMetadata({
    walletAddress: currentUser.walletAddress,
    twitterUser: userInfo.username,
  })

  console.log('Twitter handle updated in Snag')
}
```

--------------------------------

### Valid Stratus Function with External Module (Axios)

Source: https://docs.snagsolutions.io/stratus/syntax

This example shows a valid Stratus function that uses the 'axios' module to make an HTTP GET request. Ensure external modules are approved and imported correctly.

```javascript
const axios = require('axios')

module.exports.handler = async (input, output) => {
  const response = await axios.get('https://example.com')
  output.setResult({ data: response.data })
  return output.buildOutput()
}
```

--------------------------------

### Generate MCP Server with `mint-mcp`

Source: https://docs.snagsolutions.io/ai-coding-assistant

Run this command to set up an MCP server that AI tools can automatically detect and use for Snag Docs integration.

```bash
npx mint-mcp add snag
```

--------------------------------

### Get Loyalty Point Balance

Source: https://docs.snagsolutions.io/loyalty/internal-currency-integration

This endpoint retrieves the loyalty point balance for specified wallet addresses. It's designed to be performant for frequent frontend calls. Ensure correct handling of non-existent wallets and multi-currency setups.

```APIDOC
## Get loyalty point balance

* This endpoint will be called many times from our frontend, please ensure it is performant

* If we query for a wallet address which is not present in your system then please either don't include that wallet in the response array or ensure the balance value is set to `0`.

* For multi-currency setups, please include separate account balance objects in the array for each currency, and map your currency to the loyaltyCurrencyId provided in the snag admin.

```jsx theme={null}
GET <URL can be specified, e.g. https://api.domain.com/api/balances>

Query parameters:
{
  walletAddress: string | string[],  // case-insensitive
  startingAfter?: string // optional, only if pagination is required.
}

// no pagination
Status code: 2**
Response body:
{
  "data": [{
    "id": string // optional, only if pagination is required
    walletAddress: string
    amount: string // important: amount must be a string
    loyaltyCurrencyId: string
  }],
  hasNextPage: boolean // if pagination is required
}

```
```

--------------------------------

### Add Initial Loyalty Rules

Source: https://docs.snagsolutions.io/loyalty/nextjs-template

Executes a script to set up the base rule set for your website's loyalty program. Ensure the loyalty currency is created prior to running this command.

```bash
pnpm rules:create
```

--------------------------------

### GET /api/minting/contracts (Get)

Source: https://docs.snagsolutions.io/api-reference/api-changelog

Gets minting contracts. This endpoint was added to provide functionality for retrieving minting contracts.

```APIDOC
## GET /api/minting/contracts

### Description
Gets minting contracts. This endpoint was added to provide functionality for retrieving minting contracts.

### Method
GET

### Endpoint
/api/minting/contracts
```

--------------------------------

### Get Loyalty Multipliers

Source: https://docs.snagsolutions.io/llms.txt

Get Loyalty Multipliers.

```APIDOC
## Get Loyalty Multipliers

### Description
Get Loyalty Multipliers.

### Method
GET

### Endpoint
/loyalty/multipliers
```

--------------------------------

### Project Structure Overview

Source: https://docs.snagsolutions.io/loyalty/nextjs-template

Illustrates the directory structure of the Next.js template application, highlighting key folders like 'app', 'components', 'lib', and 'scripts'.

```bash
. 
├── app/                   # App Router pages
├── components/            # Reusable UI components
├── lib/                   # Utility functions and SDK integrations
├── public/                # Static assets
├── scripts/               # Loyalty setup/teardown scripts
└── .env.example           # Environment variable template
```

--------------------------------

### Get loyalty currencies

Source: https://docs.snagsolutions.io/llms.txt

Get loyalty currencies.

```APIDOC
## Get loyalty currencies

### Description
Get loyalty currencies.

### Method
GET

### Endpoint
/loyalty/currencies
```

--------------------------------

### Get loyalty accounts

Source: https://docs.snagsolutions.io/llms.txt

Get loyalty accounts.

```APIDOC
## Get loyalty accounts

### Description
Get loyalty accounts.

### Method
GET

### Endpoint
/loyalty/accounts

### Query Parameters
- **limit** (integer) - Optional - The maximum number of accounts to return.
- **offset** (integer) - Optional - The number of accounts to skip.
```

--------------------------------

### Connect a User to a Group using Snag SDK

Source: https://docs.snagsolutions.io/loyalty/development/manage-user-groups

This JavaScript example demonstrates how to connect a user to a group using the Snag Solutions SDK. Ensure you have initialized the SDK with your API key.

```javascript
import SnagSolutions from '@snagsolutions/sdk'

const client = new SnagSolutions({
  apiKey: 'your-api-key-here',
})

// Connect a user to a group
const response = await client.users.connect({
  organizationId: '123e4567-e89b-12d3-a456-426614174001',
  walletAddress: '0x1234567890abcdef1234567890abcdef12345678',
  walletType: 'evm',
  websiteId: '123e4567-e89b-12d3-a456-426614174000',
})

console.log('User connected to group:', response.id)
```

--------------------------------

### Get Referrals

Source: https://docs.snagsolutions.io/api-reference/referrals/get-referrals

This endpoint allows you to get referrals.

```APIDOC
## Get Referrals

### Description
This endpoint allows you to get referrals.

### Method
GET

### Endpoint
/referrals
```

--------------------------------

### Create a Basic User with cURL

Source: https://docs.snagsolutions.io/loyalty/development/create-users

Use this cURL command to create a new user by providing only the required `walletAddress`. Ensure your API key is included in the headers.

```bash
curl -X POST 'https://admin.snagsolutions.io/api/users/metadatas' \
    -H 'x-api-key: your-api-key-here' \
    -H 'Content-Type: application/json' \
    -d '{
      "walletAddress": "0x1234567890abcdef1234567890abcdef12345678"
    }'
```

--------------------------------

### Get Users

Source: https://docs.snagsolutions.io/api-reference/identity/get-users

This endpoint allows you to get users.

```APIDOC
## GET /users

### Description
This endpoint allows you to get users.

### Method
GET

### Endpoint
/users
```

--------------------------------

### Navigation with Folder Structure

Source: https://docs.snagsolutions.io/essentials/navigation

Organizes pages by placing MDX files within folders and referencing them using their folder path in `mint.json`. For example, `your-folder/your-page` corresponds to `your-folder/your-page.mdx`.

```json
"navigation": [
    {
        "group": "Group Name",
        "pages": ["your-folder/your-page"]
    }
]
```

--------------------------------

### Get loyalty account streaks

Source: https://docs.snagsolutions.io/llms.txt

Get loyalty account streaks.

```APIDOC
## Get loyalty account streaks

### Description
Get loyalty account streaks.

### Method
GET

### Endpoint
/loyalty/accounts/{accountId}/streaks

### Parameters
#### Path Parameters
- **accountId** (string) - Required - The ID of the loyalty account.
```

--------------------------------

### Get User Metadata

Source: https://docs.snagsolutions.io/api-reference/identity/get-user-metadata

This endpoint is used to get user metadata.

```APIDOC
## Get user metadata

### Description
This endpoint is used to get user metadata

### Method
GET

### Endpoint
/users/{userId}/metadata

### Parameters
#### Path Parameters
- **userId** (string) - Required - The unique identifier of the user.

#### Response
#### Success Response (200)
- **metadata** (object) - A JSON object containing the user's metadata.
  - **key** (string) - Description of the metadata field.
  - **value** (any) - The value of the metadata field.

#### Response Example
```json
{
  "metadata": {
    "lastLogin": "2023-10-27T10:00:00Z",
    "preferences": {
      "theme": "dark"
    }
  }
}
```
```

--------------------------------

### Environment Variables Setup

Source: https://docs.snagsolutions.io/loyalty/nextjs-template

Configure essential environment variables for the application. These include API keys, website and organization IDs, and loyalty currency ID. Optional variables for Twitter and Telegram rules are also available.

```env
NEXT_PUBLIC_API_KEY=your_api_key
NEXT_PUBLIC_WEBSITE_ID=your_website_uuid
NEXT_PUBLIC_ORGANIZATION_ID=your_organization_uuid
LOYALTY_CURRENCY_ID=your_loyalty_currency_id
ENABLE_TWITTER_RULES=boolean # Optional
ENABLE_TELEGRAM_RULES=boolean # Optional
RULES_COLLECTIONS='[{"address":"0x123","network":"mainnet"}]' # Optional
```

--------------------------------

### Get loyalty website page sections

Source: https://docs.snagsolutions.io/llms.txt

Get loyalty website page sections.

```APIDOC
## Get loyalty website page sections

### Description
Get loyalty website page sections.

### Method
GET

### Endpoint
/loyalty/website/page-sections
```
Tokens:
Raw