{ "openapi": "3.1.0", "info": { "title": "TurkDex TEST API", "version": "0.1.0", "description": "Chain 1919 only. Single-pool V2/V3 quotes and indexed V4 keys. No hosted Uniswap API dependency. No server signing/broadcast. No USD peg assurance, reserve verification, or redemption service is provided by these endpoints. Read-only Connect compatibility methods serve only static chain-1919 metadata, identity USD conversion, empty unpriced token results, and empty notifications. Compliance methods remain fail-closed while policy is unconfigured. The chain-1919 /permissions compatibility endpoint reports non-permissioned only because no permissioned adapter is configured in this TurkDex deployment; it is not a sanctions or geographic compliance check." }, "servers": [ { "url": "https://dexapi.turkscan.com/stage", "description": "Public TurkDex read-only stage API" }, { "url": "http://127.0.0.1:12919", "description": "Private server-local test API" } ], "paths": { "/health/live": { "get": { "summary": "Process liveness", "responses": { "200": { "description": "API process is running" } } } }, "/health/ready": { "get": { "summary": "Fresh chain-1919 RPC readiness; separate from full product readiness", "responses": { "200": { "description": "Fresh RPC head" }, "503": { "description": "Stale chain" } } } }, "/v1/tokens": { "get": { "summary": "TURKCHAIN token catalog with explicit valuation provenance", "responses": { "200": { "description": "Configured chain-1919 token metadata; USD valuation is unverified unless derived from verified on-chain pools." } } } }, "/v1/contracts": { "get": { "summary": "Contract address registry and verification status", "responses": { "200": { "description": "Chain-1919 addresses" } } } }, "/v1/catalog": { "get": { "summary": "Persisted V2/V3/V4 pool-discovery catalog and backfill checkpoint", "responses": { "200": { "description": "Partial or complete confirmed catalog; completeness is explicit" } } } }, "/v1/pools": { "get": { "summary": "Direct V2/V3 factory pools plus indexed V4 pool keys", "parameters": [ { "name": "tokenA", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } }, { "name": "tokenB", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } } ], "responses": { "200": { "description": "Live factory pools; V4 catalog is separate" }, "400": { "description": "Invalid address" } }, "description": "Discovers direct V2/V3 pools from on-chain factories and matching V4 pool keys from the local indexed PoolManager catalog. A V4 key is not a guarantee of a safe quote; use /v1/quote to simulate through V4Quoter." } }, "/v1/quote": { "post": { "summary": "Read-only direct-pool quote across V2/V3 and indexed V4 keys by default; no route is represented by best:null", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "Successful direct-pool quote; pools lists V2/V3 factory discoveries and matching indexed V4 keys. Only simulated routes are included in routes." }, "400": { "description": "Invalid request or wrong chain" }, "422": { "description": "No verified route, where applicable" }, "429": { "description": "Rate limit" }, "502": { "description": "RPC or simulation failure" }, "503": { "description": "Stale chain" } }, "description": "When protocols is omitted, direct quotes search V2, V3, and indexed V4 pool keys. Split and multi-hop routes are not yet implemented." } }, "/v1/swap-transaction": { "post": { "summary": "Unsigned calldata, runtime-code and canonical-block checks; user-wallet broadcast only", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "chainId", "walletAddress", "recipient", "tokenIn", "tokenOut", "amountIn", "expectedProtocol", "expectedPool", "expectedMinimumAmountOut", "quoteValidUntil" ], "properties": { "chainId": { "type": "integer", "const": 1919 }, "walletAddress": { "type": "string", "description": "Signing wallet; the API never signs or broadcasts." }, "recipient": { "type": "string", "description": "On-chain token recipient; may differ from walletAddress." }, "tokenIn": { "type": "string" }, "tokenOut": { "type": "string" }, "amountIn": { "type": "string", "pattern": "^[0-9]+$" }, "expectedProtocol": { "type": "string", "enum": [ "V2", "V3", "V4" ] }, "expectedPool": { "type": "string" }, "expectedMinimumAmountOut": { "type": "string", "pattern": "^[0-9]+$" }, "quoteValidUntil": { "type": "integer" } } } } } }, "responses": { "200": { "description": "Successful result" }, "400": { "description": "Invalid request or wrong chain" }, "422": { "description": "No verified route, where applicable" }, "429": { "description": "Rate limit" }, "502": { "description": "RPC or simulation failure" }, "503": { "description": "Stale chain" } } } }, "/v1/approval-plan": { "post": { "summary": "Exact approval plan with zero-first reset; recheck actual allowance before signing", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "Successful result" }, "400": { "description": "Invalid request or wrong chain" }, "422": { "description": "No verified route, where applicable" }, "429": { "description": "Rate limit" }, "502": { "description": "RPC or simulation failure" }, "503": { "description": "Stale chain" } } } }, "/v1/simulate": { "post": { "summary": "Verified USDT token eth_call simulation; no state persistence", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "Successful result" }, "400": { "description": "Invalid request or wrong chain" }, "422": { "description": "No verified route, where applicable" }, "429": { "description": "Rate limit" }, "502": { "description": "RPC or simulation failure" }, "503": { "description": "Stale chain" } } } }, "/data.v2.DataApiService/GetToken": { "post": { "summary": "Get locally configured token metadata", "description": "Returns metadata only for TURKCHAIN chainId 1919 tokens in the project registry; no market price is implied.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "Returns metadata only for TURKCHAIN chainId 1919 tokens in the project registry; no market price is implied." }, "400": { "description": "Invalid request" }, "503": { "description": "Unconfigured read-only or compliance policy" } } } }, "/data.v2.DataApiService/GetTokensMultiChain": { "post": { "summary": "Resolve local chain-1919 token metadata", "description": "Returns only locally configured chain-1919 deployments. It does not discover or represent deployments on other chains.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "Returns only locally configured chain-1919 deployments. It does not discover or represent deployments on other chains." }, "400": { "description": "Invalid request" }, "503": { "description": "Unconfigured read-only or compliance policy" } } } }, "/data.v1.DataApiService/GetTokenPrices": { "post": { "summary": "Token prices (currently empty)", "description": "Returns an empty tokenPrices list until verified pool-derived USD pricing is available.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "Returns an empty tokenPrices list until verified pool-derived USD pricing is available." }, "400": { "description": "Invalid request" }, "503": { "description": "Unconfigured read-only or compliance policy" } } } }, "/data.v2.DataApiService/ConvertFiat": { "post": { "summary": "USD identity conversion; unavailable FX returns no amount", "description": "Returns an identity amount only for USD-to-USD. Cross-currency rates are not configured; these requests return 200 without convertedAmount so clients can fall back to USD. No FX rate is fabricated and this endpoint does not establish USDT parity.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "Returns an identity amount only for USD-to-USD. Cross-currency rates are not configured; these requests return 200 without convertedAmount so clients can fall back to USD. No FX rate is fabricated and this endpoint does not establish USDT parity." }, "400": { "description": "Invalid request" }, "503": { "description": "Unconfigured read-only or compliance policy" } } } }, "/uniswap.notificationservice.v1.NotificationService/GetNotifications": { "post": { "summary": "Notifications (currently empty)", "description": "Returns no notifications because no TurkDex notification feed is configured.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "Returns no notifications because no TurkDex notification feed is configured." }, "400": { "description": "Invalid request" }, "503": { "description": "Unconfigured read-only or compliance policy" } } } }, "/data.v2.DataApiService/ListTokens": { "post": { "summary": "TURKCHAIN token catalogue (unranked)", "description": "Returns chain-1919 token metadata from the local catalog enriched by the Turkscan ERC-20 directory using exact contract-address matching. Directory failures fall back to the local catalog. Chain statistics and sparklines remain empty until indexed and verified; the endpoint does not fabricate prices, volume, or TVL.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "Returns chain-1919 token metadata from the local catalog enriched by the Turkscan ERC-20 directory using exact contract-address matching. Directory failures fall back to the local catalog. Chain statistics and sparklines remain empty until indexed and verified; the endpoint does not fabricate prices, volume, or TVL." }, "400": { "description": "Unsupported chain or malformed request" }, "503": { "description": "Read-only stage restriction" } } } }, "/data.v2.DataApiService/ListPools": { "post": { "summary": "Ranked pools (currently empty)", "description": "Returns no ranked pool list while verified chain-specific pool market statistics are unavailable; pool discovery is exposed separately through the TurkDex catalog and live factory APIs.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "Returns no ranked pool list while verified chain-specific pool market statistics are unavailable; pool discovery is exposed separately through the TurkDex catalog and live factory APIs." }, "400": { "description": "Unsupported chain or malformed request" }, "503": { "description": "Read-only stage restriction" } } } }, "/permissions": { "post": { "summary": "Check token permissioned-adapter requirements for TURKCHAIN", "description": "Chain 1919 only. This deployment has no permissioned adapter integration; results therefore state isPermissioned=false and do not imply sanctions screening or geographic compliance.", "operationId": "checkTokenPermissions", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "walletAddress", "tokens", "chainId" ], "properties": { "walletAddress": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "tokens": { "type": "array", "minItems": 1, "maxItems": 2, "items": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } }, "chainId": { "const": 1919 } } } } } }, "responses": { "200": { "description": "No permissioned adapters are configured on chain 1919", "content": { "application/json": { "schema": { "type": "object", "required": [ "requestId", "results" ], "properties": { "requestId": { "type": "string" }, "results": { "type": "array", "items": { "type": "object", "required": [ "token", "isPermissioned" ], "properties": { "token": { "type": "string" }, "isPermissioned": { "const": false } } } } } } } } }, "400": { "description": "Invalid request or unsupported chain" } } } }, "/v1/market/status": { "get": { "summary": "TURKCHAIN pool and swap indexer status", "description": "Reports source checkpoint health and explicitly marks USD prices and USD volume unavailable until independently verified.", "responses": { "200": { "description": "Current indexer health and data provenance", "content": { "application/json": { "schema": { "type": "object", "required": [ "chainId", "pools", "swaps", "metrics" ], "properties": { "chainId": { "const": 1919 }, "pools": { "type": "object" }, "swaps": { "type": "object" }, "metrics": { "type": "object", "properties": { "usdPrices": { "const": "unavailable" }, "usdVolume": { "const": "unavailable" } } } } } } } } } } }, "/v1/swaps": { "get": { "summary": "Indexed TURKCHAIN swap events", "description": "Returns canonical V2, V3, and V4 swap events from the local reorg-aware indexer. Amount deltas are signed raw token units; positive means tokens entered the pool. No USD value is inferred.", "parameters": [ { "name": "chainId", "in": "query", "schema": { "type": "integer", "const": 1919 } }, { "name": "protocol", "in": "query", "schema": { "type": "string", "enum": [ "V2", "V3", "V4" ] } }, { "name": "poolId", "in": "query", "schema": { "type": "string" } }, { "name": "tokenA", "in": "query", "schema": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } }, { "name": "tokenB", "in": "query", "schema": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "walletAddress", "in": "query", "schema": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 100000, "default": 0 } } ], "responses": { "200": { "description": "Indexed swap event records", "content": { "application/json": { "schema": { "type": "object", "required": [ "chainId", "status", "swaps" ], "properties": { "chainId": { "const": 1919 }, "status": { "type": "string" }, "indexedThrough": { "type": [ "integer", "null" ] }, "swaps": { "type": "array", "items": { "type": "object", "required": [ "protocol", "poolId", "token0", "token1", "amount0Delta", "amount1Delta", "blockNumber", "transactionHash", "timestamp" ], "properties": { "protocol": { "type": "string", "enum": [ "V2", "V3", "V4" ] }, "poolId": { "type": "string" }, "token0": { "type": "string" }, "token1": { "type": "string" }, "amount0Delta": { "type": "string" }, "amount1Delta": { "type": "string" }, "blockNumber": { "type": "integer" }, "transactionHash": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } } } } } } } }, "400": { "description": "Unsupported chain or invalid filter" } } } }, "/v1/wallet/tokens": { "get": { "summary": "Read verified TURKCHAIN wallet token balances", "description": "Reads native TURK and the RPC-verified token registry at one pinned block using Multicall3. Returns exact raw units and address-matched metadata. USD valuation is explicitly unavailable; this endpoint never signs or broadcasts transactions.", "parameters": [ { "name": "address", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } } ], "responses": { "200": { "description": "On-chain token balance snapshot with block number/hash, partial-read indicators, and USD valuation provenance." }, "400": { "description": "Missing or malformed wallet address." }, "502": { "description": "RPC, chain, or Multicall3 read failed." } } } }, "/data.v1.DataApiService/ListTransactions": { "post": { "summary": "Wallet swap transaction history (TURKCHAIN)", "description": "Read-only summaries of confirmed TURKCHAIN transactions whose canonical transaction from-address matches the requested wallet and which contain indexed V2/V3/V4 Swap events. No transaction amounts or USD values are inferred. Returns 503 until the sender backfill is complete.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "chainIds", "walletAccount" ], "properties": { "chainIds": { "type": "array", "items": { "type": "integer", "const": 1919 }, "minItems": 1 }, "walletAccount": { "type": "object", "properties": { "platformAddresses": { "type": "array", "items": { "type": "object", "properties": { "address": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } } } } } }, "pageSize": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "pageToken": { "type": "string", "pattern": "^\\d{1,6}$" }, "filterTransactionTypes": { "type": "array", "items": { "type": "string", "enum": [ "TRANSACTION_TYPE_FILTER_UNSPECIFIED", "TRANSACTION_TYPE_FILTER_SWAP" ] } } } } } } }, "responses": { "200": { "description": "Canonical indexed swap transactions for wallet" }, "400": { "description": "Invalid request or unsupported chain" }, "503": { "description": "Swap sender index is not caught up" } } } } } }