feat(api): update API v2 field descriptions#1469
Conversation
|
Skipping AI review because no docs changes in md, mdx, or docs.json |
ecosystem/api/toncenter/v2.json
Outdated
| ], | ||
| "summary": "JSON-RPC endpoint", | ||
| "description": "All API methods are available through this single endpoint using JSON-RPC 2.0 protocol. Send the method name in the `method` field and parameters as a dictionary in `params`. Useful when you need to call multiple methods in sequence or prefer JSON-RPC over REST.", |
ecosystem/api/toncenter/v2.json
Outdated
| "summary": "JSON-RPC endpoint", | ||
| "description": "All API methods are available through this single endpoint using JSON-RPC 2.0 protocol. Send the method name in the `method` field and parameters as a dictionary in `params`. Useful when you need to call multiple methods in sequence or prefer JSON-RPC over REST.", | ||
| "operationId": "jsonRPC_post", | ||
| "requestBody": { |
There was a problem hiding this comment.
https://companyname-a7d5b98e-fields.mintlify.app/ecosystem/api/toncenter/v2/rpc/json-rpc-endpoint
Result field seems strange and broken:
Does it really have two options?
There was a problem hiding this comment.
This was all messed up. Basically any method can be sent as JSON RPC request. And the json file had all responses for all methods as a dropdown list in there, which is not ok
ecosystem/api/toncenter/v2.json
Outdated
| ], | ||
| "summary": "Detect address", |
There was a problem hiding this comment.
The field definition is wrong, which works from ANY form of TON Address:
example:
curl --request POST \
--url https://toncenter.com/api/v2/detectAddress \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"address": "0:c78b3eb54a55243d4efe411f0bb0101a8da61904a89c48212f81ff32006b2dc1"
}
https://companyname-a7d5b98e-fields.mintlify.app/ecosystem/api/toncenter/v2/rpc/detect-address
ecosystem/api/toncenter/v2.json
Outdated
| "summary": "Detect address", | ||
| "description": "Validates an address and returns it in all standard formats. Use this to convert between address formats or to validate user input. Returns raw format (0:abc...), base64 bounceable (EQ...), base64 non-bounceable (UQ...), and URL-safe variants.", | ||
| "operationId": "detectAddress_post", | ||
| "requestBody": { |
There was a problem hiding this comment.
Let's find a more detailed explanation of this field for devs. Even if this is not for external use, it should be documented clearly:

https://companyname-a7d5b98e-fields.mintlify.app/ecosystem/api/toncenter/v2/rpc/detect-address
ecosystem/api/toncenter/v2.json
Outdated
| "description": "Similar to previous one but tries to parse additional information for known contract types. This method is based on tonlib's function *getAccountState*. For detecting wallets we recommend to use *getWalletInformation*.", | ||
| "operationId": "get_extended_address_information_getExtendedAddressInformation_get", | ||
| "summary": "Detect address", | ||
| "description": "Validates an address and returns it in all standard formats. Use this to convert between address formats or to validate user input. Returns raw format (0:abc), base64 bounceable (EQ), base64 non-bounceable (UQ), and URL-safe variants.", |
ecosystem/api/toncenter/v2.json
Outdated
| "operationId": "get_extended_address_information_getExtendedAddressInformation_get", | ||
| "summary": "Detect address", | ||
| "description": "Validates an address and returns it in all standard formats. Use this to convert between address formats or to validate user input. Returns raw format (0:abc), base64 bounceable (EQ), base64 non-bounceable (UQ), and URL-safe variants.", | ||
| "operationId": "detectAddress_get", |
There was a problem hiding this comment.
Since this is related to the user-friendly address flag, it should be accurately explained, that this is representation. This flag not 100% defined, whether the account of qiured address belongs only to the Testnet or Mainnet, because the address itself matches within both networks.

ecosystem/api/toncenter/v2.json
Outdated
| ], | ||
| "summary": "Detect address", | ||
| "description": "Validates an address and returns it in all standard formats. Use this to convert between address formats or to validate user input. Returns raw format (0:abc...), base64 bounceable (EQ...), base64 non-bounceable (UQ...), and URL-safe variants.", | ||
| "operationId": "detectAddress_post", |
There was a problem hiding this comment.
For the /api/v2/detectAddress method, address description:

It's better to make a compact definition and add a link:
Account address in raw format (e.g., 0:ca6e321c...) or User-friendly format (e.g., EQDKbjIcfM6ezt8KjKJJLshZJJSqX7XOA4ff-W72r5gqPrHF)
ecosystem/api/toncenter/v2.json
Outdated
| "hash": { | ||
| "name": "hash", | ||
| "in": "query", | ||
| "description": "A 256-bit hash in hex (64 chars) or base64 (44 chars) format. Used to identify blocks, transactions, and messages uniquely.", |
ecosystem/api/toncenter/v2.json
Outdated
| "type": "array", | ||
| "items": { | ||
| "$ref": "#/components/schemas/ExtraCurrencyBalance" | ||
|
|
There was a problem hiding this comment.
Let's define response description with the "Returns" verb. In this way, we avoid overusing "Response," and the description sounds more direct.
Example: Returns the hash of the requested resource in all supported formats (hex, base64, base64 URL-safe).
Can we remove the word "OK" from this description? "OK" is an excess word here.
ecosystem/api/toncenter/v2.json
Outdated
| "type": "array", | ||
| "items": { | ||
| "$ref": "#/components/schemas/ExtraCurrencyBalance" | ||
|
|
There was a problem hiding this comment.
A Boolean parameter is better suited to describe straightforward boolean values:
Example: Returns true if the request succeeded; otherwise false. See the error field for details.
ecosystem/api/toncenter/v2.json
Outdated
| } | ||
| } | ||
| ], | ||
| "description": "The response data. Only present when `ok` is true. " |
ecosystem/api/toncenter/v2.json
Outdated
| "b64": { | ||
| "type": "string", | ||
| "title": "base64 form", | ||
| "description": "Standard base64 encoding." |
ecosystem/api/toncenter/v2.json
Outdated
| "summary": "Pack address", | ||
| "description": "Converts a raw address to user-friendly base64 format. Raw addresses use the format `workchain:hex` (e.g., `0:abc...`). The packed format is shorter and includes a checksum for error detection.", | ||
| "operationId": "packAddress_post", | ||
| "requestBody": { |
ecosystem/api/toncenter/v2.json
Outdated
| "properties": { | ||
| "hash": { | ||
| "$ref": "#/components/schemas/TonHash", | ||
| "description": "Unique identifier hash for this object." |
There was a problem hiding this comment.
This object - unclear. Let's specify a list of potential entities here: message, transaction, account?
ecosystem/api/toncenter/v2.json
Outdated
| "type": "array", | ||
| "items": { | ||
| "$ref": "#/components/schemas/ExtraCurrencyBalance" | ||
|
|
This comment has been minimized.
This comment has been minimized.
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
|
https://companyname-a7d5b98e-fields.mintlify.app/ecosystem/api/toncenter/v2/accounts/get-address-information#response-result-balance This description seems very clear to me, but I'm afraid any potential reader who opens this method from the beginning will not be able to get how to interact with this data and where to get a complete explanation on decimals (for jettons) and TONs, nanotons terms. It will be much more helpful if we find related links on these terms and point to them on such a balanced field, or add a bit more information in plain text itself. I didn't find separate section in Jetton docs, but I had same task in my page. Maybe we can ask docs team add this as separate page or chapter in jetton documentation and then refer to this. https://companyname-a7d5b98e-fields.mintlify.app/standard/tokens/jettons/overview
|
| @@ -1,3772 +1,8267 @@ | |||
| { | |||
| "openapi": "3.1.0", | |||
| "openapi": "3.1.1", | |||
There was a problem hiding this comment.
Response description seems duplicated in https://companyname-a7d5b98e-fields.mintlify.app/ecosystem/api/toncenter/v2/accounts/get-extended-address-information#parameter-seqno

Let's refactor to one informative sentence.
| } | ||
| }, | ||
| "/getExtendedAddressInformation": { | ||
| "/api/v2/getExtendedAddressInformation": { | ||
| "get": { | ||
| "tags": [ |
There was a problem hiding this comment.
| "summary": "Get detailed account state (extended)", | ||
| "description": "Similar to previous one but tries to parse additional information for known contract types. This method is based on tonlib's function *getAccountState*. For detecting wallets we recommend to use *getWalletInformation*.", | ||
| "operationId": "get_extended_address_information_getExtendedAddressInformation_get", | ||
| "summary": "Get extended address information", |
There was a problem hiding this comment.
This field confuses some people with different methods.
We have very similar naming for different entities:
- Masterchain seqno
- Shardchain seqno
- Wallet contract seqno
- Custom contract seqno(?)
- something else?
We can't change the field name, but let's always (for all seqno fields in docs) text completely which one we have in the description.
| } | ||
| }, | ||
| "/getAddressBalance": { | ||
| "/api/v2/getAddressState": { |
There was a problem hiding this comment.
Let's add a link to the address states' state documentation: https://docs.ton.org/foundations/status
| } | ||
| }, | ||
| "/packAddress": { | ||
| "/api/v2/getBlockTransactions": { | ||
| "get": { |
There was a problem hiding this comment.
We have very similar naming for different entities:
- Masterchain block sequence number
- Shardchain block sequence number
- Wallet contract (operation or transaction) sequence number
- Custom contract (operation or transaction) sequence number(?)
- something else?
We can't change the field name, but let's always (for all seqno fields in the docs) specify the exact one we have in the description.
| "operationId": "pack_address_packAddress_get", | ||
| "summary": "Get block transactions", | ||
| "description": "Returns a summary of transactions in a specific block. Each item contains the account address and transaction ID, but not full transaction details. Use `count` to limit results and `after_lt`/`after_hash` for pagination. Call getTransactions with each transaction ID to get full details.", | ||
| "operationId": "getBlockTransactions_get", |
| "get": { | ||
| "tags": [ | ||
| "Accounts" | ||
| "Transactions" |
There was a problem hiding this comment.
| ], | ||
| "summary": "Convert user-friendly address to raw format", |
There was a problem hiding this comment.
| ], | ||
| "summary": "Convert user-friendly address to raw format", | ||
| "description": "Convert an address from human-readable to raw format.", |
There was a problem hiding this comment.
| "summary": "Convert user-friendly address to raw format", | ||
| "description": "Convert an address from human-readable to raw format.", | ||
| "operationId": "unpack_address_unpackAddress_get", | ||
| "summary": "Get block transactions (extended)", |
| "description": "Convert an address from human-readable to raw format.", | ||
| "operationId": "unpack_address_unpackAddress_get", | ||
| "summary": "Get block transactions (extended)", | ||
| "description": "Returns full transaction objects for all transactions in a specific block. Each transaction includes complete data: inbound and outbound messages, fees, state changes, and BOC-encoded raw data. Use `count` to limit results and `after_lt`/`after_hash` for pagination when `incomplete` is true.", |
| } | ||
| }, | ||
| "/getMasterchainInfo": { | ||
| "/api/v2/getTransactions": { | ||
| "get": { |
| } | ||
| }, | ||
| "/getMasterchainBlockSignatures": { | ||
| "/api/v2/getTransactionsStd": { | ||
| "get": { |
| } | ||
| }, | ||
| "/getShardBlockProof": { | ||
| "/api/v2/tryLocateTx": { | ||
| "get": { |
There was a problem hiding this comment.
It's better to define, as "extra currencies", since "non-TON currencies" may be misread and mixed with jetton tokens, which may still appear in the same message.
| } | ||
| }, | ||
| "/getMasterchainBlockSignatures": { |
There was a problem hiding this comment.
| } | ||
| }, | ||
| "/sendBoc": { | ||
| "/api/v2/runGetMethod": { |
There was a problem hiding this comment.
| "content": { | ||
| "application/json": { | ||
| "schema": { | ||
| "$ref": "#/components/schemas/TonResponse" | ||
| "$ref": "#/components/schemas/SendBocReturnHashResponse" |
There was a problem hiding this comment.
Please specify the hash algorithm in the description. Let's add a link to the normalized hash standard.
https://github.com/ton-blockchain/TEPs/blob/master/text/0467-normalized-message-hash.md











































closes #1049