Capa SDK

A TypeScript/JavaScript SDK for integrating with the Capa API v2. This SDK provides a comprehensive interface for managing cryptocurrency on-ramp and off-ramp transactions, user management, KYC verification, and more.

Installation

npm install @capa-fi/sdk

Dependencies

• Node.js >= 14
• TypeScript >= 4.0 (for TypeScript projects)

Quick Start

import { CapaV2Client } from '@capa-fi/sdk';
import { 
    fiatCurrency, 
    blockchainSymbol, 
    tokenSymbol, 
    userType, 
    transactionType, 
    transactionStatus, 
    sortOrder 
} from '@capa-fi/sdk';

// Initialize the client
const client = new CapaV2Client(
   {
    baseUrl: "https://production-api.capa.fi",
    partnerApiKey: "your-partner-api-key" 
   },
);

// Create an on-ramp transaction
const onRampRes = await client.onRamp.createPartnerOnRamp({
    userId: "your-user-id",
    fiatCurrency: fiatCurrency.DOP,
    blockchainSymbol: blockchainSymbol.SOL,
    tokenSymbol: tokenSymbol.SOL,
    fiatAmount: 100,
    destinationWalletAddress: "your-wallet-address"
});

console.log("Transaction created:", onRampRes.data?.id);

Authentication

The SDK requires a Partner API Key for authentication. You'll receive this key when you register as a partner with Capa.

const client = new CapaV2Client(
   {
    baseUrl: "https://production-api.capa.fi", // production URL
    partnerApiKey: "your-partner-api-key" // your API key
   },
);

Available Services

The SDK is organized into the following services:

Off-Ramp Service

Convert cryptocurrency to fiat currency.

// Create an off-ramp transaction
const offRampRes = await client.offRamp.createPartnerOffRamp({
    userId: "your-user-id",
    fiatCurrency: fiatCurrency.DOP,
    blockchainSymbol: blockchainSymbol.SOL,
    tokenSymbol: tokenSymbol.USDC,
    fiatAmount: 100,
    userBankInformation: {
        country: "MX",
        accountIdentifier: "123456789012345678"
    }
});

On-Ramp Service

Convert fiat currency to cryptocurrency.

// Create an on-ramp transaction
const onRampRes = await client.onRamp.createPartnerOnRamp({
    userId: "your-user-id",
    fiatCurrency: fiatCurrency.MXN,
    blockchainSymbol: blockchainSymbol.ETH,
    tokenSymbol: tokenSymbol.USDC,
    fiatAmount: 500,
    destinationWalletAddress: "your-wallet-address"
});

Quotes Service

Get exchange rates and quotes for transactions.

// Get a quote for an on-ramp transaction
const quoteRes = await client.quotes.getPartnerQuoteRate(
    tokenSymbol.USDC,        // Token symbol
    "ON_RAMP",               // Transaction type
    blockchainSymbol.ETH,    // Blockchain
    fiatCurrency.MXN,        // Fiat currency
    undefined,               // Crypto amount (optional)
    100                      // Fiat amount (optional)
);

console.log("Exchange rate:", quoteRes.data?.exchangeRate);
console.log("Estimated crypto amount:", quoteRes.data?.cryptoAmount);

Cross-Ramp Service

Convert between different fiat currencies (fiat-to-fiat conversion).

// Create a cross-ramp transaction (MXN to USD)
const crossRampRes = await client.crossRamp.createPartnerCrossRamp({
    userId: "your-user-id",
    sourceCurrency: fiatCurrency.MXN,
    targetCurrency: fiatCurrency.USD,
    sourceAmount: 1000, // 1000 MXN
    targetBankAccount: {
        country: "US",
        accountIdentifier: "1234567890"
    }
});

console.log("Transaction created:", crossRampRes.data?.id);
console.log("Exchange rate:", crossRampRes.data?.exchangeRate);
console.log("Target amount:", crossRampRes.data?.targetAmount);

// Get exchange rate for cross-ramp conversion
const crossRampQuoteRes = await client.crossRamp.getPartnerCrossRampQuoteRate(
    fiatCurrency.MXN,  // Source currency
    fiatCurrency.USD,  // Target currency
    1000,              // Source amount (optional)
    undefined,         // Target amount (optional)
    0.01              // Premium spread (optional)
);

console.log("Current exchange rate:", crossRampQuoteRes.data?.exchangeRate);
console.log("Estimated USD amount:", crossRampQuoteRes.data?.targetAmount);

// Create a quote for later use
const quoteRes = await client.crossRamp.createPartnerCrossRampQuote({
    sourceCurrency: fiatCurrency.DOP,
    targetCurrency: fiatCurrency.EUR,
    sourceAmount: 5000,
    premiumSpread: 0.005
});

console.log("Quote ID:", quoteRes.data?.id);
console.log("Quote expires at:", quoteRes.data?.expiresAt);

Users Service

Manage user accounts and profiles.

// Create a new user
const userRes = await client.users.createUser({
    type: userType.INDIVIDUAL,
    email: "[email protected]",
    externalUserId: "your-internal-user-id"
});

console.log("User created:", userRes.data?.userId);

Transactions Service

Query and manage transactions.

// List transactions using the new interface
const transactionsRes = await client.transactions.listPartnerUserTransactions({
    type: transactionType.ON_RAMP,
    fiatCurrency: fiatCurrency.MXN,
    userId: "your-user-id",
    skip: 1,
    limit: 10,
    sortBy: "createdAt",
    sortOrder: sortOrder.DESC
});

// List transactions with status filter
const pendingTransactions = await client.transactions.listPartnerUserTransactions({
    status: transactionStatus.PENDING,
    type: transactionType.ON_RAMP
});

// Cancel a transaction
const cancelRes = await client.transactions.cancelPartnerTransaction(
    "transaction-id"
);

KYC Service

Handle Know Your Customer verification processes.

// Generate a verification link for a user
const kycLinkRes = await client.kyc.generateDirectLink({
    userId: "your-user-id",
    externalUserId: "your-external-user-id",
    redirectUrl: "https://yourapp.com/verification-complete"
});

console.log("Verification URL:", kycLinkRes.data?.url);

Webhook Settings Service

Configure webhook endpoints for transaction notifications.

// Update webhook settings
const webhookRes = await client.webhookSettings.updatePartnerWebhookSettings({
    webhookUrl: "https://yourapp.com/webhook",
    enableWebhooks: true
});

Available Constants

The SDK exports several enums for use in your applications:

Supported Fiat Currencies

import { fiatCurrency } from '@capa-fi/sdk';

fiatCurrency.MXN  // Mexican Peso
fiatCurrency.DOP  // Dominican Peso

Supported Blockchains

import { blockchainSymbol } from '@capa-fi/sdk';

blockchainSymbol.ETH   // Ethereum
blockchainSymbol.SOL   // Solana
blockchainSymbol.POL   // Polygon
blockchainSymbol.BASE  // Base
blockchainSymbol.ARB   // Arbitrum
blockchainSymbol.BSC   // Binance Smart Chain
blockchainSymbol.OP    // Optimism
// ... and more

Supported Tokens

import { tokenSymbol } from '@capa-fi/sdk';

tokenSymbol.USDC    // USD Coin
tokenSymbol.USDT    // Tether
tokenSymbol.ETH     // Ethereum
tokenSymbol.SOL     // Solana
tokenSymbol.BNB     // Binance Coin
// ... and more

User Types

import { userType } from '@capa-fi/sdk';

userType.INDIVIDUAL  // Individual user
userType.BUSINESS    // Business user

Countries

import { country } from '@capa-fi/sdk';

country.MX  // Mexico
country.DO  // Dominican Republic

Complete Example

Here's a complete example showing common SDK usage patterns:

import { 
    CapaV2Client,
    CreatePartnerOffRampTransactionV2RequestBody,
    CreatePartnerUserBody,
    blockchainSymbol,
    fiatCurrency,
    tokenSymbol,
    transactionType,
    userType
} from '@capa-fi/sdk';

async function main() {
    // Initialize client
    const client = new CapaV2Client(
        {
            baseUrl: "https://production-api.capa.fi",
            partnerApiKey: "your-partner-api-key" 
        },
    );

    try {
        // 1. Create a user
        const userRes = await client.users.createUser({
            type: userType.INDIVIDUAL,
            email: "[email protected]",
            externalUserId: "unique-external-id"
        });

        const userId = userRes.data?.userId;
        if (!userId) {
            throw new Error("Failed to create user");
        }

        // 2. Get a quote
        const quoteRes = await client.quotes.getPartnerQuoteRate(
            tokenSymbol.USDC,
            "ON_RAMP",
            blockchainSymbol.ETH,
            fiatCurrency.MXN,
            undefined,
            1000 // 1000 MXN
        );

        console.log("Quote:", quoteRes.data);

        // 3. Create an on-ramp transaction
        const onRampRes = await client.onRamp.createPartnerOnRamp({
            userId,
            fiatCurrency: fiatCurrency.MXN,
            blockchainSymbol: blockchainSymbol.ETH,
            tokenSymbol: tokenSymbol.USDC,
            fiatAmount: 1000,
            destinationWalletAddress: "your-wallet-address"
        });

        console.log("On-ramp transaction:", onRampRes.data?.id);

        // 4. Create an off-ramp transaction
        const offRampRes = await client.offRamp.createPartnerOffRamp({
            userId,
            fiatCurrency: fiatCurrency.MXN,
            blockchainSymbol: blockchainSymbol.ETH,
            tokenSymbol: tokenSymbol.USDC,
            fiatAmount: 500,
            userBankInformation: {
                country: "MX",
                accountIdentifier: "012345678901234567"
            }
        });

        console.log("Off-ramp transaction:", offRampRes.data?.id);

        // 5. List user transactions
        const transactionsRes = await client.transactions.listPartnerUserTransactions({
            type: transactionType.ON_RAMP,
            fiatCurrency: fiatCurrency.MXN,
            userId: userId,
            skip: 1,
            limit: 20
        });

        console.log(`Found ${transactionsRes.data?.data?.length} transactions`);

    } catch (error) {
        console.error("Error:", error);
    }
}

main();

Error Handling

The SDK uses standard JavaScript Promises and will throw errors for failed requests. Wrap your calls in try-catch blocks:

try {
    const result = await client.onRamp.createPartnerOnRamp(requestData);
    // Handle success
} catch (error) {
    if (error.status === 400) {
        console.log("Bad request:", error.body);
    } else if (error.status === 401) {
        console.log("Authentication failed");
    } else {
        console.log("Unexpected error:", error);
    }
}

TypeScript Support

The SDK is written in TypeScript and includes full type definitions. All request and response types are exported:

import {
    CreatePartnerOnRampTransactionV2RequestBody,
    OnRampPartnerV2Response,
    GetPartnerQuoteExchangeV2Response
} from '@capa-fi/sdk';

Environment URLs

• Staging: https://staging-api.capa.fi
• Production: https://production-api.capa.fi

Support

For support, please contact the Capa Partners team or refer to the official API documentation.