Skip to main content
Version: 2.0.0

Blockchain API - Token City

REST API for queries and transaction generation on the blockchain networks where Token City operates.

This is v2.0.0 — the next major version still under construction. v1.8.1 is the current stable version. See breaking changes below before migrating.

Breaking changes from v1.8.1​

1. URL versioning prefix​

All v2.0.0 endpoints use a /v2/ path prefix (e.g. GET /v2/tokens/{tokenId}/holders). v1.8.1 had no prefix. You must prepend /v2/ to every path when migrating.

2. Paginated list response shape​

In v1.8.1 list endpoints returned a bare JSON array [ ... ]. In v2.0.0 every list endpoint returns a paginated envelope:

{ "items": [ ... ], "hasNext": true, "nextCursor": "..." }

Consumers that destructure or iterate the response directly must be updated.

Authentication​

All endpoints require HMAC authentication via three request headers:

  • Authorization: your API key
  • Date: UTC request timestamp in RFC 7231 format (e.g. Fri, 02 Feb 1996 03:04:05 GMT)
  • Signature: TC sha256 <hex-encoded-HMAC-SHA256-signature>

Error format​

All error responses use a consistent JSON envelope:

{ "success": false, "status": 400, "result": { "error": { "message": "..." } }, "requestId": "uuid" }

The requestId field is also returned as the X-Request-Id response header for correlation and support purposes.

What's new in v2.0.0​

The following endpoints are new in v2.0.0 with no v1.8.1 counterpart (marked x-new-in-v2: true in the spec):

  • POST /v2/erc1155/{tokenId}/mint — ERC-1155 multi-token mint
  • POST /v2/erc1155/{tokenId}/mint/eip712-typed-data — ERC-1155 EIP-712 typed data
  • POST /v2/erc1155/{tokenId}/transfer — ERC-1155 token transfer
  • POST /v2/erc1155/{tokenId}/upload-documents — physical asset document upload to Arweave
  • POST /v2/erc1155/{tokenId}/burn — ERC-1155 burn with signature
  • POST /v2/erc1155/{tokenId}/burn/eip712-typed-data — ERC-1155 burn EIP-712 typed data
  • POST /v2/erc1155/{tokenId}/burn-batch — ERC-1155 batch burn with signature
  • POST /v2/erc1155/{tokenId}/burn-batch/eip712-typed-data — ERC-1155 batch burn EIP-712 typed data
  • POST /v2/erc20/{tokenId}/transfer — ERC-20 transfer (new path pattern)
  • POST /v2/sponsored-transfer/{tokenId}/execute — gas-sponsored ERC-20 transfer (gas-station model; the platform funds the investor wallet's gas)
  • POST /v2/factory/erc3643-diamond — Diamond proxy (ERC-2535) token deployment
  • POST /v2/factory/erc3643-diamond/eip712-typed-data — Diamond deployment EIP-712 typed data
  • POST /v2/factory/erc3643-diamond/compute-address — Compute the CREATE2 address of an ERC-3643 Diamond token before deployment
  • POST /v2/factory/erc1155/compute-address — Compute the CREATE2 address of an ERC-1155 token before deployment
  • POST /v2/factory/erc721/compute-address — Compute the CREATE2 address of an ERC-721 token before deployment
  • POST|GET /v2/erc3643/{tokenId}/bond — Bond parameter configuration and retrieval
  • GET /v2/erc3643/{tokenId}/bond/{holder}/earned-interest — Per-holder earned interest query
  • POST /v2/erc3643/{tokenId}/roles/grant — Grant an access-control role on an ERC-3643Diamond token
  • POST /v2/erc3643/{tokenId}/roles/revoke — Revoke an access-control role on an ERC-3643Diamond token
  • GET|POST /v2/approvals/{tokenId}/permit — ERC-20 permit approval
  • GET /v2/tokens/{tokenId}/accounts/{accountId}/burns — Per-account burn history

Deployment schemas​

v2.0.0 supports two ERC-3643 factory deployment paths with different response shapes:

  • POST /v2/factory/erc3643 — standard deployment, returns TokenDeployed ({ result: { id, contractId, message, contractAddress } })
  • POST /v2/factory/erc3643-diamond — Diamond proxy deployment, returns TokenDiamondDeployed (same shape with a required constraint on all result fields)

Authentication​

Token City HMAC authentication. Authorization header = API key. Date header = UTC timestamp (RFC 7231). Signature header = TC sha256 <hex-encoded-HMAC-SHA256>.

Security Scheme Type:

apiKey

Header parameter name:

Authorization

Contact

Token City Support: support@token-city.com

URL: https://token-city.com