> For the complete documentation index, see [llms.txt](https://docs.kiiglobal.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kiiglobal.io/docs/kiichain-pay/api-reference/blockchain.md). # Blockchain ## GetChains returns a list of chains (enabled only by default, or all if all=true) > Use GetChainByID instead when only one chain's details are needed ```json {"openapi":"3.0.0","info":{"title":"KiiChain Pay Backend","version":"v1"},"tags":[{"name":"BlockchainQueryService"}],"servers":[{"description":"Production","url":"https://backend.pay.kiichain.io"},{"description":"Staging","url":"https://backend.pay.staging.kiichain.io"}],"paths":{"/blockchain/v1/chains":{"get":{"description":"Use GetChainByID instead when only one chain's details are needed","operationId":"BlockchainQueryService_GetChains","parameters":[{"description":"all indicates whether to return all chains including disabled ones\nIf false or omitted, only enabled chains are returned","in":"query","name":"all","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/chainsGetChainsResponse"}}},"description":"A successful response."},"default":{"$ref":"#/components/responses/AppError"}},"summary":"GetChains returns a list of chains (enabled only by default, or all if all=true)","tags":["BlockchainQueryService"]}}},"components":{"schemas":{"chainsGetChainsResponse":{"properties":{"chains":{"items":{"$ref":"#/components/schemas/v1Chain"},"title":"chains is the list of chains","type":"array"}},"required":["chains"],"title":"GetChainsResponse is the response message for GetChains","type":"object"},"v1Chain":{"properties":{"chainId":{"title":"chain_id is the blockchain network identifier (e.g., \"1\" for Ethereum, \"137\" for Polygon)","type":"string"},"confirmationDepth":{"format":"int32","title":"confirmation_depth is the number of block confirmations required before processing","type":"integer"},"contracts":{"additionalProperties":{"$ref":"#/components/schemas/v1ContractEntry"},"title":"contracts maps contract name to its on-chain address and ABI version","type":"object"},"enabled":{"title":"enabled indicates whether the chain is enabled on the platform","type":"boolean"},"feeAddress":{"title":"fee_address is the address that receives the affiliate fee on this chain","type":"string"},"feeBps":{"format":"int32","title":"fee_bps is the affiliate fee in basis points charged on routes through this chain (e.g. 30 = 0.30%)","type":"integer"},"id":{"format":"int32","title":"id is the surrogate identifier of the chain","type":"integer"},"logo":{"title":"logo is the URL to the logo of the chain","type":"string"},"name":{"title":"name is the human-readable name of the chain","type":"string"},"testnet":{"title":"testnet indicates whether the chain is a testnet or mainnet","type":"boolean"},"type":{"title":"type is the type of the chain (e.g., \"evm\", \"cosmos\", \"solana\", \"bitcoin\", \"tron\")","type":"string"}},"required":["id","chainId","type","name","logo","testnet","enabled","confirmationDepth","contracts"],"title":"Chain represents a chain supported by the platform","type":"object"},"v1ContractEntry":{"properties":{"address":{"title":"address is the on-chain contract address","type":"string"},"version":{"title":"version is the optional version identifier","type":"string"}},"required":["address"],"title":"ContractEntry represents a single on-chain contract: its address and optional ABI version","type":"object"},"AppErrorStatus":{"description":"The error envelope this API returns for every non-2xx response. `details` always contains exactly one AppError.","properties":{"code":{"description":"gRPC status code","format":"int32","type":"integer"},"details":{"description":"Always contains exactly one AppError","items":{"$ref":"#/components/schemas/AppError"},"type":"array"},"message":{"description":"Human-readable error message","type":"string"}},"type":"object"},"AppError":{"description":"Structured error detail responded by any non-2xx response.","properties":{"@type":{"description":"Protobuf Any type URL, always \"type.googleapis.com/pay.common.error.v1.AppError\" for this API","type":"string"},"internalCode":{"description":"Internal error code, unique within the module","format":"int32","type":"integer"},"message":{"description":"Human-readable error message","type":"string"},"meta":{"additionalProperties":{"type":"string"},"description":"Additional structured context for the error, if any","type":"object"},"module":{"description":"Module name where the error occurred (e.g. \"accounts\", \"market\")","type":"string"}},"type":"object"}},"responses":{"AppError":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppErrorStatus"}}},"description":"An unexpected error response. `details[0]` is always an AppError, see #/components/schemas/AppError"}}}} ``` ## GetTokensByChainIDs returns tokens for a specific set of chains (enabled only by default, or all if all=true) > Response is keyed by chain\_id, each mapping to its own token\_symbol\ > lookup ```json {"openapi":"3.0.0","info":{"title":"KiiChain Pay Backend","version":"v1"},"tags":[{"name":"BlockchainQueryService"}],"servers":[{"description":"Production","url":"https://backend.pay.kiichain.io"},{"description":"Staging","url":"https://backend.pay.staging.kiichain.io"}],"paths":{"/blockchain/v1/chains/tokens":{"get":{"description":"Response is keyed by chain_id, each mapping to its own token_symbol\nlookup","operationId":"BlockchainQueryService_GetTokensByChainIDs","parameters":[{"description":"chain_ids is the list of chain IDs to get tokens for","explode":true,"in":"query","name":"chainIds","required":true,"schema":{"items":{"type":"string"},"type":"array"}},{"description":"all indicates whether to return all tokens including disabled ones\nIf false or omitted, only enabled tokens are returned","in":"query","name":"all","required":false,"schema":{"type":"boolean"}},{"description":"mode filters tokens by feature category. Supported values: \"dex\".\nIf omitted, no category filter is applied.","in":"query","name":"mode","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/chains_tokensGetTokensByChainIDsResponse"}}},"description":"A successful response."},"default":{"$ref":"#/components/responses/AppError"}},"summary":"GetTokensByChainIDs returns tokens for a specific set of chains (enabled only by default, or all if all=true)","tags":["BlockchainQueryService"]}}},"components":{"schemas":{"chains_tokensGetTokensByChainIDsResponse":{"properties":{"chainsTokens":{"additionalProperties":{"$ref":"#/components/schemas/chains_tokensChainTokens"},"title":"chains_tokens is a map of chain_id to tokens","type":"object"}},"required":["chainsTokens"],"title":"GetTokensByChainIDsResponse is the response message for GetTokensByChainIDs","type":"object"},"chains_tokensChainTokens":{"properties":{"tokens":{"additionalProperties":{"$ref":"#/components/schemas/v1ChainToken"},"title":"tokens is a map of token_symbol to ChainToken","type":"object"}},"required":["tokens"],"title":"ChainTokens represents the tokens for a specific chain","type":"object"},"v1ChainToken":{"properties":{"chain":{"$ref":"#/components/schemas/v1Chain"},"chainTokenEnabled":{"title":"chain_token_enabled indicates whether the token is enabled for this specific chain","type":"boolean"},"contractAddress":{"title":"contract_address is the smart contract address of the token on the chain (null for native tokens)","type":"string"},"enabledDex":{"title":"enabled_dex indicates whether the token is enabled for DEX operations on this chain","type":"boolean"},"id":{"format":"int32","title":"id is the surrogate identifier of the chain-token relation","type":"integer"},"native":{"title":"native indicates whether the token is native to the chain","type":"boolean"},"token":{"$ref":"#/components/schemas/v1Token"}},"required":["id","chain","token","native","chainTokenEnabled","enabledDex"],"title":"ChainToken represents a token enabled on a specific chain","type":"object"},"v1Chain":{"properties":{"chainId":{"title":"chain_id is the blockchain network identifier (e.g., \"1\" for Ethereum, \"137\" for Polygon)","type":"string"},"confirmationDepth":{"format":"int32","title":"confirmation_depth is the number of block confirmations required before processing","type":"integer"},"contracts":{"additionalProperties":{"$ref":"#/components/schemas/v1ContractEntry"},"title":"contracts maps contract name to its on-chain address and ABI version","type":"object"},"enabled":{"title":"enabled indicates whether the chain is enabled on the platform","type":"boolean"},"feeAddress":{"title":"fee_address is the address that receives the affiliate fee on this chain","type":"string"},"feeBps":{"format":"int32","title":"fee_bps is the affiliate fee in basis points charged on routes through this chain (e.g. 30 = 0.30%)","type":"integer"},"id":{"format":"int32","title":"id is the surrogate identifier of the chain","type":"integer"},"logo":{"title":"logo is the URL to the logo of the chain","type":"string"},"name":{"title":"name is the human-readable name of the chain","type":"string"},"testnet":{"title":"testnet indicates whether the chain is a testnet or mainnet","type":"boolean"},"type":{"title":"type is the type of the chain (e.g., \"evm\", \"cosmos\", \"solana\", \"bitcoin\", \"tron\")","type":"string"}},"required":["id","chainId","type","name","logo","testnet","enabled","confirmationDepth","contracts"],"title":"Chain represents a chain supported by the platform","type":"object"},"v1ContractEntry":{"properties":{"address":{"title":"address is the on-chain contract address","type":"string"},"version":{"title":"version is the optional version identifier","type":"string"}},"required":["address"],"title":"ContractEntry represents a single on-chain contract: its address and optional ABI version","type":"object"},"v1Token":{"properties":{"decimals":{"format":"int32","title":"decimals is the number of decimal places the token uses","type":"integer"},"enabled":{"title":"enabled indicates whether the token is enabled on the platform","type":"boolean"},"id":{"format":"int32","title":"id is the surrogate identifier of the token","type":"integer"},"logo":{"title":"logo is the URL to the token's logo image","type":"string"},"name":{"title":"name is the full name of the token","type":"string"},"stable":{"title":"stable indicates whether the token is a stablecoin","type":"boolean"},"symbol":{"title":"symbol is the ticker symbol of the token","type":"string"}},"required":["id","name","symbol","decimals","logo","enabled","stable"],"title":"Token represents a coin/token supported by the platform","type":"object"},"AppErrorStatus":{"description":"The error envelope this API returns for every non-2xx response. `details` always contains exactly one AppError.","properties":{"code":{"description":"gRPC status code","format":"int32","type":"integer"},"details":{"description":"Always contains exactly one AppError","items":{"$ref":"#/components/schemas/AppError"},"type":"array"},"message":{"description":"Human-readable error message","type":"string"}},"type":"object"},"AppError":{"description":"Structured error detail responded by any non-2xx response.","properties":{"@type":{"description":"Protobuf Any type URL, always \"type.googleapis.com/pay.common.error.v1.AppError\" for this API","type":"string"},"internalCode":{"description":"Internal error code, unique within the module","format":"int32","type":"integer"},"message":{"description":"Human-readable error message","type":"string"},"meta":{"additionalProperties":{"type":"string"},"description":"Additional structured context for the error, if any","type":"object"},"module":{"description":"Module name where the error occurred (e.g. \"accounts\", \"market\")","type":"string"}},"type":"object"}},"responses":{"AppError":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppErrorStatus"}}},"description":"An unexpected error response. `details[0]` is always an AppError, see #/components/schemas/AppError"}}}} ``` ## GetChainTokens returns all token/chains relations (enabled only by default, or all if all=true) > Flat list across every chain. Use GetTokensByChainIDs to scope the\ > lookup to specific chains ```json {"openapi":"3.0.0","info":{"title":"KiiChain Pay Backend","version":"v1"},"tags":[{"name":"BlockchainQueryService"}],"servers":[{"description":"Production","url":"https://backend.pay.kiichain.io"},{"description":"Staging","url":"https://backend.pay.staging.kiichain.io"}],"paths":{"/blockchain/v1/chains/tokens/all":{"get":{"description":"Flat list across every chain. Use GetTokensByChainIDs to scope the\nlookup to specific chains","operationId":"BlockchainQueryService_GetChainTokens","parameters":[{"description":"all indicates whether to return all chain-tokens including disabled ones\nIf false or omitted, only enabled chain-tokens are returned","in":"query","name":"all","required":false,"schema":{"type":"boolean"}},{"description":"mode filters chain-tokens by feature category. Supported values: \"dex\".\nIf omitted, no category filter is applied.","in":"query","name":"mode","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/chains_tokensGetChainTokensResponse"}}},"description":"A successful response."},"default":{"$ref":"#/components/responses/AppError"}},"summary":"GetChainTokens returns all token/chains relations (enabled only by default, or all if all=true)","tags":["BlockchainQueryService"]}}},"components":{"schemas":{"chains_tokensGetChainTokensResponse":{"properties":{"chainsTokens":{"items":{"$ref":"#/components/schemas/v1ChainToken"},"title":"chains_tokens is a list of all chain-token relations","type":"array"}},"required":["chainsTokens"],"title":"GetChainTokensResponse is the response message for GetChainTokensResponse","type":"object"},"v1ChainToken":{"properties":{"chain":{"$ref":"#/components/schemas/v1Chain"},"chainTokenEnabled":{"title":"chain_token_enabled indicates whether the token is enabled for this specific chain","type":"boolean"},"contractAddress":{"title":"contract_address is the smart contract address of the token on the chain (null for native tokens)","type":"string"},"enabledDex":{"title":"enabled_dex indicates whether the token is enabled for DEX operations on this chain","type":"boolean"},"id":{"format":"int32","title":"id is the surrogate identifier of the chain-token relation","type":"integer"},"native":{"title":"native indicates whether the token is native to the chain","type":"boolean"},"token":{"$ref":"#/components/schemas/v1Token"}},"required":["id","chain","token","native","chainTokenEnabled","enabledDex"],"title":"ChainToken represents a token enabled on a specific chain","type":"object"},"v1Chain":{"properties":{"chainId":{"title":"chain_id is the blockchain network identifier (e.g., \"1\" for Ethereum, \"137\" for Polygon)","type":"string"},"confirmationDepth":{"format":"int32","title":"confirmation_depth is the number of block confirmations required before processing","type":"integer"},"contracts":{"additionalProperties":{"$ref":"#/components/schemas/v1ContractEntry"},"title":"contracts maps contract name to its on-chain address and ABI version","type":"object"},"enabled":{"title":"enabled indicates whether the chain is enabled on the platform","type":"boolean"},"feeAddress":{"title":"fee_address is the address that receives the affiliate fee on this chain","type":"string"},"feeBps":{"format":"int32","title":"fee_bps is the affiliate fee in basis points charged on routes through this chain (e.g. 30 = 0.30%)","type":"integer"},"id":{"format":"int32","title":"id is the surrogate identifier of the chain","type":"integer"},"logo":{"title":"logo is the URL to the logo of the chain","type":"string"},"name":{"title":"name is the human-readable name of the chain","type":"string"},"testnet":{"title":"testnet indicates whether the chain is a testnet or mainnet","type":"boolean"},"type":{"title":"type is the type of the chain (e.g., \"evm\", \"cosmos\", \"solana\", \"bitcoin\", \"tron\")","type":"string"}},"required":["id","chainId","type","name","logo","testnet","enabled","confirmationDepth","contracts"],"title":"Chain represents a chain supported by the platform","type":"object"},"v1ContractEntry":{"properties":{"address":{"title":"address is the on-chain contract address","type":"string"},"version":{"title":"version is the optional version identifier","type":"string"}},"required":["address"],"title":"ContractEntry represents a single on-chain contract: its address and optional ABI version","type":"object"},"v1Token":{"properties":{"decimals":{"format":"int32","title":"decimals is the number of decimal places the token uses","type":"integer"},"enabled":{"title":"enabled indicates whether the token is enabled on the platform","type":"boolean"},"id":{"format":"int32","title":"id is the surrogate identifier of the token","type":"integer"},"logo":{"title":"logo is the URL to the token's logo image","type":"string"},"name":{"title":"name is the full name of the token","type":"string"},"stable":{"title":"stable indicates whether the token is a stablecoin","type":"boolean"},"symbol":{"title":"symbol is the ticker symbol of the token","type":"string"}},"required":["id","name","symbol","decimals","logo","enabled","stable"],"title":"Token represents a coin/token supported by the platform","type":"object"},"AppErrorStatus":{"description":"The error envelope this API returns for every non-2xx response. `details` always contains exactly one AppError.","properties":{"code":{"description":"gRPC status code","format":"int32","type":"integer"},"details":{"description":"Always contains exactly one AppError","items":{"$ref":"#/components/schemas/AppError"},"type":"array"},"message":{"description":"Human-readable error message","type":"string"}},"type":"object"},"AppError":{"description":"Structured error detail responded by any non-2xx response.","properties":{"@type":{"description":"Protobuf Any type URL, always \"type.googleapis.com/pay.common.error.v1.AppError\" for this API","type":"string"},"internalCode":{"description":"Internal error code, unique within the module","format":"int32","type":"integer"},"message":{"description":"Human-readable error message","type":"string"},"meta":{"additionalProperties":{"type":"string"},"description":"Additional structured context for the error, if any","type":"object"},"module":{"description":"Module name where the error occurred (e.g. \"accounts\", \"market\")","type":"string"}},"type":"object"}},"responses":{"AppError":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppErrorStatus"}}},"description":"An unexpected error response. `details[0]` is always an AppError, see #/components/schemas/AppError"}}}} ``` ## GetChainByID returns a single chain by ID > Includes the chain's contracts map and confirmation depth ```json {"openapi":"3.0.0","info":{"title":"KiiChain Pay Backend","version":"v1"},"tags":[{"name":"BlockchainQueryService"}],"servers":[{"description":"Production","url":"https://backend.pay.kiichain.io"},{"description":"Staging","url":"https://backend.pay.staging.kiichain.io"}],"paths":{"/blockchain/v1/chains/{chainId}":{"get":{"description":"Includes the chain's contracts map and confirmation depth","operationId":"BlockchainQueryService_GetChainByID","parameters":[{"description":"chain_id is the blockchain network identifier (e.g., \"1\" for Ethereum)","in":"path","name":"chainId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/chainsGetChainByIDResponse"}}},"description":"A successful response."},"default":{"$ref":"#/components/responses/AppError"}},"summary":"GetChainByID returns a single chain by ID","tags":["BlockchainQueryService"]}}},"components":{"schemas":{"chainsGetChainByIDResponse":{"properties":{"chain":{"$ref":"#/components/schemas/v1Chain"}},"required":["chain"],"title":"GetChainByIDResponse is the response message for GetChainByID","type":"object"},"v1Chain":{"properties":{"chainId":{"title":"chain_id is the blockchain network identifier (e.g., \"1\" for Ethereum, \"137\" for Polygon)","type":"string"},"confirmationDepth":{"format":"int32","title":"confirmation_depth is the number of block confirmations required before processing","type":"integer"},"contracts":{"additionalProperties":{"$ref":"#/components/schemas/v1ContractEntry"},"title":"contracts maps contract name to its on-chain address and ABI version","type":"object"},"enabled":{"title":"enabled indicates whether the chain is enabled on the platform","type":"boolean"},"feeAddress":{"title":"fee_address is the address that receives the affiliate fee on this chain","type":"string"},"feeBps":{"format":"int32","title":"fee_bps is the affiliate fee in basis points charged on routes through this chain (e.g. 30 = 0.30%)","type":"integer"},"id":{"format":"int32","title":"id is the surrogate identifier of the chain","type":"integer"},"logo":{"title":"logo is the URL to the logo of the chain","type":"string"},"name":{"title":"name is the human-readable name of the chain","type":"string"},"testnet":{"title":"testnet indicates whether the chain is a testnet or mainnet","type":"boolean"},"type":{"title":"type is the type of the chain (e.g., \"evm\", \"cosmos\", \"solana\", \"bitcoin\", \"tron\")","type":"string"}},"required":["id","chainId","type","name","logo","testnet","enabled","confirmationDepth","contracts"],"title":"Chain represents a chain supported by the platform","type":"object"},"v1ContractEntry":{"properties":{"address":{"title":"address is the on-chain contract address","type":"string"},"version":{"title":"version is the optional version identifier","type":"string"}},"required":["address"],"title":"ContractEntry represents a single on-chain contract: its address and optional ABI version","type":"object"},"AppErrorStatus":{"description":"The error envelope this API returns for every non-2xx response. `details` always contains exactly one AppError.","properties":{"code":{"description":"gRPC status code","format":"int32","type":"integer"},"details":{"description":"Always contains exactly one AppError","items":{"$ref":"#/components/schemas/AppError"},"type":"array"},"message":{"description":"Human-readable error message","type":"string"}},"type":"object"},"AppError":{"description":"Structured error detail responded by any non-2xx response.","properties":{"@type":{"description":"Protobuf Any type URL, always \"type.googleapis.com/pay.common.error.v1.AppError\" for this API","type":"string"},"internalCode":{"description":"Internal error code, unique within the module","format":"int32","type":"integer"},"message":{"description":"Human-readable error message","type":"string"},"meta":{"additionalProperties":{"type":"string"},"description":"Additional structured context for the error, if any","type":"object"},"module":{"description":"Module name where the error occurred (e.g. \"accounts\", \"market\")","type":"string"}},"type":"object"}},"responses":{"AppError":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppErrorStatus"}}},"description":"An unexpected error response. `details[0]` is always an AppError, see #/components/schemas/AppError"}}}} ``` ## GetChainTokenRelation returns a single chain-token relation > Looked up by chain\_id and token\_symbol together ```json {"openapi":"3.0.0","info":{"title":"KiiChain Pay Backend","version":"v1"},"tags":[{"name":"BlockchainQueryService"}],"servers":[{"description":"Production","url":"https://backend.pay.kiichain.io"},{"description":"Staging","url":"https://backend.pay.staging.kiichain.io"}],"paths":{"/blockchain/v1/chains/{chainId}/tokens/{tokenSymbol}":{"get":{"description":"Looked up by chain_id and token_symbol together","operationId":"BlockchainQueryService_GetChainTokenRelation","parameters":[{"description":"chain_id is the unique identifier of the chain","in":"path","name":"chainId","required":true,"schema":{"type":"string"}},{"description":"token_symbol is the ticker symbol of the token","in":"path","name":"tokenSymbol","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/chains_tokensGetChainTokenRelationResponse"}}},"description":"A successful response."},"default":{"$ref":"#/components/responses/AppError"}},"summary":"GetChainTokenRelation returns a single chain-token relation","tags":["BlockchainQueryService"]}}},"components":{"schemas":{"chains_tokensGetChainTokenRelationResponse":{"properties":{"chainToken":{"$ref":"#/components/schemas/v1ChainToken"}},"required":["chainToken"],"title":"GetChainTokenRelationResponse is the response message for GetChainTokenRelation","type":"object"},"v1ChainToken":{"properties":{"chain":{"$ref":"#/components/schemas/v1Chain"},"chainTokenEnabled":{"title":"chain_token_enabled indicates whether the token is enabled for this specific chain","type":"boolean"},"contractAddress":{"title":"contract_address is the smart contract address of the token on the chain (null for native tokens)","type":"string"},"enabledDex":{"title":"enabled_dex indicates whether the token is enabled for DEX operations on this chain","type":"boolean"},"id":{"format":"int32","title":"id is the surrogate identifier of the chain-token relation","type":"integer"},"native":{"title":"native indicates whether the token is native to the chain","type":"boolean"},"token":{"$ref":"#/components/schemas/v1Token"}},"required":["id","chain","token","native","chainTokenEnabled","enabledDex"],"title":"ChainToken represents a token enabled on a specific chain","type":"object"},"v1Chain":{"properties":{"chainId":{"title":"chain_id is the blockchain network identifier (e.g., \"1\" for Ethereum, \"137\" for Polygon)","type":"string"},"confirmationDepth":{"format":"int32","title":"confirmation_depth is the number of block confirmations required before processing","type":"integer"},"contracts":{"additionalProperties":{"$ref":"#/components/schemas/v1ContractEntry"},"title":"contracts maps contract name to its on-chain address and ABI version","type":"object"},"enabled":{"title":"enabled indicates whether the chain is enabled on the platform","type":"boolean"},"feeAddress":{"title":"fee_address is the address that receives the affiliate fee on this chain","type":"string"},"feeBps":{"format":"int32","title":"fee_bps is the affiliate fee in basis points charged on routes through this chain (e.g. 30 = 0.30%)","type":"integer"},"id":{"format":"int32","title":"id is the surrogate identifier of the chain","type":"integer"},"logo":{"title":"logo is the URL to the logo of the chain","type":"string"},"name":{"title":"name is the human-readable name of the chain","type":"string"},"testnet":{"title":"testnet indicates whether the chain is a testnet or mainnet","type":"boolean"},"type":{"title":"type is the type of the chain (e.g., \"evm\", \"cosmos\", \"solana\", \"bitcoin\", \"tron\")","type":"string"}},"required":["id","chainId","type","name","logo","testnet","enabled","confirmationDepth","contracts"],"title":"Chain represents a chain supported by the platform","type":"object"},"v1ContractEntry":{"properties":{"address":{"title":"address is the on-chain contract address","type":"string"},"version":{"title":"version is the optional version identifier","type":"string"}},"required":["address"],"title":"ContractEntry represents a single on-chain contract: its address and optional ABI version","type":"object"},"v1Token":{"properties":{"decimals":{"format":"int32","title":"decimals is the number of decimal places the token uses","type":"integer"},"enabled":{"title":"enabled indicates whether the token is enabled on the platform","type":"boolean"},"id":{"format":"int32","title":"id is the surrogate identifier of the token","type":"integer"},"logo":{"title":"logo is the URL to the token's logo image","type":"string"},"name":{"title":"name is the full name of the token","type":"string"},"stable":{"title":"stable indicates whether the token is a stablecoin","type":"boolean"},"symbol":{"title":"symbol is the ticker symbol of the token","type":"string"}},"required":["id","name","symbol","decimals","logo","enabled","stable"],"title":"Token represents a coin/token supported by the platform","type":"object"},"AppErrorStatus":{"description":"The error envelope this API returns for every non-2xx response. `details` always contains exactly one AppError.","properties":{"code":{"description":"gRPC status code","format":"int32","type":"integer"},"details":{"description":"Always contains exactly one AppError","items":{"$ref":"#/components/schemas/AppError"},"type":"array"},"message":{"description":"Human-readable error message","type":"string"}},"type":"object"},"AppError":{"description":"Structured error detail responded by any non-2xx response.","properties":{"@type":{"description":"Protobuf Any type URL, always \"type.googleapis.com/pay.common.error.v1.AppError\" for this API","type":"string"},"internalCode":{"description":"Internal error code, unique within the module","format":"int32","type":"integer"},"message":{"description":"Human-readable error message","type":"string"},"meta":{"additionalProperties":{"type":"string"},"description":"Additional structured context for the error, if any","type":"object"},"module":{"description":"Module name where the error occurred (e.g. \"accounts\", \"market\")","type":"string"}},"type":"object"}},"responses":{"AppError":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppErrorStatus"}}},"description":"An unexpected error response. `details[0]` is always an AppError, see #/components/schemas/AppError"}}}} ``` ## GetTokens returns a list of tokens (enabled only by default, or all if all=true) > Platform-wide list, not scoped to a chain or wallet ```json {"openapi":"3.0.0","info":{"title":"KiiChain Pay Backend","version":"v1"},"tags":[{"name":"BlockchainQueryService"}],"servers":[{"description":"Production","url":"https://backend.pay.kiichain.io"},{"description":"Staging","url":"https://backend.pay.staging.kiichain.io"}],"paths":{"/blockchain/v1/tokens":{"get":{"description":"Platform-wide list, not scoped to a chain or wallet","operationId":"BlockchainQueryService_GetTokens","parameters":[{"description":"all indicates whether to return all tokens including disabled ones\nIf false or omitted, only enabled tokens are returned","in":"query","name":"all","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/tokensGetTokensResponse"}}},"description":"A successful response."},"default":{"$ref":"#/components/responses/AppError"}},"summary":"GetTokens returns a list of tokens (enabled only by default, or all if all=true)","tags":["BlockchainQueryService"]}}},"components":{"schemas":{"tokensGetTokensResponse":{"properties":{"tokens":{"items":{"$ref":"#/components/schemas/v1Token"},"title":"tokens is the list of tokens","type":"array"}},"required":["tokens"],"title":"GetTokensResponse is the response message for GetTokens","type":"object"},"v1Token":{"properties":{"decimals":{"format":"int32","title":"decimals is the number of decimal places the token uses","type":"integer"},"enabled":{"title":"enabled indicates whether the token is enabled on the platform","type":"boolean"},"id":{"format":"int32","title":"id is the surrogate identifier of the token","type":"integer"},"logo":{"title":"logo is the URL to the token's logo image","type":"string"},"name":{"title":"name is the full name of the token","type":"string"},"stable":{"title":"stable indicates whether the token is a stablecoin","type":"boolean"},"symbol":{"title":"symbol is the ticker symbol of the token","type":"string"}},"required":["id","name","symbol","decimals","logo","enabled","stable"],"title":"Token represents a coin/token supported by the platform","type":"object"},"AppErrorStatus":{"description":"The error envelope this API returns for every non-2xx response. `details` always contains exactly one AppError.","properties":{"code":{"description":"gRPC status code","format":"int32","type":"integer"},"details":{"description":"Always contains exactly one AppError","items":{"$ref":"#/components/schemas/AppError"},"type":"array"},"message":{"description":"Human-readable error message","type":"string"}},"type":"object"},"AppError":{"description":"Structured error detail responded by any non-2xx response.","properties":{"@type":{"description":"Protobuf Any type URL, always \"type.googleapis.com/pay.common.error.v1.AppError\" for this API","type":"string"},"internalCode":{"description":"Internal error code, unique within the module","format":"int32","type":"integer"},"message":{"description":"Human-readable error message","type":"string"},"meta":{"additionalProperties":{"type":"string"},"description":"Additional structured context for the error, if any","type":"object"},"module":{"description":"Module name where the error occurred (e.g. \"accounts\", \"market\")","type":"string"}},"type":"object"}},"responses":{"AppError":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppErrorStatus"}}},"description":"An unexpected error response. `details[0]` is always an AppError, see #/components/schemas/AppError"}}}} ``` ## GetTokenBySymbol returns a single token by symbol > Returns the token's platform-wide metadata regardless of chain ```json {"openapi":"3.0.0","info":{"title":"KiiChain Pay Backend","version":"v1"},"tags":[{"name":"BlockchainQueryService"}],"servers":[{"description":"Production","url":"https://backend.pay.kiichain.io"},{"description":"Staging","url":"https://backend.pay.staging.kiichain.io"}],"paths":{"/blockchain/v1/tokens/{symbol}":{"get":{"description":"Returns the token's platform-wide metadata regardless of chain","operationId":"BlockchainQueryService_GetTokenBySymbol","parameters":[{"description":"symbol is the ticker symbol of the token","in":"path","name":"symbol","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/tokensGetTokenBySymbolResponse"}}},"description":"A successful response."},"default":{"$ref":"#/components/responses/AppError"}},"summary":"GetTokenBySymbol returns a single token by symbol","tags":["BlockchainQueryService"]}}},"components":{"schemas":{"tokensGetTokenBySymbolResponse":{"properties":{"token":{"$ref":"#/components/schemas/v1Token"}},"required":["token"],"title":"GetTokenBySymbolResponse is the response message for GetTokenBySymbol","type":"object"},"v1Token":{"properties":{"decimals":{"format":"int32","title":"decimals is the number of decimal places the token uses","type":"integer"},"enabled":{"title":"enabled indicates whether the token is enabled on the platform","type":"boolean"},"id":{"format":"int32","title":"id is the surrogate identifier of the token","type":"integer"},"logo":{"title":"logo is the URL to the token's logo image","type":"string"},"name":{"title":"name is the full name of the token","type":"string"},"stable":{"title":"stable indicates whether the token is a stablecoin","type":"boolean"},"symbol":{"title":"symbol is the ticker symbol of the token","type":"string"}},"required":["id","name","symbol","decimals","logo","enabled","stable"],"title":"Token represents a coin/token supported by the platform","type":"object"},"AppErrorStatus":{"description":"The error envelope this API returns for every non-2xx response. `details` always contains exactly one AppError.","properties":{"code":{"description":"gRPC status code","format":"int32","type":"integer"},"details":{"description":"Always contains exactly one AppError","items":{"$ref":"#/components/schemas/AppError"},"type":"array"},"message":{"description":"Human-readable error message","type":"string"}},"type":"object"},"AppError":{"description":"Structured error detail responded by any non-2xx response.","properties":{"@type":{"description":"Protobuf Any type URL, always \"type.googleapis.com/pay.common.error.v1.AppError\" for this API","type":"string"},"internalCode":{"description":"Internal error code, unique within the module","format":"int32","type":"integer"},"message":{"description":"Human-readable error message","type":"string"},"meta":{"additionalProperties":{"type":"string"},"description":"Additional structured context for the error, if any","type":"object"},"module":{"description":"Module name where the error occurred (e.g. \"accounts\", \"market\")","type":"string"}},"type":"object"}},"responses":{"AppError":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppErrorStatus"}}},"description":"An unexpected error response. `details[0]` is always an AppError, see #/components/schemas/AppError"}}}} ``` ## ExecuteTransaction signs and broadcasts a batch of transactions on behalf of the caller > Each transaction is signed using the caller's delegated wallet. Failed\ > transactions are returned as "0x00" in the response and do not abort the\ > rest of the batch ```json {"openapi":"3.0.0","info":{"title":"KiiChain Pay Backend","version":"v1"},"tags":[{"name":"BlockchainMsgService"}],"servers":[{"description":"Production","url":"https://backend.pay.kiichain.io"},{"description":"Staging","url":"https://backend.pay.staging.kiichain.io"}],"security":[{"ApiKeyAuth":["blockchain.transactions.execute"]},{"BearerAuth":["blockchain.transactions.execute"]}],"components":{"securitySchemes":{"ApiKeyAuth":{"description":"Send 'Authorization: APIKey ' to authenticate with a API key.","in":"header","name":"Authorization","type":"apiKey"},"BearerAuth":{"flows":{"password":{"scopes":{},"tokenUrl":"https://backend.pay.kiichain.io/users/v1/auth/login"}},"type":"oauth2"}},"schemas":{"transactionsExecuteTransactionRequest":{"description":"ExecuteTransactionRequest contains the ordered list of transactions to execute.","properties":{"transactions":{"items":{"$ref":"#/components/schemas/blockchainV1Transaction"},"type":"array"}},"type":"object"},"blockchainV1Transaction":{"properties":{"evm":{"$ref":"#/components/schemas/v1EVMTransaction"}},"title":"Transaction wraps the transactions to build an ordered list","type":"object"},"v1EVMTransaction":{"properties":{"chainId":{"title":"chain_id is the ID of the network","type":"string"},"data":{"title":"data is the hex raw call data to be sent on the transaction","type":"string"},"from":{"title":"from is the address from which the transaction should be sent","type":"string"},"metadata":{"additionalProperties":{"type":"string"},"title":"metadata is the map of additional information to be sent with the transaction","type":"object"},"to":{"title":"to is the address to which the transaction should be sent","type":"string"},"type":{"title":"type is the type of the tx -- kiirouter, approval, etc","type":"string"},"value":{"title":"value is the amount of native token to be sent with the transaction","type":"string"}},"required":["type","chainId","from","to","value","data"],"title":"EVMTransaction represents an EVM transaction to be sent to the blockchain","type":"object"},"transactionsExecuteTransactionResponse":{"description":"ExecuteTransactionResponse contains the transaction hashes in the same order as the request.\nFailed transactions are represented as \"0x00\".","properties":{"txHashes":{"items":{"type":"string"},"type":"array"}},"type":"object"},"AppErrorStatus":{"description":"The error envelope this API returns for every non-2xx response. `details` always contains exactly one AppError.","properties":{"code":{"description":"gRPC status code","format":"int32","type":"integer"},"details":{"description":"Always contains exactly one AppError","items":{"$ref":"#/components/schemas/AppError"},"type":"array"},"message":{"description":"Human-readable error message","type":"string"}},"type":"object"},"AppError":{"description":"Structured error detail responded by any non-2xx response.","properties":{"@type":{"description":"Protobuf Any type URL, always \"type.googleapis.com/pay.common.error.v1.AppError\" for this API","type":"string"},"internalCode":{"description":"Internal error code, unique within the module","format":"int32","type":"integer"},"message":{"description":"Human-readable error message","type":"string"},"meta":{"additionalProperties":{"type":"string"},"description":"Additional structured context for the error, if any","type":"object"},"module":{"description":"Module name where the error occurred (e.g. \"accounts\", \"market\")","type":"string"}},"type":"object"}},"responses":{"AppError":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppErrorStatus"}}},"description":"An unexpected error response. `details[0]` is always an AppError, see #/components/schemas/AppError"}}},"paths":{"/blockchain/v1/transactions/execute":{"post":{"description":"Each transaction is signed using the caller's delegated wallet. Failed\ntransactions are returned as \"0x00\" in the response and do not abort the\nrest of the batch","operationId":"BlockchainMsgService_ExecuteTransaction","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/transactionsExecuteTransactionRequest"}}},"description":"ExecuteTransactionRequest contains the ordered list of transactions to execute.","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/transactionsExecuteTransactionResponse"}}},"description":"A successful response."},"default":{"$ref":"#/components/responses/AppError"}},"summary":"ExecuteTransaction signs and broadcasts a batch of transactions on behalf of the caller","tags":["BlockchainMsgService"]}}}} ``` ## GetInternalWallets returns the internal wallets owned by the caller > Lists the internal wallets tied to the authenticated user's\ > account(s), across every chain family ```json {"openapi":"3.0.0","info":{"title":"KiiChain Pay Backend","version":"v1"},"tags":[{"name":"BlockchainQueryService"}],"servers":[{"description":"Production","url":"https://backend.pay.kiichain.io"},{"description":"Staging","url":"https://backend.pay.staging.kiichain.io"}],"security":[{"ApiKeyAuth":["blockchain.wallets.read"]},{"BearerAuth":["blockchain.wallets.read"]}],"components":{"securitySchemes":{"ApiKeyAuth":{"description":"Send 'Authorization: APIKey ' to authenticate with a API key.","in":"header","name":"Authorization","type":"apiKey"},"BearerAuth":{"flows":{"password":{"scopes":{},"tokenUrl":"https://backend.pay.kiichain.io/users/v1/auth/login"}},"type":"oauth2"}},"schemas":{"transactionsGetInternalWalletsResponse":{"description":"GetInternalWalletsResponse contains the caller's internal wallets.","properties":{"wallets":{"items":{"$ref":"#/components/schemas/transactionsInternalWallet"},"type":"array"}},"type":"object"},"transactionsInternalWallet":{"description":"InternalWallet represents an internal wallet owned by the caller.","properties":{"address":{"title":"address is the on-chain address of the wallet","type":"string"},"chainType":{"title":"chain_type is the chain family the wallet belongs to (ethereum, solana, tron, ...)","type":"string"},"id":{"title":"id is the internal identifier of the wallet","type":"string"}},"type":"object"},"AppErrorStatus":{"description":"The error envelope this API returns for every non-2xx response. `details` always contains exactly one AppError.","properties":{"code":{"description":"gRPC status code","format":"int32","type":"integer"},"details":{"description":"Always contains exactly one AppError","items":{"$ref":"#/components/schemas/AppError"},"type":"array"},"message":{"description":"Human-readable error message","type":"string"}},"type":"object"},"AppError":{"description":"Structured error detail responded by any non-2xx response.","properties":{"@type":{"description":"Protobuf Any type URL, always \"type.googleapis.com/pay.common.error.v1.AppError\" for this API","type":"string"},"internalCode":{"description":"Internal error code, unique within the module","format":"int32","type":"integer"},"message":{"description":"Human-readable error message","type":"string"},"meta":{"additionalProperties":{"type":"string"},"description":"Additional structured context for the error, if any","type":"object"},"module":{"description":"Module name where the error occurred (e.g. \"accounts\", \"market\")","type":"string"}},"type":"object"}},"responses":{"AppError":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppErrorStatus"}}},"description":"An unexpected error response. `details[0]` is always an AppError, see #/components/schemas/AppError"}}},"paths":{"/blockchain/v1/wallets/internal":{"get":{"description":"Lists the internal wallets tied to the authenticated user's\naccount(s), across every chain family","operationId":"BlockchainQueryService_GetInternalWallets","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/transactionsGetInternalWalletsResponse"}}},"description":"A successful response."},"default":{"$ref":"#/components/responses/AppError"}},"summary":"GetInternalWallets returns the internal wallets owned by the caller","tags":["BlockchainQueryService"]}}}} ``` ## SendBalanceFromInternalWallet sends a balance out of the caller's internal wallet > Builds a native (gas token) or ERC20 transfer from the caller's internal\ > wallet to the given address, then signs and broadcasts it using the\ > caller's delegated wallet. The asset field selects the token to send; an\ > empty or zero address sends the native gas token. Works on any supported\ > chain given its chain\_id ```json {"openapi":"3.0.0","info":{"title":"KiiChain Pay Backend","version":"v1"},"tags":[{"name":"BlockchainMsgService"}],"servers":[{"description":"Production","url":"https://backend.pay.kiichain.io"},{"description":"Staging","url":"https://backend.pay.staging.kiichain.io"}],"security":[{"ApiKeyAuth":["blockchain.wallets.send"]},{"BearerAuth":["blockchain.wallets.send"]}],"components":{"securitySchemes":{"ApiKeyAuth":{"description":"Send 'Authorization: APIKey ' to authenticate with a API key.","in":"header","name":"Authorization","type":"apiKey"},"BearerAuth":{"flows":{"password":{"scopes":{},"tokenUrl":"https://backend.pay.kiichain.io/users/v1/auth/login"}},"type":"oauth2"}},"schemas":{"transactionsSendBalanceFromInternalWalletRequest":{"description":"SendBalanceFromInternalWalletRequest asks to send a balance out of the caller's internal wallet.","properties":{"amount":{"title":"amount is the amount to send in the token's smallest unit (wei/atoms)","type":"string"},"asset":{"title":"asset is the token contract address to send; leave empty or use the zero\naddress to send the native gas token","type":"string"},"chainId":{"title":"chain_id is the numeric ID of the network to send on","type":"string"},"to":{"title":"to is the destination address that receives the balance","type":"string"}},"required":["chainId","to","amount"],"type":"object"},"transactionsSendBalanceFromInternalWalletResponse":{"description":"SendBalanceFromInternalWalletResponse contains the broadcast transaction hash.","properties":{"txHash":{"title":"tx_hash is the hash of the broadcast transaction","type":"string"}},"type":"object"},"AppErrorStatus":{"description":"The error envelope this API returns for every non-2xx response. `details` always contains exactly one AppError.","properties":{"code":{"description":"gRPC status code","format":"int32","type":"integer"},"details":{"description":"Always contains exactly one AppError","items":{"$ref":"#/components/schemas/AppError"},"type":"array"},"message":{"description":"Human-readable error message","type":"string"}},"type":"object"},"AppError":{"description":"Structured error detail responded by any non-2xx response.","properties":{"@type":{"description":"Protobuf Any type URL, always \"type.googleapis.com/pay.common.error.v1.AppError\" for this API","type":"string"},"internalCode":{"description":"Internal error code, unique within the module","format":"int32","type":"integer"},"message":{"description":"Human-readable error message","type":"string"},"meta":{"additionalProperties":{"type":"string"},"description":"Additional structured context for the error, if any","type":"object"},"module":{"description":"Module name where the error occurred (e.g. \"accounts\", \"market\")","type":"string"}},"type":"object"}},"responses":{"AppError":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppErrorStatus"}}},"description":"An unexpected error response. `details[0]` is always an AppError, see #/components/schemas/AppError"}}},"paths":{"/blockchain/v1/wallets/internal/send":{"post":{"description":"Builds a native (gas token) or ERC20 transfer from the caller's internal\nwallet to the given address, then signs and broadcasts it using the\ncaller's delegated wallet. The asset field selects the token to send; an\nempty or zero address sends the native gas token. Works on any supported\nchain given its chain_id","operationId":"BlockchainMsgService_SendBalanceFromInternalWallet","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/transactionsSendBalanceFromInternalWalletRequest"}}},"description":"SendBalanceFromInternalWalletRequest asks to send a balance out of the caller's internal wallet.","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/transactionsSendBalanceFromInternalWalletResponse"}}},"description":"A successful response."},"default":{"$ref":"#/components/responses/AppError"}},"summary":"SendBalanceFromInternalWallet sends a balance out of the caller's internal wallet","tags":["BlockchainMsgService"]}}}} ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.kiiglobal.io/docs/kiichain-pay/api-reference/blockchain.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.