Knit API Documentation
Create a single Payout
{{baseUrl}}/api/v1/payoutsSupported Networks
- BITCOIN_MAINNET: For operations on the Bitcoin main network.
- ETHEREUM_MAINNET: For activities on the Ethereum main network.
- MATIC_MAINNET: For activities on the Polygon main network
- TRON_MAINNET: For activities on the Tron main network
Headers
- Authentication:
Authorization: Bearer <token>(preferred) or the legacyX-API-KEY: {{apiKey}}. - Accept:
application/json
Prerequisites
- API Account funded:
POST /api/v1/business-api-services-walletscreates the wallet, but you still need to move funds from the business wallet into it (see the dashboard transfer action). If the selected token balance is lower than theamount, the API responds with400 Insufficient balance. - IP Whitelist: both API keys and OAuth clients inherit the business whitelist. Requests from non-approved IPs are rejected before they reach the controller.
- Valid crypto address: Knit validates
toAddressper network using theValidCryptoAddressRule. Invalid checksums or formats produce a422validation error.
Validation & Defaults
| Field | Notes |
|---|---|
network | Must be one of MATIC_MAINNET, TRON_MAINNET, BSC_MAINNET, SOL_MAINNET. |
token | Currently USDT or USDC. |
amount | Minimum 0.01. Use token decimals (not fiat). |
toAddress | Checked against the per-chain format; invalid values block the request. |
merchantReference | Optional but recommended for idempotency. If supplied it must be unique in api_payouts. |
When the request passes validation the service persists the payout as PENDING,
kicks off KnitCore settlement, and stores the caller’s IP address for auditing.
Request Body
{
"network": "MATIC_MAINNET",
"token": "USDT",
"amount": 0.02,
"toAddress": "0x56adfcc254ab3b8142a275c1837bcffaff5aa38b"
}Sample Request
curl --location -g '{{baseUrl}}/api/v1/payouts' \
--header 'X-API-KEY: {{apiKey}}' \
--header 'Accept: application/json' \
--data '{
"network": "MATIC_MAINNET",
"token": "USDT",
"amount": 0.02,
"toAddress": "0x56adfcc254ab3b8142a275c1837bcffaff5aa38b"
}'Sample Response
Sample Response
{
"success": true,
"message": "Payout created successfully",
"status": 201,
"data": {
"amount": 0.02,
"token": "USDT",
"toAddress": "0x56adfcc254ab3b8142a275c1837bcffaff5aa38b",
"network": "MATIC_MAINNET",
"userId": "8286065b-577e-11ef-9218-96f5ee698dcd",
"payoutWalletId": "5c7bb5bd-acb5-453a-9eb9-11380a329d79",
"id": "8e5697e3-8265-455b-984a-0eb40e10b0f9",
"updatedAt": "2024-08-27T13:44:20.000000Z",
"createdAt": "2024-08-27T13:44:20.000000Z"
}
}
##### Status Lifecycle & Webhooks
- `PENDING` → initial state after creation.
- `COMPLETED` → KnitCore confirms on-chain success; triggers a
`PAYOUT_SUCCESSFUL` webhook (see the Webhooks section for payload format) and
the listener skips delivery if the payout isn’t completed.
- `FAILED` → KnitCore or blockchain errors; check dashboard logs and retry with
a new payout ID (the service does not auto-retry failed payouts).
Webhook payloads are camelCased and signed with your business webhook secret via
`X-Signature`. Use that signature plus your stored secret to verify integrity.