API Documentation

Overview

The Trust Card API allows developers to programmatically interact with the Trust Cryptocurrency Card platform. You can manage cards, retrieve transaction history, connect wallets, fetch real-time exchange rates, and receive event notifications via webhooks.

All API requests must be made over HTTPS. HTTP requests are not supported and will be rejected. The API uses RESTful conventions with JSON request and response bodies.

Authentication

All API requests require authentication using a Bearer token. To obtain a token, call the POST /auth/token endpoint with your API key and secret. Include the token in the Authorization header of all subsequent requests:

Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5...

API keys and secrets can be generated and managed from the Developer section of your Trust Card dashboard. Keep your API secret confidential — never expose it in client-side code or public repositories.

Access tokens expire after 3600 seconds (1 hour). Your application should implement token refresh logic using the POST /auth/token endpoint before expiry to maintain uninterrupted access.

Rate Limiting

API requests are rate-limited to protect system stability. Standard accounts are allowed 100 requests per minute. Business accounts are allowed 1,000 requests per minute. Rate limit information is included in response headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1741700460

If you exceed the rate limit, you will receive a 429 Too Many Requests response. Implement exponential backoff in your application to handle rate limit responses gracefully.

Error Handling

The API uses standard HTTP status codes. Errors are returned as JSON objects with a code and message field:

{
  "error": {
    "code": "CARD_NOT_FOUND",
    "message": "No card found with the provided ID.",
    "request_id": "req_8mNpKq"
  }
}

Common status codes: 200 OK — request succeeded; 201 Created — resource created; 400 Bad Request — invalid parameters; 401 Unauthorized — invalid or missing token; 403 Forbidden — insufficient permissions; 404 Not Found — resource not found; 422 Unprocessable Entity — validation error; 429 Too Many Requests — rate limit exceeded; 500 Internal Server Error — server error.

Endpoints

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5...",
  "token_type": "Bearer",
  "expires_in": 3600
}

{
  "cards": [
    {
      "id": "card_9xK2mP",
      "type": "virtual",
      "status": "active",
      "last_four": "4242",
      "created_at": "2026-01-15T08:30:00Z",
      "spending_limit": 1000.00,
      "currency": "USD"
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}

{
  "card_id": "card_9xK2mP",
  "status": "frozen",
  "frozen_at": "2026-03-11T14:22:00Z"
}

{
  "card_id": "card_9xK2mP",
  "status": "active",
  "unfrozen_at": "2026-03-11T14:25:00Z"
}

{
  "transactions": [
    {
      "id": "txn_7hGpQr",
      "card_id": "card_9xK2mP",
      "amount_fiat": 49.99,
      "currency_fiat": "USD",
      "amount_crypto": 0.00071,
      "currency_crypto": "BTC",
      "exchange_rate": 70407.00,
      "conversion_fee": 0.50,
      "merchant_name": "Amazon",
      "merchant_category": "retail",
      "status": "completed",
      "created_at": "2026-03-10T11:45:00Z"
    }
  ],
  "total": 142,
  "limit": 50,
  "offset": 0
}

{
  "wallets": [
    {
      "id": "wallet_3nRt1X",
      "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
      "currency": "ETH",
      "balance": 2.4812,
      "balance_usd": 9180.44,
      "network": "ethereum"
    }
  ]
}

{
  "rates": {
    "BTC": { "USD": 70407.00, "EUR": 64980.50, "GBP": 55620.00 },
    "ETH": { "USD": 3697.80, "EUR": 3412.10, "GBP": 2921.40 },
    "SOL": { "USD": 185.40, "EUR": 171.10, "GBP": 146.50 }
  },
  "updated_at": "2026-03-11T14:30:00Z"
}

{
  "webhook_id": "wh_5kNmBv",
  "url": "https://yourapp.com/webhooks/trust",
  "events": ["transaction.completed", "card.frozen"],
  "active": true,
  "created_at": "2026-03-11T09:00:00Z"
}

Webhook Events

Webhook payloads are signed using HMAC-SHA256 with the secret you provide. Verify the signature by computing HMAC-SHA256(payload_body, your_secret) and comparing it to the value in the X-Trust-Signature header. Always verify signatures before processing webhook payloads.

Webhooks are retried up to 5 times with exponential backoff if your endpoint returns a non-2xx status code. After 5 failures, the webhook is marked as failed and you will be notified by email.

Respond to webhook requests within 10 seconds to prevent timeout. If your processing takes longer, return a 200 immediately and process the event asynchronously.

SDK Libraries

We provide official SDK libraries to simplify API integration in popular programming languages. All SDKs are open-source and available on GitHub.

JavaScript / Node.js: npm install @trustcard/sdk

Python: pip install trustcard-sdk

PHP: composer require trustcard/sdk

Ruby: gem install trustcard

Support

For API-related questions or issues, contact our developer support team at developers@trust-card.space. Include your API key (never your secret), the request ID from the error response, and a description of the issue. We typically respond within 4 business hours.