Skip to main content
Network issues can cause requests to time out before you receive a response. Without idempotency, retrying a request could result in duplicate transfers, double trades, or repeated liquidity operations. Knot supports idempotency keys to ensure that retrying a request has no additional effect if the original succeeded.

​
Using idempotency keys

Include the Idempotency-Key header with a unique string identifier on any financial operation: 
curl -X POST https://api.useknot.xyz/wallets/me/actions/transfer \
  -H "Authorization: Bearer <token>" \
  -H "Idempotency-Key: transfer-abc123-1234567890" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "RecipientAddress...",
    "amount": 100,
    "mint": "USDC"
  }'
Use a key that includes context about the operation — such as the recipient, amount, and a timestamp — to make it easy to trace later.

​
How it works

1

First request

The request is processed normally. The response is cached against the idempotency key.
2

Duplicate request

If the same key is sent within 24 hours, the cached response is returned immediately — the operation is not re-executed.
3

Different key

A new key is always treated as a new request and processed normally.

​
Duplicate response

When Knot detects a duplicate request, it returns the cached original response with an indicator: 
{
  "status": true,
  "statusCode": 200,
  "message": "Request already processed (idempotent).",
  "data": {
    "cached": true,
    "originalResponse": {
      "signature": "5UfgJ3vN...",
      "explorerUrl": "https://solscan.io/tx/5UfgJ3vN...",
      "amount": "100 USDC"
    }
  }
}
Idempotency keys are cached for 24 hours. After that window, the same key is treated as a new request.

​
Key generation strategies

Choose a strategy that produces unique, traceable keys:

​
UUID-based

import uuid
idempotency_key = f"transfer-{uuid.uuid4()}"

​
Operation-based

# Includes operation details to prevent logical duplicates
idempotency_key = f"transfer-{recipient}-{amount}-{timestamp}"

​
Hash-based

import hashlib
content = f"{recipient}:{amount}:{timestamp}"
idempotency_key = hashlib.sha256(content.encode()).hexdigest()[:32]

​
When to use a new key

ScenarioUse same key?Reason
Network timeout during requestYesThe request may have succeeded — safe to retry with the same key
5xx error responseNoThe request failed — safe to retry with a new key
4xx error responseNoThe request was rejected — fix the issue before retrying
Intentional new operationNoThis is a distinct operation

​
Best practices

Always use for financial operations

All transfers, trades, and liquidity operations should include idempotency keys.

Generate unique keys

Use UUIDs, timestamps, or content hashes to ensure each key is unique.

New key for retries

When retrying after a non-timeout error, always generate a fresh idempotency key.

Include operation context

Embed operation details in the key to make it easier to trace and debug.