SolenceAiPay SDK

Overview

SolenceAiPay helps developers build safer Solana applications by adding intelligent payment security checks. The SDK scans wallet addresses before transactions, protecting users from scams and malicious actors while maintaining a smooth payment experience.

Installation

Install the SDK using your preferred package manager:

npm install @solenceai/payment-sdk @solana/web3.js @solana/wallet-adapter-react

yarn add @solenceai/payment-sdk @solana/web3.js @solana/wallet-adapter-react

pnpm add @solenceai/payment-sdk @solana/web3.js @solana/wallet-adapter-react

Quick Start

Basic Setup

Initialize the client and start checking wallet security:

import { SolenceAiPayClient } from '@solenceai/payment-sdk';

const client = new SolenceAiPayClient({
  apiEndpoint: 'https://api.solenceai.com/api',
  tokenMintAddress: 'YOUR_TOKEN_MINT_ADDRESS',
  minTokenBalance: 5000000,
});

// Check wallet security
const security = await client.verifyRecipientSecurity(recipientAddress);

if (security.passed) {
  // Safe to proceed with payment
  const result = await client.executePayment(
    senderPublicKey,
    signTransaction,
    {
      recipient: recipientAddress,
      amount: '0.1',
      memo: 'Payment for services',
    }
  );
}

React Integration

Drop the payment hook into your component:

import { useSolenceAiPay } from '@solenceai/payment-sdk/react';
import { useWallet } from '@solana/wallet-adapter-react';

function PaymentComponent() {
  const { publicKey, signTransaction } = useWallet();
  const {
    performSecurityCheck,
    executePayment,
    securityCheck,
    tokenGateStatus,
  } = useSolenceAiPay({
    config: {
      apiEndpoint: process.env.NEXT_PUBLIC_API_ENDPOINT!,
      tokenMintAddress: process.env.NEXT_PUBLIC_TOKEN_MINT_ADDRESS,
    },
  });

  const handlePay = async () => {
    const security = await performSecurityCheck(recipientAddress);
    
    if (security.passed) {
      await executePayment({
        recipient: recipientAddress,
        amount: '0.1',
        memo: 'Payment',
      });
    }
  };

  return (
    <div>
      {tokenGateStatus?.hasAccess && (
        <span className="badge">Unlimited Access</span>
      )}
      <button onClick={handlePay}>Send Payment</button>
    </div>
  );
}

How It Works

Security Flow

Token Gating

The SDK implements a simple token-gating mechanism:

• Token Holders (5M+): Unlimited security scans, no rate limits
• Free Tier: 100 scans per day, full feature access

This creates sustainable token utility while keeping the SDK accessible to all developers.

API Reference

SolenceAiPayClient

The main client for all SDK operations.

Configuration

Methods

verifyRecipientSecurity(recipient, viewer?)

Check wallet security score and risk level.

const security = await client.verifyRecipientSecurity(recipientAddress);
// Returns: { score, riskLevel, passed, warnings, hasSafetyBadge, details }

checkTokenGate(walletAddress)

Check if wallet has token-gated access.

const status = await client.checkTokenGate(userWallet);
// Returns: { hasAccess, balance, requiredBalance, remainingCalls }

checkSafetyBadge(walletAddress)

Verify if wallet has Safety Badge NFT.

const hasBadge = await client.checkSafetyBadge(walletAddress);
// Returns: boolean

executePayment(sender, signTransaction, details, options?)

Execute a complete payment with security checks.

const result = await client.executePayment(
  senderPublicKey,
  signTransaction,
  {
    recipient: recipientAddress,
    amount: '0.1',
    memo: 'Payment note',
  }
);
// Returns: { success, signature?, error?, securityScore }

React Hooks

useSolenceAiPay(options)

All-in-one hook with complete SDK functionality.

const {
  performSecurityCheck,
  executePayment,
  paymentState,
  tokenGateStatus,
  transactions,
  balance,
  safetyBadge,
} = useSolenceAiPay({
  config: { apiEndpoint, tokenMintAddress },
  autoCheckTokenGate: true,
});

Backend Requirements

Your backend needs to implement 4 endpoints for the SDK to function:

1. Security Scanner

POST /api/scan
Headers: { "x-viewer-wallet": "USER_WALLET_ADDRESS" }
Body: { wallet: string, isPublic?: boolean }

Response: {
  score: number;           // 0-100
  riskLevel: "LOW" | "MEDIUM" | "HIGH";
  passed: boolean;
  warnings: string[];
}

2. Safety Badge Check

GET /api/badge/check?wallet=ADDRESS

Response: {
  onChainBadge: boolean;
  wallet: string;
}

3. Payment Logger

POST /api/payments/log
Body: {
  sender: string;
  recipient: string;
  amount: number;
  success: boolean;
  transactionSignature?: string;
  securityScore: number;
}

Response: { success: boolean, logId: string }

4. Transaction History

GET /api/transactions?wallet=ADDRESS&limit=10&offset=0

Response: {
  transactions: Array<{
    signature: string;
    type: "sent" | "received";
    amount: number;
    counterparty: string;
    securityScore: number;
    timestamp: string;
  }>;
  total: number;
}

Examples

Complete Payment Flow

// 1. Initialize client
const client = new SolenceAiPayClient({
  apiEndpoint: process.env.NEXT_PUBLIC_API_ENDPOINT!,
  tokenMintAddress: process.env.NEXT_PUBLIC_TOKEN_MINT_ADDRESS,
});

// 2. Check token status (optional, good for UX)
const tokenStatus = await client.checkTokenGate(userWallet);
if (tokenStatus.hasAccess) {
  console.log('User has unlimited access');
}

// 3. Check if recipient has Safety Badge (faster if they do)
const hasBadge = await client.checkSafetyBadge(recipientAddress);
if (hasBadge) {
  console.log('Recipient is verified, skipping scan');
}

// 4. Perform security check
const security = await client.verifyRecipientSecurity(recipientAddress);

if (!security.passed) {
  console.warn('Security check failed:', security.warnings);
  // Show warning to user, let them decide
}

// 5. Execute payment
const result = await client.executePayment(
  senderPublicKey,
  signTransaction,
  {
    recipient: recipientAddress,
    amount: '0.1',
    memo: 'Payment for services',
  }
);

if (result.success) {
  console.log('Payment successful:', result.signature);
} else {
  console.error('Payment failed:', result.error);
}

Event Monitoring

// Track security checks
client.on('security_check_completed', (event) => {
  console.log('Security score:', event.data.score);
  // Send to analytics
});

// Monitor payments
client.on('payment_confirmed', (event) => {
  console.log('Payment confirmed:', event.data.signature);
  // Update UI, show success message
});

// Handle errors
client.on('payment_failed', (event) => {
  console.error('Payment error:', event.data.error);
  // Show error to user
});

Security Best Practices

For Developers

• Always perform security checks — Never skip verification in production, even for small amounts.
• Respect security warnings — If a wallet scores below threshold, show clear warnings to users.
• Implement proper rate limiting — Use Redis or similar for production rate limiting on your backend.
• Validate all inputs — Check wallet addresses, sanitize user input, verify amounts are within bounds.
• Log everything — Track all transactions, security checks, and rate limit hits for monitoring.
• Keep secrets secure — Use environment variables, never commit API keys, rotate credentials regularly.

For Users

• Double-check addresses — Always verify recipient wallet addresses before sending.
• Trust the scores — If a wallet has a low security score, proceed with caution.
• Start small — Test with small amounts first when sending to new addresses.
• Get verified — Consider getting a Safety Badge for your wallet to build trust.

Environment Setup

Frontend Variables

# .env.local
NEXT_PUBLIC_API_ENDPOINT=https://api.solenceai.com/api
NEXT_PUBLIC_TOKEN_MINT_ADDRESS=YOUR_TOKEN_MINT_ADDRESS
NEXT_PUBLIC_MIN_TOKEN_BALANCE=5000000
NEXT_PUBLIC_SOLANA_RPC_URL=https://api.mainnet-beta.solana.com

Backend Variables

# .env
MONGODB_URI=mongodb+srv://username:password@cluster.mongodb.net/db
SOLANA_RPC_URL=https://api.mainnet-beta.solana.com
NEXT_PUBLIC_TOKEN_MINT_ADDRESS=YOUR_TOKEN_MINT_ADDRESS
NEXT_PUBLIC_MIN_TOKEN_BALANCE=5000000
REDIS_URL=redis://localhost:6379  # For rate limiting

TypeScript Support

The SDK is built with TypeScript and provides full type definitions:

import type {
  SolenceAiPayConfig,
  SecurityVerificationResult,
  PaymentResult,
  TokenGateStatus,
  TransactionLog,
  SDKEvent,
} from '@solenceai/payment-sdk';

// Full IntelliSense support
const config: SolenceAiPayConfig = {
  apiEndpoint: 'https://api.solenceai.com',
  tokenMintAddress: 'YOUR_TOKEN_MINT',
};

// Type-safe event handling
client.on('security_check_completed', (event: SDKEvent) => {
  const result: SecurityVerificationResult = event.data;
  console.log(result.score);
});