Knit API Documentation

Create A Collection

{{baseUrl}}/api/v1/collections

Supported 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 legacy X-API-KEY: {{apiKey}}. See Authentication for details.
• Accept: Set to application/json to receive responses in JSON format.

Prerequisites & Behavior

• Each collection is a single-use address that expires 30 minutes after creation. After expiry you must create a new collection.
• Knit automatically creates/looks up the KnitCore user for your business, so the only required fields are the ones in the body above.
• merchantCallbackUrl is stored as metadata and echoed back via webhook events so you can reconcile requests on your side.

Event Timeline

1. CollectionCreatedEvent fires immediately; you can observe it on the dashboard.
2. When KnitCore detects on-chain funds, CollectionSuccessfulEvent credits the API account via ApiAccountTransaction.
3. If confirmation thresholds are not met or the transfer fails, a collectionFailed webhook is emitted (see the Webhooks section).

Every webhook payload is camelCased and signed with your business secret key.

Request Body

{
  "network": "MATIC_MAINNET",
  "token": "USDT",
  "tokenAmount": 2500,
  "confirmationThreshold": 10,
  "merchantRedirectUrl": "https://example.com/test",
  "merchantCallbackUrl": "https://webhook.site/34b47e03-38ac-4040-a6fc-3dcb44a922e9"
}

Sample Request

curl --location -g '{{baseUrl}}/api/v1/collections' \
--header 'X-API-KEY: {{apiKey}}' \
--header 'Accept: application/json' \
--data '{
    "network": "POLYGON_MAINNET",
    "token": "USDT",
    "tokenAmount": 0.1,
    "merchantRedirectUrl": "https://example.com",
    "merchantCallbackUrl": "https://example.com"
}'

Sample Response

{
  "success": true,
  "message": "Collection created successfully",
  "status": 201,
  "data": {
    "network": "MATIC_MAINNET",
    "token": "USDT",
    "address": "0x3761f3504104f4faa8959963a5d8dce89989d45b",
    "status": "PENDING",
    "tokenToUsd": 1,
    "feeInUsd": 0,
    "feeByToken": 0,
    "expiresAt": "2024-08-27T14:02:10.000000Z",
    "tokenAmountRequested": 2500,
    "tokenAmount": 2500,
    "confirmationThreshold": 10,
    "merchantCallbackUrl": "https://example.com",
    "id": "9cddd3ad-c2a8-463c-a703-158b900beea8",
    "updatedAt": "2024-08-27T13:32:10.000000Z",
    "createdAt": "2024-08-27T13:32:10.000000Z",
    "paymentLinkUrl": "https://checkout-dev.collection.useknit.io/9cddd3ad-c2a8-463c-a703-158b900beea8"
  }
}