Idempotency

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

First request

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

Duplicate request

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

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

Scenario	Use same key?	Reason
Network timeout during request	Yes	The request may have succeeded — safe to retry with the same key
`5xx` error response	No	The request failed — safe to retry with a new key
`4xx` error response	No	The request was rejected — fix the issue before retrying
Intentional new operation	No	This 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.

Getting Started

Core Features

Security & Policies

Advanced

Using idempotency keys

How it works

Duplicate response

Key generation strategies

UUID-based

Operation-based

Hash-based

When to use a new key

Best practices

Always use for financial operations

Generate unique keys

New key for retries

Include operation context

​Using idempotency keys

​How it works

​Duplicate response

​Key generation strategies

​UUID-based

​Operation-based

​Hash-based

​When to use a new key

​Best practices

Always use for financial operations

Generate unique keys

New key for retries

Include operation context

Using idempotency keys

How it works

Duplicate response

Key generation strategies

UUID-based

Operation-based

Hash-based

When to use a new key

Best practices