Frequently Asked Questions

Find answers to the most common questions about Card Market API.

Getting Started

How do I get access to the API?

To get access to Card Market API:

Sign up for a developer account at developers.cardmarket.com
Complete the verification process
Generate your API key from the developer dashboard
Start making API calls using your key

What's the difference between API Key and Bearer Token authentication?

API Key (X-API-KEY): Used for server-to-server authentication and developer access. Provides elevated permissions and is ideal for backend services.
Bearer Token (Authorization: Bearer): Used for user session authentication. Obtained through the login endpoint and represents a specific user's session.

Is there a sandbox environment for testing?

Yes! We provide a sandbox environment at https://sandbox-api.market.decenctype.com where you can test your integration without affecting real data or transactions.

Rate Limits & Quotas

What are the rate limits?

Rate limits vary by plan:

Developer: 1,000 requests/hour, 10 concurrent connections
Pro: 10,000 requests/hour, 50 concurrent connections
Enterprise: 100,000 requests/hour, 200 concurrent connections

How do I handle rate limiting in my application?

Implement exponential backoff when you receive a 429 Too Many Requests response:

async function makeRequestWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options);
    
    if (response.status !== 429) {
      return response;
    }
    
    const retryAfter = response.headers.get('Retry-After') || Math.pow(2, i);
    await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
  }
  
  throw new Error('Max retries exceeded');
}

Can I request higher rate limits?

Yes! Contact our support team at support@cardmarket.com with details about your use case, and we'll review your request.

Authentication & Security

How do I keep my API keys secure?

Follow these best practices:

Never commit API keys to version control
Use environment variables to store keys
Rotate keys regularly
Use different keys for different environments
Never expose keys in client-side code

Can I use the API from a browser/frontend application?

For security reasons, API keys should not be used in frontend applications. Instead:

Implement user authentication in your backend
Use Bearer tokens for frontend API calls
Proxy sensitive API calls through your backend server

How long do Bearer tokens last?

Bearer tokens expire after 24 hours by default. You can refresh them using the /auth/refresh endpoint or by having users log in again.

API Usage

How do I handle pagination?

Most list endpoints support pagination with page and limit parameters:

const response = await fetch('https://api.market.decenctype.com/orders?page=1&limit=50', {
  headers: { 'Authorization': 'Bearer your-token' }
});

const data = await response.json();
console.log(`Page ${data.page} of ${data.totalPages}`);
console.log(`${data.items.length} items out of ${data.total} total`);

What's the maximum page size for list endpoints?

The maximum limit value is 100 items per page. We recommend using smaller page sizes (20-50) for better performance.

How do I filter and sort results?

Many endpoints support filtering and sorting parameters:

// Filter orders by status and sort by creation date
const url = 'https://api.market.decenctype.com/orders?status=completed&sortBy=createdAt&sortOrder=desc';

Check each endpoint's documentation for available filter and sort options.

Webhooks

Do you support webhooks?

Yes! Webhooks allow you to receive real-time notifications about events in your account. You can configure them in your developer dashboard.

How do I verify webhook signatures?

Verify webhook authenticity using the signature header:

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
    
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

Available webhook events include:

user.created - New user registration
order.created - New order placed
order.completed - Order fulfilled
transaction.confirmed - Payment confirmed
kyc.approved - KYC verification approved
kyc.rejected - KYC verification rejected

Error Handling

What do the different HTTP status codes mean?

200 - Success
201 - Created successfully
400 - Bad request (invalid parameters)
401 - Unauthorized (invalid or missing authentication)
403 - Forbidden (valid auth but insufficient permissions)
404 - Not found
429 - Too many requests (rate limited)
500 - Internal server error

How should I handle API errors?

Always check the response status and handle errors appropriately:

async function handleApiCall(url, options) {
  try {
    const response = await fetch(url, options);
    const data = await response.json();
    
    if (!response.ok) {
      throw new Error(`API Error: ${data.error?.message || response.statusText}`);
    }
    
    if (!data.success) {
      throw new Error(data.error?.message || 'Request failed');
    }
    
    return data.data;
  } catch (error) {
    console.error('API call failed:', error);
    throw error;
  }
}

Why am I getting a 403 Forbidden error?

A 403 error means your authentication is valid but you don't have permission for that resource. This can happen if:

You're trying to access another user's data
Your API key doesn't have the required permissions
The endpoint requires a different authentication method

Most financial transactions are irreversible once confirmed. However, some operations like order cancellations may be possible within a short time window. Check the specific endpoint documentation for details.

How do I track transaction status?

Use the transaction ID to poll the transaction status:

async function waitForConfirmation(transactionId) {
  while (true) {
    const transaction = await api.transactions.get(transactionId);
    
    if (transaction.status === 'confirmed') {
      return transaction;
    } else if (transaction.status === 'failed') {
      throw new Error('Transaction failed');
    }
    
    // Wait 5 seconds before checking again
    await new Promise(resolve => setTimeout(resolve, 5000));
  }
}

What cryptocurrencies do you support?

Currently supported cryptocurrencies:

USDT (Tether)
USDC (USD Coin)
ETH (Ethereum)
BTC (Bitcoin)

More currencies may be added in the future.

Technical Support

Where can I find code examples?

Code examples are available:

In this documentation for each endpoint
In our GitHub examples repository
In the interactive API explorer
In our official SDKs

How do I report a bug or request a feature?

You can:

Create an issue on the relevant GitHub repository
Contact support at support@cardmarket.com
Join our Discord community for real-time discussion
Use the feedback form in your developer dashboard

❓ Frequently Asked Questions