Guides
Start typing to search…

Authorization signatures

When adding a wallet as a payment method, authorization signatures are required to authenticate the wallet holder. This security measure ensures that only users with access to the wallet's private key can add it as a payment method. This guide demonstrates how to implement secure wallet authentication across EVM and Solana networks.

Wallet Authentication Guide

Note: This is only required if you are calling the API's directly. If you're using the Pay Widget, the widget will take care of this for you

This guide demonstrates how to generate authentication tokens for both EVM (Ethereum, Polygon, Base, etc.) and Solana wallets.

Table of Contents

Important Security Notes

  1. Never expose private keys in your production code
  2. Always use secure wallet connections in production environments
  3. Store authentication tokens securely
  4. Implement proper error handling for failed wallet connections or signatures
  5. Verify the network (mainnet/testnet) before sending transactions

Requirements

  • EVM Wallets: MetaMask or similar Web3 wallet
  • Solana Wallets: Phantom or similar Solana wallet
  • The message that needs to be signed must be exactly: I accept Loop Crypto Inc's Terms of Service
  • The domain must be exactly: loopcrypto.xyz
    • Using any other values for the message or domain will result in a failed signature verification
  • Node.js dependencies: 
    {
    "dependencies": {
        "ethers": "^6.0.0",
        "web3-token": "^1.0.5",
        "@solana/web3.js": "^1.0.0",
        "bs58": "^5.0.0",
        "tweetnacl": "^1.0.3"
    }
}

Generating and verifying authentication tokens using private keys directly

These examples are standalone test scripts for testing purposes only and should not be used with real private keys in production. They can be run independently to verify wallet authentication functionality.

EVM

const { ethers } = require("ethers");
const Web3Token = require("web3-token");

const authMessage = "I accept Loop Crypto Inc's Terms of Service";
const privateKey = "<YOU PRIVATE KEY HERE>";

async function generateAuthToken() {
    try {
        const wallet = new ethers.Wallet(privateKey);
        const token = await Web3Token.sign((msg) => wallet.signMessage(msg), {
            statement: authMessage,
            domain: "loopcrypto.xyz",
        });

        console.log("Wallet Address:", wallet.address);
        console.log("Auth Token:", token);

        const verified = Web3Token.verify(token);
        console.log("Verified Address:", verified.address);
    } catch (error) {
        console.error("Error:", error.message);
    }
}

generateAuthToken();

Solana

Important note when constructing signatures for Solana:

  1. Signatures should always be base64 encoded when sending in the API requests
  2. Solana wallet addresses are case sensitive and should never be lowercased when sending API requests
const { Keypair } = require("@solana/web3.js");
const bs58 = require("bs58").default;
const nacl = require("tweetnacl");

const authMessage = "I accept Loop Crypto Inc's Terms of Service";
const privateKeyBase58 = "<YOU PRIVATE KEY HERE>";

async function generateAuthToken() {
    try {
        const privateKeyBytes = bs58.decode(privateKeyBase58);
        const keypair = Keypair.fromSecretKey(privateKeyBytes);

        const messageBytes = new TextEncoder().encode(authMessage);
        const signatureBytes = nacl.sign.detached(
            messageBytes,
            keypair.secretKey,
        );
        const signature = Buffer.from(signatureBytes).toString("base64");

        console.log("Wallet Address:", keypair.publicKey.toString());
        console.log("Message:", authMessage);
        console.log("Signature:", signature);

        // Verify the signature
        const verified = nacl.sign.detached.verify(
            messageBytes,
            Buffer.from(signature, "base64"),
            keypair.publicKey.toBytes(),
        );

        console.log("Signature Verified:", verified);
    } catch (error) {
        console.error("Error:", error.message);
    }
}

generateAuthToken();

Running the scripts

To run the test scripts:

# Install dependencies
npm install ethers web3-token @solana/web3.js bs58 tweetnacl

# Add the private key of the wallet you're using to sign to evm-auth.js or solana-auth.js

# Run EVM script
node evm-auth.js

# Run Solana script
node solana-auth.js

Generating and verifying authentication tokens by connecting to a wallet provider

For production environments, you should connect to actual wallet providers (MetaMask for EVM, Phantom for Solana etc). Here are examples of how to implement wallet authentication in a web application:

EVM Wallets

const authMessage = "I accept Loop Crypto Inc's Terms of Service";

async function generateAuthToken() {
    const provider = new ethers.BrowserProvider(window.ethereum);
    const accounts = await window.ethereum.request({
        method: "eth_requestAccounts",
    });
    const signer = await provider.getSigner();

    const token = await Web3Token.sign((msg) => signer.signMessage(msg), {
        statement: authMessage,
        domain: "loopcrypto.xyz",
    });

    console.log("Wallet Address:", accounts[0]);
    console.log("Auth Token:", token);

    const verified = Web3Token.verify(token);
    console.log("Verified Address:", verified.address);

    return token;
}

Solana Wallets

Important note when constructing signatures for Solana:

  1. Signatures should always be base64 encoded when sending in the API requests
  2. Solana wallet addresses are case sensitive and should never be lowercased when sending API requests
async function connectSolanaWallet() {
    if (!window.solana || !window.solana.isPhantom) {
        throw new Error("Phantom wallet is not installed");
    }

    const resp = await window.solana.connect();
    const walletAddress = resp.publicKey.toString();

    const message = "I accept Loop Crypto Inc's Terms of Service";
    const encodedMessage = new TextEncoder().encode(message);

    const signatureBytes = await window.solana.signMessage(
        encodedMessage,
        "utf8",
    );
    const signature = Buffer.from(signatureBytes).toString("base64");

    // Verify the signature
    const verified = nacl.sign.detached.verify(
        encodedMessage,
        Buffer.from(signature, "base64"),,
        resp.publicKey.toBytes()
    );          
  
    console.log("Signature Verified:", verified);

    return {
        walletAddress,
        signature,
        message,
    };
}

Full Web Integration Examples (React)

EVM (MetaMask) example

Create a new React project and install dependencies:

# Create new React project
npx create-react-app evm-wallet-auth-example
cd evm-wallet-auth-example

# Install dependencies
npm install ethers web3-token

Replace the contents of src/App.js with:

import { useState } from "react";
import { ethers } from "ethers";
import Web3Token from "web3-token";

function App() {
    const [token, setToken] = useState("");
    const [status, setStatus] = useState("");
    const [address, setAddress] = useState("");
    const [loading, setLoading] = useState(false);

    const authMessage = "I accept Loop Crypto Inc's Terms of Service";

    async function generateAuthToken() {
        try {
            setLoading(true);
            if (!window.ethereum) {
                throw new Error("MetaMask is not installed");
            }

            const provider = new ethers.BrowserProvider(window.ethereum);
            const accounts = await window.ethereum.request({
                method: "eth_requestAccounts",
            });
            const signer = await provider.getSigner();
            setAddress(accounts[0]);

            const token = await Web3Token.sign(
                (msg) => signer.signMessage(msg),
                {
                    statement: authMessage,
                    domain: "loopcrypto.xyz",
                },
            );

            setToken(token);
            setStatus("Token generated successfully!");

            console.log("Wallet Address:", accounts[0]);
            console.log("Auth Token:", token);

            const verified = Web3Token.verify(token);
            console.log("Verified Address:", verified.address);
        } catch (error) {
            console.error(error);
            setStatus(`Error: ${error.message}`);
        } finally {
            setLoading(false);
        }
    }

    const styles = {
        container: {
            maxWidth: "800px",
            margin: "40px auto",
            padding: "0 20px",
            fontFamily: "Arial, sans-serif",
        },
        button: {
            padding: "10px 20px",
            margin: "20px 0",
            cursor: "pointer",
            backgroundColor: "#0066cc",
            color: "white",
            border: "none",
            borderRadius: "4px",
        },
        pre: {
            backgroundColor: "#f5f5f5",
            padding: "15px",
            borderRadius: "4px",
            overflowX: "auto",
            wordWrap: "break-word",
            whiteSpace: "pre-wrap",
        },
        section: {
            marginTop: "20px",
        },
    };

    return (
        <div style={styles.container}>
            <h1>API Authentication Token Generator</h1>
            <p>
                Generate a token to authenticate with the API using your wallet.
            </p>

            <button
                onClick={generateAuthToken}
                disabled={loading}
                style={styles.button}
            >
                {loading ? "Connecting..." : "Connect Wallet & Generate Token"}
            </button>

            {address && (
                <div style={styles.section}>
                    <h3>Connected Address</h3>
                    <pre style={styles.pre}>{address}</pre>
                </div>
            )}

            {status && (
                <div style={styles.section}>
                    <h3>Status</h3>
                    <div
                        style={{
                            color: status.includes("Error")
                                ? "#dc3545"
                                : "#198754",
                        }}
                    >
                        {status}
                    </div>
                </div>
            )}

            {token && (
                <div style={styles.section}>
                    <h3>Generated Token</h3>
                    <pre style={styles.pre}>{token}</pre>
                </div>
            )}
        </div>
    );
}

export default App;

Start the development server:

npm start

Open your browser to http://localhost:3000

Solana (Phantom) example

Create a new React project and install dependencies:

# Create new React project
npx create-react-app solana-wallet-auth-example
cd solana-wallet-auth-example

# Install dependencies
npm install bs58 tweetnacl buffer

Replace the contents of src/App.js with:

import { useState } from "react";
import bs58 from "bs58";
import nacl from "tweetnacl";
import { Buffer } from "buffer";

function App() {
    const [token, setToken] = useState("");
    const [status, setStatus] = useState("");
    const [address, setAddress] = useState("");
    const [loading, setLoading] = useState(false);

    const authMessage = "I accept Loop Crypto Inc's Terms of Service";

    async function generateAuthToken() {
        try {
            setLoading(true);
            if (!window.solana || !window.solana.isPhantom) {
                throw new Error("Phantom wallet is not installed");
            }

            const resp = await window.solana.connect();
            const walletAddress = resp.publicKey.toString();
            setAddress(walletAddress);

            const encodedMessage = new TextEncoder().encode(authMessage);
            const { signature: signatureBytes } = await window.solana.request({
                method: "signMessage",
                params: {
                    message: encodedMessage,
                    display: "utf8",
                },
            });

            const signature = Buffer.from(signatureBytes).toString("base64");
            setToken(signature);
            setStatus("Signature generated successfully!");

            console.log("Wallet Address:", walletAddress);
            console.log("Signature:", signature);

            // Verify the signature
            const verified = nacl.sign.detached.verify(
                encodedMessage,
                Buffer.from(signature, "base64"),
                resp.publicKey.toBytes()
            );      
          
            console.log("Signature Verified:", verified);
        } catch (error) {
            console.error(error);
            setStatus(`Error: ${error.message}`);
        } finally {
            setLoading(false);
        }
    }

    const styles = {
        container: {
            maxWidth: "800px",
            margin: "40px auto",
            padding: "0 20px",
            fontFamily: "Arial, sans-serif",
        },
        button: {
            padding: "10px 20px",
            margin: "20px 0",
            cursor: "pointer",
            backgroundColor: "#0066cc",
            color: "white",
            border: "none",
            borderRadius: "4px",
        },
        pre: {
            backgroundColor: "#f5f5f5",
            padding: "15px",
            borderRadius: "4px",
            overflowX: "auto",
            wordWrap: "break-word",
            whiteSpace: "pre-wrap",
        },
        section: {
            marginTop: "20px",
        },
    };

    return (
        <div style={styles.container}>
            <h1>API Authentication Token Generator</h1>
            <p>
                Generate a token to authenticate with the API using your wallet.
            </p>

            <button
                onClick={generateAuthToken}
                disabled={loading}
                style={styles.button}
            >
                {loading ? "Connecting..." : "Connect Wallet & Generate Token"}
            </button>

            {address && (
                <div style={styles.section}>
                    <h3>Connected Address</h3>
                    <pre style={styles.pre}>{address}</pre>
                </div>
            )}

            {status && (
                <div style={styles.section}>
                    <h3>Status</h3>
                    <div
                        style={{
                            color: status.includes("Error")
                                ? "#dc3545"
                                : "#198754",
                        }}
                    >
                        {status}
                    </div>
                </div>
            )}

            {token && (
                <div style={styles.section}>
                    <h3>Generated Token</h3>
                    <pre style={styles.pre}>{token}</pre>
                </div>
            )}
        </div>
    );
}

export default App;

Start the development server:

npm start

Open your browser to http://localhost:3000

API Usage

Once you have generated the authorization signature from the wallet, set the authorizationSignature in the request body to this value (don't forget the authentication headers with your API keys in the headers):

// Example API call using fetch
const response = await fetch("https://api.loopcrypto.xyz/api/v2/payment-method", {
    headers: {
        "entity-id": `${entityId}`,
        "api-key": `${apiKey}`,
    },
    body: {
        ...,
        authorizationSignature: `${token}`
    }
});

Updated about 22 hours ago