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.

reveloper · 2026-03-04T01:07:12Z

ecosystem/api/toncenter/v2.json

      }
    },
-    "/getShardBlockProof": {
+    "/api/v2/tryLocateTx": {


Please unite the "Response" description in a single description.

https://companyname-a7d5b98e-fields.mintlify.app/ecosystem/api/toncenter/v2/transactions/try-locate-transaction#parameter-created-lt

reveloper · 2026-03-04T01:28:46Z

ecosystem/api/toncenter/v2.json

      }
    },
-    "/getShardBlockProof": {
+    "/api/v2/tryLocateTx": {
      "get": {


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.

https://companyname-a7d5b98e-fields.mintlify.app/ecosystem/api/toncenter/v2/transactions/try-locate-transaction#response-result-in-msg-extra-currencies

reveloper · 2026-03-04T01:50:16Z

ecosystem/api/toncenter/v2.json

      }
    },
-    "/getMasterchainInfo": {
+    "/api/v2/getTransactions": {


Please, rephrase this in synergetic text

https://companyname-a7d5b98e-fields.mintlify.app/ecosystem/api/toncenter/v2/blocks/get-masterchain-info#authorization-x-api-key

reveloper · 2026-03-04T02:04:35Z

ecosystem/api/toncenter/v2.json

      }
    },
-    "/getMasterchainInfo": {
+    "/api/v2/getTransactions": {


Please specify the hash algorithm

https://companyname-a7d5b98e-fields.mintlify.app/ecosystem/api/toncenter/v2/blocks/get-masterchain-info#response-result-state-root-hash

reveloper · 2026-03-04T02:18:03Z

ecosystem/api/toncenter/v2.json

      }
    },
-    "/getMasterchainBlockSignatures": {


Page broken?

https://companyname-a7d5b98e-fields.mintlify.app/ecosystem/api/toncenter/v2/blocks/get-masterchain-block-signatures

reveloper · 2026-03-04T03:02:18Z

ecosystem/api/toncenter/v2.json

      }
    },
-    "/getConfigAll": {
+    "/api/v2/getBlockHeader": {


Please, add formatting to variables:
workchain, shard, seqno, root_hash, file_hash, start_lt, and end_lt.

https://companyname-a7d5b98e-fields.mintlify.app/ecosystem/api/toncenter/v2/blocks/get-block-header#response-result-end-lt

reveloper · 2026-03-04T03:06:40Z

ecosystem/api/toncenter/v2.json

      }
    },
-    "/getConfigAll": {
+    "/api/v2/getBlockHeader": {
      "get": {


seqno always should be formatted as code in text

https://companyname-a7d5b98e-fields.mintlify.app/ecosystem/api/toncenter/v2/blocks/get-block-header#response-result-min-ref-mc-seqno

reveloper · 2026-03-04T03:12:57Z

ecosystem/api/toncenter/v2.json

      }
    },
-    "/tryLocateResultTx": {
+    "/api/v2/getOutMsgQueueSize": {


Rework the response description to one fit text.

https://companyname-a7d5b98e-fields.mintlify.app/ecosystem/api/toncenter/v2/blocks/get-outbound-message-queue-size#authorization-x-api-key

reveloper · 2026-03-04T03:18:35Z

ecosystem/api/toncenter/v2.json

      }
    },
-    "/sendBoc": {
+    "/api/v2/runGetMethod": {


Let's add the link to exit codes https://docs.ton.org/tvm/exit-codes#exit-codes

https://companyname-a7d5b98e-fields.mintlify.app/ecosystem/api/toncenter/v2/run-method/run-get-method#response-result-exit-code

reveloper · 2026-03-04T03:24:31Z

ecosystem/api/toncenter/v2.json

            "content": {
              "application/json": {
                "schema": {
-                  "$ref": "#/components/schemas/TonResponse"
+                  "$ref": "#/components/schemas/SendBocReturnHashResponse"


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

https://companyname-a7d5b98e-fields.mintlify.app/ecosystem/api/toncenter/v2/send/send-boc-return-hash#response-result-hash

reveloper · 2026-03-09T05:08:09Z

LGTM, Ready for review.

github-actions

No documentation issues detected.

memearchivarius

Why source description is different from destination?

memearchivarius · 2026-03-10T08:45:00Z

ecosystem/api/toncenter/v2.json

+          },
+          "message": {
+            "type": "string",
+            "descripti


Suggested change

"descripti

"description": "Array of fee breakdowns charged on the receiving account. Each entry contains `in_fwd_fee`, `storage_fee`, `gas_fee`, and `fwd_fee` in nanotons (integers)."

@memearchivarius Great catch! I fixed it, please let me know if it looks good to you know.

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

reveloper requested changes Mar 4, 2026

View reviewed changes

laviniat1996 added 3 commits March 5, 2026 04:39

address comments

3db86db

Merge branch 'main' into fields

0a6fc7e

fixes

0f941ec

mintlify bot deployed to staging March 5, 2026 02:48 View deployment

fix broken pages

0fcccae

mintlify bot deployed to staging March 9, 2026 04:32 View deployment

mintlify bot deployed to staging March 9, 2026 04:35 View deployment

add count parameter validation bounds

6e98056

laviniat1996 force-pushed the fields branch from 144d5d7 to 6e98056 Compare March 9, 2026 04:57

Merge branch 'main' into fields

8d758a9

mintlify bot deployed to staging March 9, 2026 04:58 View deployment

reveloper marked this pull request as ready for review March 9, 2026 05:08

reveloper previously approved these changes Mar 9, 2026

View reviewed changes

github-actions bot reviewed Mar 9, 2026

View reviewed changes

reveloper added the scope: api OpenAPI specs and relevant sub-directories in the /ecosystem/api/ folders label Mar 9, 2026

memearchivarius requested changes Mar 10, 2026

View reviewed changes

mintlify bot deployed to staging March 11, 2026 16:24 View deployment

fix description

f83a1e8

laviniat1996 dismissed reveloper’s stale review via f83a1e8 March 12, 2026 07:20

laviniat1996 force-pushed the fields branch from b388c9a to f83a1e8 Compare March 12, 2026 07:20

Merge branch 'main' into fields

3e2c5b7

mintlify bot deployed to staging March 12, 2026 07:22 View deployment

Merge branch 'main' into fields

c94ba83

mintlify bot deployed to staging March 18, 2026 06:53 View deployment

Merge branch 'main' into fields

fc67510

mintlify bot deployed to staging March 18, 2026 14:02 View deployment

	"descripti
	"description": "Array of fee breakdowns charged on the receiving account. Each entry contains `in_fwd_fee`, `storage_fee`, `gas_fee`, and `fwd_fee` in nanotons (integers)."

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.

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!

reveloper commented Mar 9, 2026

Uh oh!

github-actions bot left a comment

Choose a reason for hiding this comment

Uh oh!

memearchivarius left a comment

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

reveloper Dec 4, 2025 •

edited

Loading