SDK Documentation

Official ClawPay SDKs for TypeScript, Python, and Go.

Installation

TypeScript/JavaScript

npm install @clawpay/sdk
# or
yarn add @clawpay/sdk
# or
pnpm add @clawpay/sdk

Requirements: Node.js 16+ or modern browsers

Python

pip install clawpay

Requirements: Python 3.8+

Go

go get github.com/ClawPay-app/go-sdk

Requirements: Go 1.19+

TypeScript SDK

Initialization

import { ClawPay } from '@clawpay/sdk';

const client = new ClawPay({
  apiKey: process.env.CLAWPAY_API_KEY,
  environment: 'production', // or 'sandbox'
  timeout: 30000, // optional, in milliseconds
  maxRetries: 3 // optional, default: 3
});

Vaults

// Create vault
const vault = await client.vaults.create({
  name: 'Company Treasury',
  currency: 'USDC',
  network: 'solana',
  initialDeposit: 10000
});

// List vaults
const vaults = await client.vaults.list({
  limit: 10,
  currency: 'USDC'
});

// Get vault
const vault = await client.vaults.retrieve('vault_123');

// Update vault
await client.vaults.update('vault_123', {
  name: 'Updated Name'
});

// Freeze vault
await client.vaults.freeze('vault_123');

// Get balance
const balance = await client.vaults.getBalance('vault_123');

Cards

// Create card
const card = await client.cards.create({
  vaultId: 'vault_123',
  cardholderName: 'John Doe',
  spendingLimit: {
    daily: 1000,
    monthly: 25000
  }
});

// List cards
const cards = await client.cards.list({
  vaultId: 'vault_123',
  status: 'active'
});

// Reveal card details (requires 2FA if enabled)
const details = await client.cards.reveal('card_123');
console.log(details.number, details.cvv);

// Freeze card
await client.cards.freeze('card_123');

// Cancel card
await client.cards.cancel('card_123');

Transactions

// List transactions
const transactions = await client.transactions.list({
  vaultId: 'vault_123',
  limit: 50,
  status: 'completed'
});

// Get transaction
const txn = await client.transactions.retrieve('txn_123');

// Get transaction metadata (ZK-encrypted)
const metadata = await client.transactions.getMetadata('txn_123');

Transfers

// Internal transfer
const transfer = await client.transfers.create({
  sourceVaultId: 'vault_123',
  destinationVaultId: 'vault_456',
  amount: 5000,
  currency: 'USDC',
  memo: 'Q1 Budget'
});

// External transfer
const externalTransfer = await client.transfers.createExternal({
  sourceVaultId: 'vault_123',
  destinationAddress: '9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin',
  amount: 1000,
  currency: 'USDC',
  network: 'solana'
});

Authorization Policies

// Set policy
await client.vaults.setAuthorizationPolicy('vault_123', {
  type: 'whitelist_only',
  dailyLimit: 5000,
  currency: 'USDC',
  merchants: ['amazon.com', 'vercel.com'],
  zkProofRequired: true
});

// Get policy
const policy = await client.vaults.getAuthorizationPolicy('vault_123');

// Delete policy
await client.vaults.deleteAuthorizationPolicy('vault_123');

Webhooks

// Create webhook
const webhook = await client.webhooks.create({
  url: 'https://api.yourcompany.com/webhooks',
  events: ['transaction.completed', 'card.declined']
});

// Verify webhook signature
import { ClawPay } from '@clawpay/sdk';

const event = ClawPay.webhooks.verify(
  requestBody,
  signature,
  webhookSecret
);

Error Handling

try {
  const vault = await client.vaults.retrieve('vault_123');
} catch (error) {
  if (error instanceof ClawPay.errors.NotFoundError) {
    console.error('Vault not found');
  } else if (error instanceof ClawPay.errors.AuthenticationError) {
    console.error('Invalid API key');
  } else if (error instanceof ClawPay.errors.RateLimitError) {
    console.error('Rate limit exceeded');
  } else {
    console.error('Unexpected error:', error.message);
  }
}

TypeScript Types

Full TypeScript support with auto-completion:

import type {
  Vault,
  Card,
  Transaction,
  AuthorizationPolicy
} from '@clawpay/sdk';

const vault: Vault = await client.vaults.create({
  name: 'Treasury',
  currency: 'USDC',
  network: 'solana'
});

Python SDK

Initialization

from clawpay import ClawPay

client = ClawPay(
    api_key=os.environ.get('CLAWPAY_API_KEY'),
    environment='production',
    timeout=30,
    max_retries=3
)

Vaults

# Create vault
vault = client.vaults.create(
    name='Company Treasury',
    currency='USDC',
    network='solana',
    initial_deposit=10000.0
)

# List vaults
vaults = client.vaults.list(limit=10, currency='USDC')

# Get vault
vault = client.vaults.retrieve('vault_123')

# Update vault
client.vaults.update('vault_123', name='Updated Name')

# Get balance
balance = client.vaults.get_balance('vault_123')
print(f"Available: {balance.available} {balance.currency}")

Cards

# Create card
card = client.cards.create(
    vault_id='vault_123',
    cardholder_name='John Doe',
    spending_limit={
        'daily': 1000,
        'monthly': 25000
    }
)

# List cards
cards = client.cards.list(vault_id='vault_123', status='active')

# Reveal card details
details = client.cards.reveal('card_123')
print(f"Card: {details.number}, CVV: {details.cvv}")

# Freeze card
client.cards.freeze('card_123')

Transactions

# List transactions
transactions = client.transactions.list(
    vault_id='vault_123',
    limit=50,
    status='completed'
)

for txn in transactions:
    print(f"{txn.merchant.name}: ${txn.amount}")

# Get transaction
txn = client.transactions.retrieve('txn_123')

Transfers

# Internal transfer
transfer = client.transfers.create(
    source_vault_id='vault_123',
    destination_vault_id='vault_456',
    amount=5000.0,
    currency='USDC',
    memo='Q1 Budget'
)

# External transfer
external = client.transfers.create_external(
    source_vault_id='vault_123',
    destination_address='9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin',
    amount=1000.0,
    currency='USDC',
    network='solana'
)

Authorization Policies

# Set policy
client.vaults.set_authorization_policy('vault_123', {
    'type': 'whitelist_only',
    'daily_limit': 5000,
    'currency': 'USDC',
    'merchants': ['amazon.com', 'vercel.com'],
    'zk_proof_required': True
})

# Get policy
policy = client.vaults.get_authorization_policy('vault_123')

Webhooks

# Create webhook
webhook = client.webhooks.create(
    url='https://api.yourcompany.com/webhooks',
    events=['transaction.completed', 'card.declined']
)

# Verify webhook signature
from clawpay import verify_webhook

try:
    event = verify_webhook(request.body, signature, webhook_secret)
    print(f"Event type: {event.type}")
except ValueError:
    print("Invalid signature")

Error Handling

from clawpay.errors import (
    NotFoundError,
    AuthenticationError,
    RateLimitError
)

try:
    vault = client.vaults.retrieve('vault_123')
except NotFoundError:
    print("Vault not found")
except AuthenticationError:
    print("Invalid API key")
except RateLimitError as e:
    print(f"Rate limit exceeded. Retry after {e.retry_after}s")
except Exception as e:
    print(f"Unexpected error: {e}")

Go SDK

Initialization

import "github.com/ClawPay-app/go-sdk"

client := clawpay.NewClient(&clawpay.Config{
    APIKey:      os.Getenv("CLAWPAY_API_KEY"),
    Environment: "production",
    Timeout:     30 * time.Second,
    MaxRetries:  3,
})

Vaults

// Create vault
vault, err := client.Vaults.Create(&clawpay.VaultCreateParams{
    Name:           "Company Treasury",
    Currency:       "USDC",
    Network:        "solana",
    InitialDeposit: 10000.0,
})
if err != nil {
    log.Fatal(err)
}

// List vaults
vaults, err := client.Vaults.List(&clawpay.VaultListParams{
    Limit:    10,
    Currency: "USDC",
})

// Get vault
vault, err := client.Vaults.Retrieve("vault_123")

// Get balance
balance, err := client.Vaults.GetBalance("vault_123")
fmt.Printf("Available: %.2f %s\n", balance.Available, balance.Currency)

Cards

// Create card
card, err := client.Cards.Create(&clawpay.CardCreateParams{
    VaultID:        "vault_123",
    CardholderName: "John Doe",
    SpendingLimit: &clawpay.SpendingLimit{
        Daily:   1000,
        Monthly: 25000,
    },
})

// List cards
cards, err := client.Cards.List(&clawpay.CardListParams{
    VaultID: "vault_123",
    Status:  "active",
})

// Reveal card details
details, err := client.Cards.Reveal("card_123")
fmt.Printf("Card: %s, CVV: %s\n", details.Number, details.CVV)

// Freeze card
err = client.Cards.Freeze("card_123")

Transactions

// List transactions
transactions, err := client.Transactions.List(&clawpay.TransactionListParams{
    VaultID: "vault_123",
    Limit:   50,
    Status:  "completed",
})

for _, txn := range transactions {
    fmt.Printf("%s: $%.2f\n", txn.Merchant.Name, txn.Amount)
}

// Get transaction
txn, err := client.Transactions.Retrieve("txn_123")

Transfers

// Internal transfer
transfer, err := client.Transfers.Create(&clawpay.TransferCreateParams{
    SourceVaultID:      "vault_123",
    DestinationVaultID: "vault_456",
    Amount:             5000.0,
    Currency:           "USDC",
    Memo:               "Q1 Budget",
})

// External transfer
external, err := client.Transfers.CreateExternal(&clawpay.ExternalTransferParams{
    SourceVaultID:        "vault_123",
    DestinationAddress:   "9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin",
    Amount:               1000.0,
    Currency:             "USDC",
    Network:              "solana",
})

Authorization Policies

// Set policy
err = client.Vaults.SetAuthorizationPolicy("vault_123", &clawpay.AuthorizationPolicy{
    Type:             "whitelist_only",
    DailyLimit:       5000,
    Currency:         "USDC",
    Merchants:        []string{"amazon.com", "vercel.com"},
    ZKProofRequired:  true,
})

// Get policy
policy, err := client.Vaults.GetAuthorizationPolicy("vault_123")

Webhooks

// Create webhook
webhook, err := client.Webhooks.Create(&clawpay.WebhookCreateParams{
    URL:    "https://api.yourcompany.com/webhooks",
    Events: []string{"transaction.completed", "card.declined"},
})

// Verify webhook signature
event, err := clawpay.VerifyWebhook(requestBody, signature, webhookSecret)
if err != nil {
    http.Error(w, "Invalid signature", http.StatusUnauthorized)
    return
}
fmt.Printf("Event type: %s\n", event.Type)

Error Handling

vault, err := client.Vaults.Retrieve("vault_123")
if err != nil {
    switch e := err.(type) {
    case *clawpay.NotFoundError:
        log.Println("Vault not found")
    case *clawpay.AuthenticationError:
        log.Println("Invalid API key")
    case *clawpay.RateLimitError:
        log.Printf("Rate limit exceeded. Retry after %d seconds", e.RetryAfter)
    default:
        log.Printf("Unexpected error: %v", err)
    }
}

SDK Support

Versioning

SDKs follow semantic versioning. Check your current version:

# TypeScript
npm list @clawpay/sdk

# Python
pip show clawpay

# Go
go list -m github.com/ClawPay-app/go-sdk

Updates

Stay up to date with the latest SDK releases:

# TypeScript
npm update @clawpay/sdk

# Python
pip install --upgrade clawpay

# Go
go get -u github.com/ClawPay-app/go-sdk

Source Code

SDKs are open source:

TypeScript: github.com/ClawPay-app/typescript-sdk
Python: github.com/ClawPay-app/python-sdk
Go: github.com/ClawPay-app/go-sdk

Community SDKs

Community-maintained SDKs:

Ruby: clawpay-ruby
PHP: clawpay-php
Rust: clawpay-rs

Note: Community SDKs are not officially supported.

Next Steps

PreviousError Codes NextAuthorization Engine

Last updated 1 hour ago

Good evening

hashtagInstallation

hashtagTypeScript/JavaScript

hashtagPython

hashtagGo

hashtagTypeScript SDK

hashtagInitialization

hashtagVaults

hashtagCards

hashtagTransactions

hashtagTransfers

hashtagAuthorization Policies

hashtagWebhooks

hashtagError Handling

hashtagTypeScript Types

hashtagPython SDK

hashtagInitialization

hashtagVaults

hashtagCards

hashtagTransactions

hashtagTransfers

hashtagAuthorization Policies

hashtagWebhooks

hashtagError Handling

hashtagGo SDK

hashtagInitialization

hashtagVaults

hashtagCards

hashtagTransactions

hashtagTransfers

hashtagAuthorization Policies

hashtagWebhooks

hashtagError Handling

hashtagSDK Support

hashtagVersioning

hashtagUpdates

hashtagSource Code

hashtagCommunity SDKs

hashtagNext Steps

Installation

TypeScript/JavaScript

Python

Go

TypeScript SDK

Initialization

Vaults

Cards

Transactions

Transfers

Authorization Policies

Webhooks

Error Handling

TypeScript Types

Python SDK

Initialization

Vaults

Cards

Transactions

Transfers

Authorization Policies

Webhooks

Error Handling

Go SDK

Initialization

Vaults

Cards

Transactions

Transfers

Authorization Policies

Webhooks

Error Handling

SDK Support

Versioning

Updates

Source Code

Community SDKs

Next Steps