Skip to content
CowriePay API

Pre-fund a sandbox wallet with test assets

POST
/sandbox/faucet
curl --request POST \
  --url https://example.com/v2/sandbox/faucet \
  --header 'Content-Type: application/json' \
  --header 'X-CowriePay-Key: <X-CowriePay-Key>' \
  --data '{ "chain": "TRON", "address": "example", "assets": [ { "symbol": "USDT_TRON", "amount": "example" } ] }'

Sandbox only. Pre-funds one of your own sandbox wallet addresses with test assets so you can exercise the deposit / balance / withdrawal flow without hunting public faucets. Requires a cpk_test_ key (a live key returns 403 FAUCET_ONLY_SANDBOX). Tokens (USDT/USDC/EURC) are generous; native gas (ETH/BNB) is rationed and opt-in, request it only to test a native deposit. The drip is queued and dispatched on-chain; it then arrives as a normal deposit (with its usual webhooks). address must be one of your sandbox wallets.

LIMITS. Mock tokens are minted by CowriePay, so they are cheap; native currency is farmed from public testnet faucets and is the scarce resource, so it is what the limits actually bound. One drip may carry a bounded number of assets, each asset at most once. Native carries a ROLLING PER-ASSET BUDGET per workspace, and is released only once your workspace has at least one confirmed sandbox token deposit: in a custodial WaaS model CowriePay funds the gas for sweeps and withdrawals, so you never need native to move tokens. Each limit has its own error code (see the 422 below).

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
chain
required

Base protocol; the network is your key’s (cpk_test_ = testnet).

string
Allowed values: TRON BSC ETH
address
required

One of your sandbox wallet addresses on this chain.

string
assets
required
Array<object>
>= 1 items
object
symbol
required
string
Allowed values: USDT_TRON USDT_BSC USDT_ETH USDC_ETH EURC_ETH ETH BNB
amount

Whole asset units (trailing zeros optional; “1000” == “1000.000000”); omit to use the per-asset default. Capped per asset.

string

Responses

Section titled “Responses”

202

Section titled “202”

Drip accepted; assets are dispatched on-chain and will arrive as a deposit.

Media typeapplication/json
object
drip_id
string
status
string
chain
string
address
string
items
Array<object>
object
asset
string
amount
string
status
string
Examplegenerated
{
  "drip_id": "example",
  "status": "example",
  "chain": "example",
  "address": "example",
  "items": [
    {
      "asset": "example",
      "amount": "example",
      "status": "example"
    }
  ]
}

400

Section titled “400”

Validation error (bad asset/amount).

403

Section titled “403”

Live key used (code FAUCET_ONLY_SANDBOX) or insufficient scope.

422

Section titled “422”

Each limit has its OWN code, so you can tell which one stopped you. FAUCET_ADDRESS_NOT_FOUND the address is not a sandbox wallet of your workspace. FAUCET_AMOUNT_OVER_CAP one item exceeds the per-asset cap. FAUCET_TOO_MANY_ITEMS the drip requests more assets than a single drip may carry. FAUCET_DUPLICATE_ASSET an asset appears twice; request it once with the total amount. FAUCET_NATIVE_REQUIRES_DEPOSIT native (ETH/BNB) is released once your workspace has at least one confirmed sandbox TOKEN deposit. Drip a token first and let it confirm. You do not need native to move tokens: CowriePay funds the gas for sweeps and withdrawals. FAUCET_NATIVE_BUDGET_EXCEEDED your rolling native budget for that asset is spent; the message carries how much of it is used and over what window. FAUCET_RATE_LIMITED too many drip REQUESTS in the window (a coarse secondary limit). FAUCET_DISPENSER_EXHAUSTED OUR side, not yours: the sandbox dispenser is out of the chain’s native currency and cannot fund this drip (a token drip still costs us gas to send). Retry later, or request token assets only. Every other code above is something you can act on; this one is on us, and our team is alerted when it starts firing.