Skip to content

feat(api): update API v2 field descriptions#1469

Draft
laviniat1996 wants to merge 26 commits intomainfrom
fields
Draft

feat(api): update API v2 field descriptions#1469
laviniat1996 wants to merge 26 commits intomainfrom
fields

Conversation

@laviniat1996
Copy link
Collaborator

closes #1049

@github-actions
Copy link

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

@laviniat1996 laviniat1996 self-assigned this Nov 28, 2025
@laviniat1996 laviniat1996 marked this pull request as draft November 28, 2025 03:30
@laviniat1996 laviniat1996 changed the title update field descriptions update API v2 field descriptions Nov 28, 2025
@laviniat1996 laviniat1996 added the 3p Reviewed by someone else (a third party). Used for filtering PRs. Don't mind this. label Dec 1, 2025
@reveloper reveloper self-requested a review December 4, 2025 06:09
],
"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.",
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Authorizations description shouldn't be empty:
Screenshot 0007-12-04 at 15 48 37

Example of a good definition:
Screenshot 0007-12-04 at 16 13 19

"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": {
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

https://companyname-a7d5b98e-fields.mintlify.app/ecosystem/api/toncenter/v2/rpc/json-rpc-endpoint

Result field seems strange and broken:

Screenshot 0007-12-04 at 16 43 07 Screenshot 0007-12-04 at 16 43 11

Does it really have two options?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

],
"summary": "Detect address",
Copy link
Collaborator

@reveloper reveloper Dec 4, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The field definition is wrong, which works from ANY form of TON Address:

Screenshot 0007-12-04 at 16 59 47

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

"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": {
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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:
Screenshot 0007-12-04 at 17 17 29

https://companyname-a7d5b98e-fields.mintlify.app/ecosystem/api/toncenter/v2/rpc/detect-address

"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.",
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All fields should be fully self-descriptive without dependency on other fields:
Screenshot 0007-12-04 at 17 29 14

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

"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",
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.
Screenshot 0007-12-04 at 17 51 53

],
"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",
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For the /api/v2/detectAddress method, address description:
Screenshot 0007-12-08 at 18 50 32

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)

"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.",
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This description duplicated with another one in render:
Screenshot 0007-12-08 at 18 50 32

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

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Screenshot 0007-12-08 at 20 06 37

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.

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

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

true should be formatted as code.

Screenshot 0007-12-08 at 20 26 51

"b64": {
"type": "string",
"title": "base64 form",
"description": "Standard base64 encoding."
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Screenshot 0007-12-08 at 20 29 28

"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": {
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Duplicated address field description
Screenshot 0007-12-08 at 20 32 05

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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

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

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Screenshot 0007-12-09 at 17 11 57

@laviniat1996 laviniat1996 changed the title update API v2 field descriptions docs (feat): update API v2 field descriptions Feb 17, 2026
@laviniat1996 laviniat1996 changed the title docs (feat): update API v2 field descriptions feat (docs): update API v2 field descriptions Feb 17, 2026
@laviniat1996 laviniat1996 changed the title feat (docs): update API v2 field descriptions feat(docs): update API v2 field descriptions Feb 17, 2026
@github-actions

This comment has been minimized.

laviniat1996 and others added 3 commits February 19, 2026 06:19
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>
@reveloper
Copy link
Collaborator

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

Screenshot 0008-02-19 at 13 52 03

@reveloper
Copy link
Collaborator

@reveloper
Copy link
Collaborator

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?

Screenshot 0008-02-19 at 14 16 54

@reveloper
Copy link
Collaborator

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?
Screenshot 0008-02-19 at 14 24 55

@reveloper
Copy link
Collaborator

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)).

Screenshot 0008-02-19 at 14 25 50

@laviniat1996
Copy link
Collaborator Author

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?

Screenshot 0008-02-19 at 14 16 54

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
Copy link
Collaborator Author

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)).

Screenshot 0008-02-19 at 14 25 50

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

@@ -1,3772 +1,8267 @@
{
"openapi": "3.1.0",
"openapi": "3.1.1",
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

}
},
"/getExtendedAddressInformation": {
"/api/v2/getExtendedAddressInformation": {
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Give a descriptive name instead of "Option #"
In the description, recall how the option will be defined in the Toncenter api/v2.

Image

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

}
},
"/getExtendedAddressInformation": {
"/api/v2/getExtendedAddressInformation": {
"get": {
"tags": [
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"get": {
"tags": [
"Accounts"
],
"summary": "Get detailed account state (extended)",
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"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",
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Image

https://companyname-a7d5b98e-fields.mintlify.app/ecosystem/api/toncenter/v2/accounts/get-address-balance#parameter-seqno

}
},
"/getAddressBalance": {
"/api/v2/getAddressState": {
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

}
},
"/getAddressState": {
"/api/v2/getTokenData": {
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Add accurate link to supported contract types will be helpful in the description and field:

https://companyname-a7d5b98e-fields.mintlify.app/ecosystem/api/toncenter/v2-tonlib-types#token-types-ton-center-extensions

Image Image

}
},
"/getAddressState": {
"/api/v2/getTokenData": {
"get": {
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Description a bit duplicated, can we make this:
Storage method for token (jetton) metadata content:
onchain - stored in contract data)
offchain - external URI

Image

https://companyname-a7d5b98e-fields.mintlify.app/ecosystem/api/toncenter/v2/accounts/get-token-data#response-result-one-of-0-jetton-content-type

}
},
"/packAddress": {
"/api/v2/getBlockTransactions": {
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

}
},
"/packAddress": {
"/api/v2/getBlockTransactions": {
"get": {
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Image

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.

https://companyname-a7d5b98e-fields.mintlify.app/ecosystem/api/toncenter/v2/transactions/get-block-transactions#parameter-seqno

"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",
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"get": {
"tags": [
"Accounts"
"Transactions"
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

hash may be calculated within different algorithms, can we point to a specific one in our documentation, or at least text its name:

Image

Extra: almost the same fields(hash and lt) described in a different way in English, make the same sentence structure here, to improve readability.

https://companyname-a7d5b98e-fields.mintlify.app/ecosystem/api/toncenter/v2/transactions/get-block-transactions-extended#response-result-transactions-items-transaction-id-hash

],
"summary": "Convert user-friendly address to raw format",
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

],
"summary": "Convert user-friendly address to raw format",
"description": "Convert an address from human-readable to raw format.",
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"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)",
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"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.",
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

}
},
"/getMasterchainInfo": {
"/api/v2/getTransactions": {
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please add the hash algorithm name, which will help to get an idea of how it was calculated.

Image

https://companyname-a7d5b98e-fields.mintlify.app/ecosystem/api/toncenter/v2/transactions/get-transactions#parameter-hash

}
},
"/getMasterchainInfo": {
"/api/v2/getTransactions": {
"get": {
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since Liteservers have no automation for cleaning data, we can text either:
"at least last two days", or "guaranteed last two days"
The word "About" may be read as some nodes may store less than two days of data.
Image

https://companyname-a7d5b98e-fields.mintlify.app/ecosystem/api/toncenter/v2/transactions/get-transactions#parameter-archival

"get": {
"tags": [
"Blocks"
"Transactions"
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we rephrase this to a more detailed description:

Storage fees in nanotons that paid from the account balance (in .. phases) during this transaction.
Image

https://companyname-a7d5b98e-fields.mintlify.app/ecosystem/api/toncenter/v2/transactions/get-transactions#response-result-items-fee

"get": {
"tags": [
"Blocks"
"Transactions"
],
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

}
},
"/getTransactions": {
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

}
},
"/getMasterchainBlockSignatures": {
"/api/v2/getTransactionsStd": {
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is it necessary to point to the version in the description? Seems to exceed information, which possibly may change:

Image

https://companyname-a7d5b98e-fields.mintlify.app/ecosystem/api/toncenter/v2/transactions/get-transactions-standard#response-jsonrpc

}
},
"/getMasterchainBlockSignatures": {
"/api/v2/getTransactionsStd": {
"get": {
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The description consists of two parts that are not completely synergetic. Can we improve this into a single connected text?

Image

}
},
"/getShardBlockProof": {
"/api/v2/tryLocateTx": {
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

}
},
"/getShardBlockProof": {
"/api/v2/tryLocateTx": {
"get": {
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Image

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

}
},
"/getMasterchainInfo": {
"/api/v2/getTransactions": {
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

}
},
"/getMasterchainInfo": {
"/api/v2/getTransactions": {
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

}
},
"/getMasterchainBlockSignatures": {
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

}
},
"/getConfigAll": {
"/api/v2/getBlockHeader": {
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Image

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

}
},
"/getConfigAll": {
"/api/v2/getBlockHeader": {
"get": {
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

}
},
"/tryLocateResultTx": {
"/api/v2/getOutMsgQueueSize": {
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

}
},
"/sendBoc": {
"/api/v2/runGetMethod": {
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TonResponse"
"$ref": "#/components/schemas/SendBocReturnHashResponse"
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

3p Reviewed by someone else (a third party). Used for filtering PRs. Don't mind this.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[TON Center > API/v2 > OpenAPI 3 full field description]

2 participants