feat(api): update API v2 field descriptions by laviniat1996 · Pull Request #1469 · ton-org/docs

laviniat1996 · 2025-11-28T03:29:27Z

github-actions · 2025-11-28T03:29:42Z

Skipping AI review because no docs changes in md, mdx, or docs.json

reveloper · 2025-12-04T07:15:39Z

ecosystem/api/toncenter/v2.json

        ],
+        "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.",


Authorizations description shouldn't be empty:

Example of a good definition:

reveloper · 2025-12-04T07:45:38Z

ecosystem/api/toncenter/v2.json

+        "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": {


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?

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

reveloper · 2025-12-04T08:05:20Z

ecosystem/api/toncenter/v2.json

        ],
+        "summary": "Detect address",


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

reveloper · 2025-12-04T08:27:10Z

ecosystem/api/toncenter/v2.json

+        "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": {


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

reveloper · 2025-12-04T08:45:42Z

ecosystem/api/toncenter/v2.json

-        "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.",


All fields should be fully self-descriptive without dependency on other fields:

Example:
description: User-friendly bounceable address in standard base64 encoding.
description: User-friendly bounceable address, base64-encoded and safe for use in URLs.

reveloper · 2025-12-04T08:55:57Z

ecosystem/api/toncenter/v2.json

-        "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",


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.

reveloper · 2025-12-08T09:57:29Z

ecosystem/api/toncenter/v2.json

        ],
+        "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",


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)

reveloper · 2025-12-08T10:06:42Z

ecosystem/api/toncenter/v2.json

+      "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.",


This description duplicated with another one in render:

reveloper · 2025-12-08T11:09:47Z

ecosystem/api/toncenter/v2.json

+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/ExtraCurrencyBalance"
+


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.

reveloper · 2025-12-08T11:25:14Z

ecosystem/api/toncenter/v2.json

+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/ExtraCurrencyBalance"
+


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.

reveloper · 2025-12-08T11:29:00Z

ecosystem/api/toncenter/v2.json

+                }
+              }
+            ],
+            "description": "The response data. Only present when `ok` is true. "


true should be formatted as code.

reveloper · 2025-12-08T11:30:57Z

ecosystem/api/toncenter/v2.json

+          "b64": {
+            "type": "string",
+            "title": "base64 form",
+            "description": "Standard base64 encoding."


Add a full self-defined description for each child field.

reveloper · 2025-12-08T11:35:19Z

ecosystem/api/toncenter/v2.json

+        "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": {


Duplicated address field description

reveloper · 2025-12-09T07:41:25Z

ecosystem/api/toncenter/v2.json

+        "properties": {
+          "hash": {
+            "$ref": "#/components/schemas/TonHash",
+            "description": "Unique identifier hash for this object."


This object - unclear. Let's specify a list of potential entities here: message, transaction, account?

reveloper · 2025-12-09T08:12:11Z

ecosystem/api/toncenter/v2.json

+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/ExtraCurrencyBalance"
+


If we have no child object specified, let's describe this in the overall description. Add self-completed description here, what will be in this data by type, encoding e.t.c.

laviniat1996 · 2026-02-18T09:19:42Z

@novusnota There is an issue with the wallet info page. It doesn't render unless I remove ecosystem/api/toncenter/v2/accounts/get-wallet-information.mdx

github-actions

Thanks for the updates to ecosystem/api/toncenter/v2-tonlib-types.mdx and ecosystem/api/toncenter/v2.json; I have several consistency and style improvements to suggest. Please apply the inline suggestions to align the references and endpoint descriptions with the documentation guidelines.

github-actions · 2026-02-18T09:26:17Z

ecosystem/api/toncenter/v2-tonlib-types.mdx

+
+Every object returned by API v2 includes an `@type` field that identifies the object's structure. These values originate from two sources:
+
+- **TonLib types** (e.g. `raw.fullAccountState`, `tvm.cell`) come from the [TonLib TL schema](https://github.com/ton-blockchain/ton/blob/master/tl/generate/scheme/tonlib_api.tl), the type definition language used by the C++ library powering this API.


[HIGH] Non-permalink GitHub reference to TonLib schema

The TonLib TL schema link uses the moving master branch URL on GitHub instead of a commit- or tag-based permalink. For normative, precision‑critical references, this makes the documentation non-reproducible over time because the linked content can change independently of the docs. The extended style guide requires using stable permalinks (e.g., a specific commit hash) for external specs.

Suggested change

- **TonLib types** (e.g. `raw.fullAccountState`, `tvm.cell`) come from the [TonLib TL schema](https://github.com/ton-blockchain/ton/blob/master/tl/generate/scheme/tonlib_api.tl), the type definition language used by the C++ library powering this API.

Please leave a reaction 👍/👎 to this suggestion to improve future reviews for everyone!

ecosystem/api/toncenter/v2-tonlib-types.mdx

github-actions · 2026-02-18T09:26:17Z

ecosystem/api/toncenter/v2-tonlib-types.mdx

+  "@type": "raw.fullAccountState",
+  "balance": "1000000000",
+  "code": "te6cc...",
+  "data": "te6cc...",
+  "last_transaction_id": {
+    "@type": "internal.transactionId",
+    "lt": "12345678",
+    "hash": "abc..."


[HIGH] Silently truncated address/hash values in JSON example

The JSON example on lines 17–24 uses visibly truncated values such as "code": "te6cc...", "data": "te6cc...", and "hash": "abc..." without any explanation that they are shortened for illustration. The extended style guide states that address and hash values must not be silently truncated; when truncation improves readability, the text must explicitly call it out and indicate that the values are not meant to be copied. As written, a reader might treat these as real, copyable values, which conflicts with this HIGH-severity rule. Adding a short note before the code block keeps the example readable while making the truncation explicit.

Please leave a reaction 👍/👎 to this suggestion to improve future reviews for everyone!

ecosystem/api/toncenter/v2-tonlib-types.mdx

ecosystem/api/toncenter/v2.json

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

reveloper · 2026-02-19T05:03:37Z

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
https://companyname-a7d5b98e-fields.mintlify.app/ecosystem/wallet-apps/deep-links#read-more:~:text=One%20whole%20Jetton%20for%20%3CAMOUNT%3E%20is%20defined%20by

reveloper · 2026-02-19T05:05:39Z

https://companyname-a7d5b98e-fields.mintlify.app/ecosystem/api/toncenter/v2/accounts/get-address-information
Descripted twice?

reveloper · 2026-02-19T05:19:00Z

Is it possible to share here an arbitrary example that appears to be real data? If so, is it worth separate task to make this for all methods? Does the OpenAPI v3 JSON content affect this somehow?

reveloper · 2026-02-19T05:25:10Z

https://companyname-a7d5b98e-fields.mintlify.app/ecosystem/api/toncenter/v2/accounts/get-extended-address-information#option-5

Can we enter self-described names here instead of "Option 1", "Option 2", etc.? text?

reveloper · 2026-02-19T05:29:00Z

Seems that we shouldn't provide this until we didn't prepare workable examples like
JavaScript - via @ton/ton
Java - via ton4j
Could you hide all languages and keep the visible curl only for now?
And create a separate task: make a workable example request field with fully supported libraries (@ton/ton, ton4j, ton-utils (Go), ton-utils(Python)).

laviniat1996 · 2026-02-19T14:13:13Z

Is it possible to share here an arbitrary example that appears to be real data? If so, is it worth separate task to make this for all methods? Does the OpenAPI v3 JSON content affect this somehow?

I think it's better to create a new task, as it would be a lot of examples which would make this PR even harder to review.

laviniat1996 · 2026-02-19T14:14:19Z

Seems that we shouldn't provide this until we didn't prepare workable examples like JavaScript - via @ton/ton Java - via ton4j Could you hide all languages and keep the visible curl only for now? And create a separate task: make a workable example request field with fully supported libraries (@ton/ton, ton4j, ton-utils (Go), ton-utils(Python)).

These code snippets are fully autogenerated by mintlify, I don't have control over them tbh

laviniat1996 added 2 commits November 28, 2025 05:27

update field descriptions

00366ae

Merge branch 'main' into fields

b6eee23

laviniat1996 self-assigned this Nov 28, 2025

laviniat1996 marked this pull request as draft November 28, 2025 03:30

mintlify bot deployed to staging November 28, 2025 03:30 View deployment

laviniat1996 changed the title ~~update field descriptions~~ update API v2 field descriptions Nov 28, 2025

laviniat1996 added the 3p Reviewed by someone else (a third party). Used for filtering PRs. Don't mind this. label Dec 1, 2025

reveloper self-requested a review December 4, 2025 06:09

reveloper requested changes Dec 4, 2025

View reviewed changes

Merge branch 'main' into fields

87fe3f6

mintlify bot deployed to staging December 8, 2025 09:37 View deployment

reveloper requested changes Dec 8, 2025

View reviewed changes

reveloper requested changes Dec 9, 2025

View reviewed changes

Merge branch 'main' into fields

4e0cc6c

mintlify bot deployed to staging February 17, 2026 13:12 View deployment

error updates

eaef911

mintlify bot deployed to staging February 17, 2026 14:43 View deployment

updates

d0a488f

laviniat1996 changed the title ~~update API v2 field descriptions~~ docs (feat): update API v2 field descriptions Feb 17, 2026

laviniat1996 changed the title ~~docs (feat): update API v2 field descriptions~~ feat (docs): update API v2 field descriptions Feb 17, 2026

mintlify bot deployed to staging February 17, 2026 14:58 View deployment

laviniat1996 changed the title ~~feat (docs): update API v2 field descriptions~~ feat(docs): update API v2 field descriptions Feb 17, 2026

mintlify bot deployed to staging February 18, 2026 06:14 View deployment

updates

76f13c0

laviniat1996 force-pushed the fields branch from b2b2ae2 to 76f13c0 Compare February 18, 2026 08:07

Merge branch 'main' into fields

10e0c23

This comment has been minimized.

Sign in to view

laviniat1996 requested a review from novusnota February 18, 2026 09:20

github-actions bot reviewed Feb 18, 2026

View reviewed changes

reveloper marked this pull request as draft February 18, 2026 09:37

laviniat1996 and others added 2 commits February 19, 2026 06:17

Update ecosystem/api/toncenter/v2-tonlib-types.mdx

95292c8

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Update ecosystem/api/toncenter/v2-tonlib-types.mdx

3e972b4

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

mintlify bot deployed to staging February 19, 2026 04:18 View deployment

Update ecosystem/api/toncenter/v2.json

c3a9d9c

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

mintlify bot deployed to staging February 19, 2026 04:18 View deployment

laviniat1996 and others added 5 commits February 19, 2026 06:18

Update ecosystem/api/toncenter/v2.json

2cb4d96

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Update ecosystem/api/toncenter/v2.json

afa4c0f

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Update ecosystem/api/toncenter/v2.json

7df77e0

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Update ecosystem/api/toncenter/v2.json

bf12b55

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Update ecosystem/api/toncenter/v2.json

6e03f08

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

mintlify bot deployed to staging February 19, 2026 04:20 View deployment

Merge branch 'main' into fields

051c8a3

mintlify bot deployed to staging February 19, 2026 04:20 View deployment

mintlify bot deployed to staging February 19, 2026 04:21 View deployment

mintlify bot deployed to staging February 19, 2026 04:22 View deployment

mintlify bot deployed to staging February 19, 2026 04:32 View deployment

laviniat1996 mentioned this pull request Feb 19, 2026

[Ecosystem > API > TON Center > API v2 > Tonlib Types] #1870

Open


		Every object returned by API v2 includes an `@type` field that identifies the object's structure. These values originate from two sources:

		- TonLib types (e.g. `raw.fullAccountState`, `tvm.cell`) come from the [TonLib TL schema](https://github.com/ton-blockchain/ton/blob/master/tl/generate/scheme/tonlib_api.tl), the type definition language used by the C++ library powering this API.

Comments

Conversation

laviniat1996 commented Nov 28, 2025

Uh oh!

github-actions bot commented Nov 28, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

reveloper Dec 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This comment has been minimized.

laviniat1996 commented Feb 18, 2026

Uh oh!

github-actions bot left a comment

Choose a reason for hiding this comment

Uh oh!

github-actions bot Feb 18, 2026

Choose a reason for hiding this comment

[HIGH] Non-permalink GitHub reference to TonLib schema

Uh oh!

Uh oh!

github-actions bot Feb 18, 2026

Choose a reason for hiding this comment

[HIGH] Silently truncated address/hash values in JSON example

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

reveloper commented Feb 19, 2026

Uh oh!

reveloper commented Feb 19, 2026

Uh oh!

reveloper commented Feb 19, 2026

Uh oh!

reveloper commented Feb 19, 2026

Uh oh!

reveloper commented Feb 19, 2026

Uh oh!

laviniat1996 commented Feb 19, 2026

Uh oh!

laviniat1996 commented Feb 19, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

reveloper Dec 4, 2025 •

edited

Loading