Create payout withdrawal

curl --request POST \
  --url https://api.skinshark.gg/user/wallet/payout/crypto/withdraw \
  --header 'Content-Type: application/json' \
  --header 'api-key: <api-key>' \
  --data '
{
  "destination": "<string>",
  "amountCents": "<string>",
  "externalId": "<string>",
  "forSubUser": "<string>",
  "maxFeeUsdCents": "<string>"
}
'

{
  "requestId": "<string>",
  "success": true,
  "data": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "chain": "<string>",
    "token": "<string>",
    "destination": "<string>",
    "amountCents": "<string>",
    "feeCents": "<string>",
    "externalId": "<string>",
    "forUserId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "forUserExternalId": "<string>",
    "createdAt": "2023-11-07T05:31:56Z"
  },
  "error": {
    "code": 1500,
    "key": "INSUFFICIENT_BALANCE",
    "message": "Insufficient balance"
  }
}

Partner Payout Custody

Create payout withdrawal

Auth context: merchant — API key only (JWT not accepted; this is the one write endpoint in the payout group). Requires cryptoPayoutEnabled=true, a provisioned webhook signing secret, and at least one active CallbackUrl registered for the merchant.

Idempotent on externalId. Retrying the same externalId returns the original withdrawal unchanged (idempotent replay) — it never double-spends or errors. The 1824 conflict is only returned on a genuine concurrent duplicate racing the first create.

Withdrawals are per (chain, token), not from a single pool. SkinShark does not hold cross-chain liquidity. You can only withdraw from a chain × token combination you previously deposited to. Depositing USDC on Base and asking to withdraw USDC on Ethereum will fail with 1822 CRYPTO_PAYOUT_INSUFFICIENT_BALANCE even if you have plenty of USDC on Base. Use GET /payout/crypto/balances to see what’s withdrawable on each chain.

Flow:

Live fee computed; rejected with 1821 if maxFeeUsdCents is set and the live fee exceeds it. No state mutated.
Atomic transaction: sidecar decremented by amountCents + liveFeeUsdCents (rejected with 1822 if insufficient), payout_withdraw_lock ledger posting, withdrawal row created in pending_callback.
Synchronous approval call: a signed POST of type payout.crypto.withdraw.approval is sent to your CallbackUrl (5s timeout), separate from the async lifecycle queue. Return 2xx to approve (release funds) or 4xx to reject. The request carries webhook-id, webhook-timestamp, and webhook-signature headers — the signature is always present (payouts require a provisioned signing secret), so verify it before acting.
On 2xx → queued → broadcast → confirmed. On 4xx → immediate refund. On 5xx/timeout/network → retry up to 3 times, then refund. Any rejection, failure, or on-chain revert resolves to the single terminal status refunded.
Lifecycle events (payout.crypto.withdraw.broadcast, .confirmed, and the single terminal .refunded) are delivered asynchronously via the standard signed webhook queue. There is no separate .failed delivery.

POST

user

wallet

payout

crypto

withdraw

Create payout withdrawal

curl --request POST \
  --url https://api.skinshark.gg/user/wallet/payout/crypto/withdraw \
  --header 'Content-Type: application/json' \
  --header 'api-key: <api-key>' \
  --data '
{
  "destination": "<string>",
  "amountCents": "<string>",
  "externalId": "<string>",
  "forSubUser": "<string>",
  "maxFeeUsdCents": "<string>"
}
'

{
  "requestId": "<string>",
  "success": true,
  "data": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "chain": "<string>",
    "token": "<string>",
    "destination": "<string>",
    "amountCents": "<string>",
    "feeCents": "<string>",
    "externalId": "<string>",
    "forUserId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "forUserExternalId": "<string>",
    "createdAt": "2023-11-07T05:31:56Z"
  },
  "error": {
    "code": 1500,
    "key": "INSUFFICIENT_BALANCE",
    "message": "Insufficient balance"
  }
}

Authorizations

api-key

string

header

required

Your raw API key. Generate, rotate, and revoke keys from the merchant dashboard. Keys can optionally be bound to one or more allowed source IPs — requests from any other IP are rejected with API_KEY_IP_DENIED.

Body

application/json

chain

enum<string>

required

Available options:

ethereum,

base,

arbitrum,

optimism,

bsc

token

enum<string>

required

Stables only at MVP.

Available options:

USDT,

USDC

destination

string

required

EVM address that will receive the funds on-chain.

Pattern: ^0x[a-fA-F0-9]{40}$

amountCents

string

required

USD cents to send to the destination. Fee is added on top and debited together.

Pattern: ^\d+$

externalId

string

required

Partner-supplied reference. Echoed in the approval callback and all lifecycle events so you can match against your own records. Must be unique per merchant; duplicate ⇒ 1824.

Required string length: 1 - 128

forSubUser

string

Optional label — sub-user id (UUID) or your externalId for that sub-user, scoped to the calling merchant. Pure label, not auth scope: funding always comes from the merchant's payout custody; the sub-user reference is recorded for audit and echoed in the approval callback / lifecycle events.

Required string length: 1 - 128

maxFeeUsdCents

string

Optional fee cap. If the live fee at submission exceeds this cap, the request is rejected with 1821 and no state is mutated. Useful for declining high-gas moments.

Pattern: ^\d+$

Response

OK.

requestId

string

required

success

boolean

required

data

object

Present when success: true. Shape varies per endpoint.

Show child attributes

error

object

Show child attributes

Quote payout withdrawal List payout withdrawals