> ## Documentation Index
> Fetch the complete documentation index at: https://docs.afkcrypto.com/llms.txt
> Use this file to discover all available pages before exploring further.

# AFK API v1

> AFK Crypto API v1 का अवलोकन और कन्वेंशंस

## अवलोकन

* बेस पाथ: `/api/v1`
* प्रमाणीकरण: `x-api-key` हेडर के जरिए API कुंजी
* आइडेम्पोटेंसी: लिखने वाले ऑपरेशन्स के लिए `Idempotency-Key` हेडर (UUID फॉर्मेट) आवश्यक
* प्रतिक्रिया प्रारूप: सभी प्रतिक्रियाओं में ट्रैकिंग हेतु `x-request-id` हेडर शामिल

### एंडपॉइंट्स

* `GET /api/v1/wallets` – उपयोगकर्ता वॉलेट सूची
* `GET /api/v1/wallets/balances` – कॉलर के वॉलेट के बैलेंस (चेन के अनुसार; डिफॉल्ट वॉलेट)
* `GET /api/v1/wallets/:address/balances` – किसी स्वामित्व वाले पते के बैलेंस
* `GET /api/v1/tx/:id` – ट्रांज़ैक्शन विवरण
* `POST /api/v1/send` – नेटिव/टोकन भेजें (EVM + Solana)
* `POST /api/v1/token/approve` – ERC20 टोकन अप्रूवल (EVM)
* `POST /api/v1/contracts/send` – जनरल कॉन्ट्रैक्ट इंटरैक्शन (EVM)
* `POST /api/v1/trade/quote` – स्वैप कोट्स (EVM + Solana)
* `POST /api/v1/trade/swap` – स्वैप निष्पादित करें (EVM + Solana)

## चेन्स

[समर्थित चेन्स](/api-reference/supported-chains/) में पूरी सूची देखें। `chain` स्लग का उपयोग करें (जैसे `base`, `solana-devnet`).

## रेट लिमिटिंग

* **लिखना** (`POST /api/v1/trade/quote` सहित): प्रति उपयोगकर्ता प्रति मिनट 15 अनुरोध
* **पढ़ना**: प्रति उपयोगकर्ता प्रति मिनट 60 अनुरोध
* प्रतिक्रिया: सीमा पार होने पर HTTP 429
* हेडर्स: `Retry-After` (अगली विंडो तक सेकंड)

## आइडेम्पोटेंसी (लिखाई)

* सभी म्यूटेटिंग एंडपॉइंट्स पर `Idempotency-Key` आवश्यक।
* समान रिक्वेस्ट बॉडी के साथ key दोहराने पर मूल 200 प्रतिक्रिया मिलती है।
* भिन्न बॉडी के साथ key दोहराने पर HTTP 409 मिलता है और `code: IDEMPOTENT_BODY_MISMATCH`।
* बिना सहेजी सफलता के key दोहराने पर HTTP 409 और `code: IDEMPOTENT_REPLAY`।
* keys प्रमाणित यूज़र के स्कोप में होती हैं; एंडपॉइंट पाथ रिकॉर्ड किया जाता है।
* लागू: `POST /api/v1/send`, `POST /api/v1/token/approve`, `POST /api/v1/contracts/send`, `POST /api/v1/trade/swap`।

## त्रुटि प्रबंधन

### त्रुटि प्रतिक्रिया प्रारूप

```json theme={null}
{
  "error": "पठनीय त्रुटि संदेश",
  "code": "ERROR_CODE",
  "requestId": "unique-request-id"
}
```

### त्रुटि कोड

* `UNAUTHORIZED` – प्रमाणीकरण गायब/अमान्य या API कुंजी (HTTP 401)
* `FORBIDDEN` – प्रमाणित लेकिन कार्रवाई के लिए अनुमति नहीं (HTTP 403)
* `NOT_FOUND` – संसाधन नहीं मिला (HTTP 404)
* `RATE_LIMITED` – रेट सीमा पार (HTTP 429)
* `INVALID_INPUT` – अमान्य अनुरोध पैरामीटर (HTTP 400)
* `WALLET_NOT_FOUND` – निर्दिष्ट वॉलेट नहीं मिला
* `USER_NOT_LINKED` – उपयोगकर्ता Privy से लिंक नहीं
* `WALLET_NOT_DELEGATED` – वॉलेट सर्वर साइनर को डेलिगेट नहीं
* `WALLET_ID_REQUIRED` – Privy वॉलेट ID गायब
* `CHAIN_UNKNOWN` – अज्ञात या असमर्थित चेन
* `INSUFFICIENT_FUNDS` – भेजने वाले के पास मूल्य/शुल्क के लिए फंड कम
* `IDEMPOTENT_BODY_MISMATCH` – समान आइडेम्पोटेंसी key के साथ भिन्न रिक्वेस्ट बॉडी (HTTP 409)
* `IDEMPOTENT_REPLAY` – आइडेम्पोटेंसी key पहले से उपयोग में (HTTP 409)
* `PRIVY_RPC_ERROR` – Privy RPC सेवा त्रुटि
* `SEND_FAILED` – ट्रांज़ैक्शन सबमिशन विफल
* `SERVICE_UNAVAILABLE` – आवश्यक सेवा कॉन्फ़िगर नहीं
* `QUOTE_FAILED` – कोट सेवा त्रुटि (HTTP 400)
* `INTERNAL_ERROR` – सर्वर त्रुटि

<Note>
  **QUOTE\_FAILED विवरण:**

  * **Solana/Jupiter**: कुछ Solana mints Jupiter पर व्यापार योग्य नहीं (क्यूरेटेड allowlist)। ऐसे मामलों में, यह API HTTP 400 के साथ `code: QUOTE_FAILED` और त्रुटि संदेश जैसे: "Token not tradable on Jupiter" लौटाता है।
  * **EVM/1inch**: यदि टोकन 1inch द्वारा समर्थित नहीं है, तो API HTTP 400 के साथ `code: QUOTE_FAILED` और संदेश जैसे: "Token not tradable on 1inch" लौटाता है।
  * जब अनुरोधित आउटपुट टोकन/mint को अपस्ट्रीम प्रदाता द्वारा non-tradable चिह्नित किया गया हो तो यह अपेक्षित व्यवहार है, भले ही अन्य जगहों पर pools मौजूद हों।
</Note>

## वेलिडेशन

### एड्रेस फॉर्मेट्स

* EVM: `/^0x[a-fA-F0-9]{40}$/` से मेल
* Solana: वैध base58 पब्लिक की

### कॉमन पैरामीटर्स

* **अमाउंट (EVM)**: केवल integer स्ट्रिंग्स (decimal या 0x-hex). non-negative होनी चाहिए। ERC20 और `value` के लिए uint256 में फिट होनी चाहिए।
* **अमाउंट (Solana)**: base यूनिट्स में integer स्ट्रिंग्स। SPL अमाउंट्स unsigned 64-bit रेंज में होने चाहिए।
* **भेजने वाला (`from`)**: वैकल्पिक। न देने पर निर्दिष्ट चेन के लिए यूज़र का डिफ़ॉल्ट वॉलेट उपयोग होता है।
* **आइडेम्पोटेंसी**: सभी write एंडपॉइंट्स को `Idempotency-Key` हेडर चाहिए। समान बॉडी के साथ दोहराव मूल प्रतिक्रिया लौटाता है।

### नेटिव टोकन कीवर्ड

ट्रेड एंडपॉइंट्स (`/api/v1/trade/quote`, `/api/v1/trade/swap`) `fromToken`/`toToken` के लिए case-insensitive `NATIVE` कीवर्ड स्वीकार करते हैं:

* **EVM**: `NATIVE` को `0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE` में रिज़ॉल्व किया जाता है
* **Solana**: `NATIVE` को wrapped SOL mint `So11111111111111111111111111111111111111112` में रिज़ॉल्व किया जाता है
* प्रतिक्रियाएँ रिज़ॉल्व किए गए एड्रेस लौटाती हैं (`NATIVE` नहीं)
* send एंडपॉइंट नेटिव ट्रांसफर्स के लिए टोकन एड्रेस के बजाय `asset: "native"` का उपयोग करता है

## कन्वेंशंस

* चेन चयन: `chain` स्लग का उपयोग करें (उदा., `base`, `base-sepolia`, `solana-devnet`).
* Solana `Transaction.chainId` सेंटिनल मैपिंग: `0` = mainnet, `-2` = testnet, `-3` = devnet।
* आइडेम्पोटेंसी: यूज़र/कुंजी के अनुसार अद्वितीय; रिप्ले → मूल प्रतिक्रिया; बॉडी असंगति → 409।

## संबंधित

<CardGroup cols={2}>
  <Card title="समर्थित चेन्स" icon="link-simple" href="/api-reference/supported-chains/" />

  <Card title="नीतियाँ और सुरक्षा" icon="shield" href="/api-reference/policies-security/" />
</CardGroup>