DOCSEARCHbyAlgolia
Submit Docs

Cobrex API Documentation

website·Indexed 30 days ago

https://docs.cobrex.com

A crypto platform for merchants providing APIs for processing payments via fixed-amount invoices or static wallets, managing payouts from merchant or user accounts, and tracking balances. Features include HMAC signature authentication, webhooks for status changes, and a public asset catalog for network and limit verification.

Tokens
14.2K
Snippets
64
Records
103
Agent score
47%

What's inside Cobrex

  1. Overview of Cobrex API capabilities

    Cobrex is a crypto platform for businesses to store funds and manage crypto payments. The API allows developers to:

    • Manage accounts: Separate personal and business funds or create dedicated accounts for trading and savings.
    • Delegate access: Grant limited account access to other users via the Cobrex dashboard.
    • Accept payments: Implement fixed invoices and static customer addresses.
    • Send payouts: Execute payouts from merchant-linked accounts or specific accounts using the x-uid identifier.
    • Receive notifications: Set up webhooks to trigger actions when payment or payout statuses change.

  2. Cobrex API Base URL and Request Format

    The Cobrex API uses the following base endpoint and format:

    • Endpoint: https://api.cobrex.com
    • Format: All requests and responses use JSON (Content-Type: application/json for requests with a body).
    • API Keys: Manageable via the dashboard settings.

  3. Handle Cobrex Webhooks for Payments and Payouts

    Cobrex provides webhooks to notify your system about payment and payout events. To ensure the security and authenticity of incoming webhook requests, you must implement IP address verification and validate the request signature.

  4. Cobrex API Base URL and Format

    The Cobrex API uses the following base endpoint and data format:

    • Endpoint: https://api.cobrex.com
    • Format: Both requests and responses use JSON. For requests with a body, use Content-Type: application/json.
    • API Keys: Keys can be generated in the panel settings at https://app.cobrex.com/settings.

  5. Cobrex API Overview and Capabilities

    Cobrex is a crypto platform designed for storing funds and managing business crypto payments. The API allows developers to perform the following core tasks:

    • Account Management: Separate personal and business funds, and create dedicated accounts for savings or trading.
    • Payment Acceptance: Create fixed invoices and static addresses for clients.
    • Fund Payouts: Execute payouts from a merchant-linked account or a specific account identified by x-uid.
    • Notifications: Implement webhooks to receive real-time updates when payment or payout statuses change.

  6. Get started with Cobrex API requests

    To make your first request to the Cobrex API, you will need the Base URL, three specific request headers, and an HMAC signature for authentication.

  7. Cobrex Payout Object Field Reference

    The Cobrex Payout object provides detailed information about a payout operation, including merchant details, asset rail information, on-chain transaction hashes, and a financial breakdown of fees and amounts sent.
    {
  "payout_id": "o-2b72159c-8495-472f-a7f9-7d49721864bb",
  "internal_id": "22c21d78-0155-49d9-9e39-cd1d99b5f846",
  "user_id": "u-7027b0e7-a192-47c6-9082-de8e4049d85a",
  "merchant": {
    "merchant_id": "m-e2dbcd50-6b5c-4d2a-97dd-153beb2a1abe",
    "name": "test",
    "url": "https://test.com",
    "fees_on": 0
  },
  "asset": {
    "name": "Tether SOL",
    "asset": "USDT",
    "network": "SOL"
  },
  "txs": [
    {
      "hash": "w23BtR9eX2MyCJniJ6uq15tSGJV3yooxAFiY5QGjDVjYPi4nPBzg3SzwJMXicLKHh3sypr3h7t9eJWKN13aj4av",
      "sender": "QWUF8QGDf1Msd3cYhLkDnkjtFZwK6BTqaamus2dDMi7",
      "confirmations": 2
    }
  ],
  "address": "QWUF8QGDf1Msd3cYhLkDnkjtFZwK6BTqaamus2dDMi7",
  "client": "743859",
  "amount": "2.000000000000000000",
  "hash": "w23BtR9eX2MyCJniJ6uq15tSGJV3yooxAFiY5QGjDVjYPi4nPBzg3SzwJMXicLKHh3sypr3h7t9eJWKN13aj4av",
  "details": {
    "sent": "1.700000000000000000",
    "withdrawn": "2.000000000000000000",
    "fees_on": 1,
    "fee": "0.000000000000000000",
    "network_fee": "0.300000000000000000",
    "total_fees": "0.300000000000000000",
    "usdt": "2.000000000000000000"
  },
  "status": {
    "final": false,
    "code": "PENDING",
    "substatus": "CREATED"
  },
  "created_at": "2026-05-03T08:09:13.000Z",
  "paid_at": null,
  "canceled_at": null
}

  8. Initiate fund transfers using the Cobrex Payouts API

    The Cobrex Payouts API allows you to send funds using two different sourcing methods:

    1. Merchant-linked account: Specify the merchant ID using the x-mid header.
    2. Explicit user account: Specify the user ID using the x-uid header and provide the specific account identifier in the request body.

  9. Cobrex API Authentication and Request Basics

    To make requests to the Cobrex API, you need the Base URL, three specific HTTP headers, and an HMAC signature for authentication. The API supports two modes of operation: acting as a user (using the x-uid header) or acting as a merchant (using the x-mid header) to manage payments, payouts, and balances.

  10. Cobrex Payout Object Field Reference

    The Cobrex payout object contains detailed information about a payment operation, including merchant data, asset details, on-chain transaction hashes, and financial breakdowns.

    Core Identifiers

    • payout_id (string): Unique Cobrex payout ID (starts with o-).
    • internal_id (string): Your internal operation ID used for deduplication and accounting.
    • user_id (string): Cobrex user ID (starts with u-).
    • client (string): Your client identifier.

    Merchant Information (merchant object)

    • merchant_id (string): Merchant ID (starts with m-).
    • name (string): Merchant name.
    • url (string): Merchant URL.
    • fees_on (number): Default commission setting.

    Asset & Network (asset object)

    • name (string): Full asset name (e.g., 'Tether SOL').
    • asset (string): Asset ticker (e.g., 'USDT').
    • network (string): Network name (e.g., 'SOL').

    Transaction Details

    • address (string): Recipient address.
    • amount (string): Payout amount as a fixed-precision string.
    • hash (string): Main transaction hash.
    • txs (array): List of on-chain transactions, each containing:
      • hash (string): Blockchain transaction hash.
      • sender (string): Sender address (Cobrex wallet or intermediary).
      • confirmations (number): Number of network confirmations.

    Financial Breakdown (details object)

    • sent (string): Amount sent to the recipient.
    • withdrawn (string): Amount debited from the balance.
    • fees_on (number): Who pays the commission (0 = merchant, 1 = user).
    • fee (string): Service commission.
    • network_fee (string): Network fee.
    • total_fees (string): Sum of all commissions.
    • usdt (string): USDT equivalent.

    Status & Timestamps

    • status (object):
      • final (boolean): Whether the payout is finalized.
      • code (string): Status code (PENDING, SUCCESS, FAIL).
      • substatus (string): Detailed status (e.g., CREATED).
    • created_at (string): Creation timestamp in ISO 8601 format.
    • paid_at (string | null): Completion/sending time according to Cobrex.
    • canceled_at (string | null): Cancellation timestamp, if applicable.
    {
  "payout_id": "o-2b72159c-8495-472f-a7f9-7d49721864bb",
  "internal_id": "22c21d78-0155-49d9-9e39-cd1d99b5f846",
  "user_id": "u-7027b0e7-a192-47c6-9082-de8e4049d85a",
  "merchant": {
    "merchant_id": "m-e2dbcd50-6b5c-4d2a-97dd-153beb2a1abe",
    "name": "test",
    "url": "https://test.com",
    "fees_on": 0
  },
  "asset": {
    "name": "Tether SOL",
    "asset": "USDT",
    "network": "SOL"
  },
  "txs": [
    {
      "hash": "w23BtR9eX2MyCJniJ6uq15tSGJV3yooxAFiY5QGjDVjYPi4nPBzg3SzwJMXicLKHh3sypr3h7t9eJWKN13aj4av",
      "sender": "QWUF8QGDf1Msd3cYhLkDnkjtFZwK6BTqaamus2dDMi7",
      "confirmations": 2
    }
  ],
  "address": "QWUF8QGDf1Msd3cYhLkDnkjtFZwK6BTqaamus2dDMi7",
  "client": "743859",
  "amount": "2.000000000000000000",
  "hash": "w23BtR9eX2MyCJniJ6uq15tSGJV3yooxAFiY5QGjDVjYPi4nPBzg3SzwJMXicLKHh3sypr3h7t9eJWKN13aj4av",
  "details": {
    "sent": "1.700000000000000000",
    "withdrawn": "2.000000000000000000",
    "fees_on": 1,
    "fee": "0.000000000000000000",
    "network_fee": "0.300000000000000000",
    "total_fees": "0.300000000000000000",
    "usdt": "2.000000000000000000"
  },
  "status": {
    "final": false,
    "code": "PENDING",
    "substatus": "CREATED"
  },
  "created_at": "2026-05-03T08:09:13.000Z",
  "paid_at": null,
  "canceled_at": null
}

  11. Cobrex Payment Object Reference

    The Cobrex API and webhooks provide a payment object containing details about the transaction, merchant, asset, and processing status. This object is returned during API queries and sent via webhooks when a payment status changes.
    {
  "payment_id": "p-1a9a67a1-46ce-11f1-8b35-7cc255316480",
  "user_id": "u-96bada25-a20f-49d6-99e9-5893d0769af2",
  "merchant": {
    "merchant_id": "m-ca33fcbe-317f-47fb-bf3a-520827816658",
    "name": "Cobrex",
    "url": "https://cobrex.com",
    "fees_on": 0
  },
  "asset": {
    "name": "Tether USDT TRC-20",
    "asset": "USDT",
    "network": "TRON"
  },
  "txs": [
    {
      "hash": "b9ccd188fa62c4cad987088b25085ee3783fbae8d0884a1d2b416878b99d51ac",
      "sender": "TU4vEruvZwLLkSfV9bNw12EJTPvNr7Pvab",
      "confirmations": 18
    }
  ],
  "client": "743858",
  "address": "TV9jGGXR4SCPGnRMP77pvurBWE5SMjjjvA",
  "amount": "75.000000000000000000",
  "details": {
    "credited": "74.925000000000000000",
    "fee": "0.075000000000000000",
    "network_fee": "0.000000000000000000",
    "total_fees": "0.075000000000000000",
    "usdt": "75.000000000000000000"
  },
  "status": {
    "final": true,
    "code": "SUCCESS",
    "substatus": "PAID"
  },
  "created_at": "2026-05-03T08:57:24.000Z",
  "updated_at": "2026-05-03T08:58:19.000Z",
  "paid_at": "2026-05-03T08:58:19.000Z",
  "canceled_at": null
}

  12. Generate the canonical string for API request signing

    To create the x-signature, you must first build a canonical string following these steps:

    1. Full request URL: The exact URL called, including protocol, host, path, and query string (if any). Query parameters must be in the exact order sent in the request.
    2. Line feed: Add a newline character (\n).
    3. Timestamp: The same whole-second Unix timestamp used in the x-timestamp header.
    4. Request Body (Optional): If the request has a body (e.g., POST):
      • Add another newline character (\n).
      • Append the raw body bytes (the exact string result of JSON.stringify). Whitespace and key order must match the actual body sent.

    Note: For GET requests (no body), stop after step 3. Do not add a trailing newline for an empty body.

    // POST Example Canonical String:
https://api.cobrex.com/wallet
1752675847
{"asset":["USDT","TRX"],"network":"TRON","client":"test1","callback":"https://api.cobrex.com/webhook"}

// GET Example Canonical String:
https://api.cobrex.com/payment/p-1a9a67a1-46ce-11f1-8b35-7cc255316480
1752675847