Skip to content
CowriePay API

Use the SDKs

CowriePay ships three official SDKs. They exist so you never hand-write the HMAC signing recipe, and so the API reference maps one-to-one onto your code.

Language Package Install
Node / TypeScript @cowriepay/sdk npm install @cowriepay/sdk
Python cowriepay pip install cowriepay
PHP cowriepay/cowriepay-php composer require cowriepay/cowriepay-php

Three properties they share, by design:

  • Zero runtime dependencies. Each SDK uses only its language’s standard library; nothing else enters your supply chain.
  • Server-side only. The API secret signs requests, so it must never reach a browser or a mobile app. There is no client-side build, on purpose.
  • Method names are the API reference’s operationIds. The reference page for Create a deposit wallet is createWallet; in the SDKs it is wallets.create under the matching resource namespace. What you read is what you call, and those names are a stable contract.

The shape, in Node

Section titled “The shape, in Node”
import { CowriePay } from '@cowriepay/sdk';


const cowriepay = new CowriePay({
  apiKey: process.env.CPK_KEY,      // cpk_test_... or cpk_live_...
  apiSecret: process.env.CPK_SECRET,
});


const wallet = await cowriepay.wallets.create(
  { chain: 'TRON', asset: 'USDT_TRON', external_ref: 'order_12345' },
  { idempotencyKey: crypto.randomUUID() },
);


const { data: deposits } = await cowriepay.transactions.listDeposits({ status: 'CONFIRMED' });
const balances = await cowriepay.transactions.balances();

Signing, timestamps, body hashing and retries are handled inside; idempotency keys are a first-class option on mutating calls. The Python and PHP READMEs carry the same walkthrough in their own idiom.

Errors are typed, and the code travels

Section titled “Errors are typed, and the code travels”

A failed call raises a typed error carrying the same code the raw API returns (plus the HTTP status and a request id for support). Branch on the code exactly as the error catalogue prescribes; the SDK adds types, never a different contract.

Webhook verification is included

Section titled “Webhook verification is included”

Each SDK verifies webhook signatures against the raw request body, and accepts an array of secrets so a secret rotation (old and new overlapping) verifies cleanly:

const event = CowriePay.verifyWebhook({
  payload: rawBody,
  signatureHeader: req.headers['x-cowriepay-signature'],
  timestamp: req.headers['x-cowriepay-timestamp'],
  secrets: [currentSecret, previousSecret].filter(Boolean),
});

When the SDK does not cover it yet

Section titled “When the SDK does not cover it yet”

Every SDK exposes a signed escape hatch (cowriepay.request({ method, path, body }) in Node) that signs any path with the same recipe. A brand-new endpoint is usable the day it ships, before the SDK catches up.

Prefer Postman?

Section titled “Prefer Postman?”

A ready-to-sign Postman collection is generated from the same published spec:

  1. In Postman, choose Import, then Link, and paste https://docs.cowriepay.io/cowriepay.postman_collection.json.
  2. On the imported collection, open the Variables tab and fill hmac_key_id and hmac_secret with an API key from your dashboard.
  3. Send. A collection-level pre-request script computes the HMAC signature on every call, and the key prefix decides Sandbox versus Live as everywhere else.

The same collection is also browsable on the Postman Public API Network; fork it into your own workspace, then fill the two variables there. Wherever it comes from, never put your key in a public or shared workspace.

What next

Section titled “What next”