Quickstart

Five steps to a credited deposit, entirely in the Sandbox, without leaving your terminal. You need your cpk_test_ key and its secret; if you do not have them yet, start with Create your account and get your keys. Every request below is signed per the Authentication guide.

Step 1: Create a deposit wallet

Call POST /v2/wallets to generate a dedicated deposit address. Send the base protocol (TRON, BSC, ETH) as chain; the network is taken from your API key (cpk_test_ = testnet, cpk_live_ = mainnet), so you never send it. The response echoes the full resolved chain.

Request:

{
  "chain": "TRON",
  "asset": "USDT_TRON",
  "external_ref": "order_12345"
}

Response:

{
  "id": "a1b2c3d4-0000-0000-0000-000000000001",
  "chain": "TRON_TESTNET",
  "asset": "USDT_TRON",
  "address": "TExampleWalletAddress1234567890ABC",
  "status": "ACTIVE",
  "created_at": "2026-08-09T10:00:00.000Z"
}

Store the id against your own order or user record: it is how you will tie incoming deposits back to whatever they pay for.

Step 2: Register a webhook

Call POST /v2/webhooks so deposit events reach your application. Any HTTPS endpoint you control works; for a first run, a request-inspection tunnel to your machine does the job.

Request:

{
  "url": "https://your-app.example.com/webhooks/cowriepay",
  "events": ["DEPOSIT_DETECTED", "DEPOSIT_CONFIRMED", "DEPOSIT_SWEPT"]
}

Response:

{
  "id": "b2c3d4e5-0000-0000-0000-000000000002",
  "url": "https://your-app.example.com/webhooks/cowriepay",
  "events": ["DEPOSIT_DETECTED", "DEPOSIT_CONFIRMED", "DEPOSIT_SWEPT"],
  "is_active": true,
  "created_at": "2026-08-09T10:01:00.000Z",
  "secret": "9f8e7d6c5b4a39281706f5e4d3c2b1a09f8e7d6c5b4a39281706f5e4d3c2b1a0"
}

Step 3: Fund the wallet with the faucet

No test tokens to find, no public faucet to hunt: ask the built-in faucet to pre-fund the address from Step 1. Call POST /v2/sandbox/faucet:

Request:

{
  "chain": "TRON",
  "address": "TExampleWalletAddress1234567890ABC",
  "assets": [{ "symbol": "USDT_TRON" }]
}

Response (202):

{
  "drip_id": "d4e5f6a7-0000-0000-0000-000000000004",
  "status": "PENDING",
  "chain": "TRON",
  "address": "TExampleWalletAddress1234567890ABC",
  "items": [
    { "asset": "USDT_TRON", "amount": "1000", "status": "PENDING" }
  ]
}

The faucet sends a real on-chain transaction to your address. Because it arrives as a completely normal deposit, what happens next is exactly what happens with a real customer.

Step 4: Watch the deposit confirm, then credit

Within moments your endpoint receives DEPOSIT_DETECTED (the transaction was seen on-chain), then, once the confirmation threshold is reached, DEPOSIT_CONFIRMED:

{
  "event": "DEPOSIT_CONFIRMED",
  "created_at": "2026-08-09T10:10:00.000Z",
  "data": {
    "deposit_id": "c3d4e5f6-0000-0000-0000-000000000003",
    "workspace_id": "11111111-0000-0000-0000-000000000000",
    "wallet_id": "a1b2c3d4-0000-0000-0000-000000000001",
    "chain": "TRON_TESTNET",
    "asset": "USDT_TRON",
    "amount": "1000.000000",
    "txid": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890ab",
    "status": "CONFIRMED",
    "confirmations": 19,
    "required_confirmations": 19,
    "detected_at": "2026-08-09T10:05:00.000Z",
    "confirmed_at": "2026-08-09T10:10:00.000Z"
  }
}

Credit your customer on DEPOSIT_CONFIRMED, never on DEPOSIT_DETECTED: a detected transaction can still disappear in a reorganisation (the why is in On-chain concepts). Use data.wallet_id to find your order via the mapping from Step 1, and render progress with confirmations / required_confirmations rather than hard-coding a threshold.

Congratulations: you have received and credited your first deposit, end to end, on a real chain.

Step 5: The same flow, with a real customer

With a real customer nothing changes except who sends the funds: display the wallet address, the customer sends the amount due, and the webhooks of Step 4 fire exactly the same way. Later, DEPOSIT_SWEPT tells you the funds were consolidated to custody and your balance was credited net of fees, with the fee breakdown in the payload.

When you are ready for real money, Going live is the checklist: same host, same code, a cpk_live_ key, and the security controls that come with it.

What next

The sandbox and the faucet: limits, native currency, and what the Sandbox deliberately does not simulate.
Webhooks: signature verification, retries, and the deduplication contract.
Error codes: what failures look like, and which ones to retry.