--- updatedAt: 2025-06-03T05:23:38.000Z agentTools: projectIndex: https://rootvx.readme.io/llms.txt --- # Create Ledger This endpoint creates a new ledger with specific currency information. The ledger can be defined using either a predefined fiat currency or a custom-defined currency. # OpenAPI definition ```json { "openapi": "3.0.1", "info": { "title": "rootVX Ledger + Wallet", "description": "Interact with the rootVX API to manage users, ledgers, wallets and transactions.", "version": "1.0.0", "contact": { "email": "support@rootpe.com" } }, "servers": [ { "url": "https://api.sandbox.rootvx.com" } ], "security": [ { "BearerAuth": [] } ], "tags": [ { "name": "Ledger" } ], "paths": { "/api/ledger/create": { "post": { "summary": "Create Ledger", "deprecated": false, "description": "This endpoint creates a new ledger with specific currency information. The ledger can be defined using either a predefined fiat currency or a custom-defined currency.", "operationId": "createLedger", "tags": [ "Ledger" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "A unique key to prevent duplicate requests. Typically a UUID.", "required": true, "example": "123e4567-e89b-12d3-a456-426614174000", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LedgerCreateRequest" } } } }, "responses": { "201": { "description": "successful", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LedgerInfoResponse" } } } }, "400": { "description": "bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LedgerInfoResponse" } } } }, "422": { "description": "unsuccessful", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Bearer token for authentication. Format: Bearer " } }, "schemas": { "BalanceType": { "type": "string", "description": "The `BalanceType` field categorizes the status of an account's balance into three enumerated values. POSTED indicates that the balance has been finalized and recorded in the account, PENDING represents a balance that is awaiting confirmation or final processing, and AVAILABLE refers to funds that are currently available for use or withdrawal.", "enum": [ "POSTED", "PENDING", "AVAILABLE" ], "example": "POSTED" }, "Balance": { "type": "object", "properties": { "created_at": { "type": "string", "description": "The `created_at` field records the date and time when the balance was initially established. The date and time are represented in the ISO 8601 format 'YYYY-MM-DDTHH:MM:SS.sssZ', where Z denotes Zulu time (UTC).", "example": "2024-05-27T03:59:17.041Z", "format": "date-time" }, "updated_at": { "type": "string", "description": "The `updated_at` field records the date and time when the balance was initially updated. The date and time are represented in the ISO 8601 format 'YYYY-MM-DDTHH:MM:SS.sssZ', where Z denotes Zulu time (UTC).", "example": "2024-05-27T03:59:17.041Z", "format": "date-time" }, "amount": { "type": "integer", "format": "int64", "description": "The amount field represents the total balance amount as an integer." }, "balance_type": { "$ref": "#/components/schemas/BalanceType" } } }, "LedgerInfo": { "required": [ "name", "id", "createdAt", "decimals", "currencyCode", "availableBalance" ], "type": "object", "properties": { "name": { "type": "string", "description": "The name of the ledger.", "example": "ledger001" }, "id": { "type": "string", "description": "A unique identifier for the ledger, using a UUID format.", "example": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "format": "uuid" }, "address": { "type": "string", "description": "The address of the ledger", "example": "0x12345678902323" }, "createdAt": { "type": "string", "description": "The timestamp of when the ledger was created. The date and time are represented in the ISO 8601 format 'YYYY-MM-DDTHH:MM:SS.sssZ', where Z denotes Zulu time (UTC).", "example": "2024-05-27T03:59:17.041Z", "format": "date-time" }, "updatedAt": { "type": "string", "description": "The timestamp of when the ledger was updated. The date and time are represented in the ISO 8601 format 'YYYY-MM-DDTHH:MM:SS.sssZ', where Z denotes Zulu time (UTC).", "example": "2024-05-27T03:59:17.041Z", "format": "date-time" }, "discardedAt": { "type": "string", "nullable": true, "description": "The timestamp of when the ledger was discarded. The date and time are represented in the ISO 8601 format 'YYYY-MM-DDTHH:MM:SS.sssZ', where Z denotes Zulu time (UTC).", "example": "2024-05-27T03:59:17.041Z", "format": "date-time" }, "availableBalance": { "$ref": "#/components/schemas/Balance" }, "currencyCode": { "type": "string", "description": "The `currencyCode` parameter specifies the three-letter ISO code representing the currency type, such as USD for U.S. Dollars. This code determines the currency used in transactions.", "example": "USD" }, "ledgerPlatformAccount": { "type": "string", "format": "uuid", "description": "The unique identifier of the ledger platform account.", "example": "497f6eca-6276-4993-bfeb-53cbbbba6f08" }, "ledgerPlatformAddress": { "type": "string", "description": "The address of the ledger platform account.", "example": "0x12345678902323" }, "decimals": { "type": "integer", "description": "The `decimals` parameter defines the number of decimal places used for the currency. It is an integer value ranging from 0 to 255, allowing for precise currency calculations and representations.", "format": "uint8", "minimum": 0, "maximum": 255 }, "description": { "type": "string", "nullable": true, "description": "The `description` field is an optional free-form text that provides additional information about the currency." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Additional data represented as key-value pairs. Both the key and value must be strings.", "example": { "mykey": "myvalue1", "mykey1": "myvalue2" }, "properties": {} } } }, "LedgerInfoResponse": { "allOf": [ { "$ref": "#/components/schemas/LedgerInfo" } ] }, "ErrorResponse": { "type": "object", "properties": { "errorCode": { "type": "string", "description": "Specific error code identifying the type of error.", "example": "VSE-001" }, "errorMessage": { "type": "string", "description": "A brief message describing the error.", "example": "ENTITY_NOT_FOUND" }, "details": { "type": "string", "description": "Additional details about the error.", "example": "User entity not found for the given ID." } } }, "CustomCurrencyType": { "type": "string", "description": "The type of the custom currency. For example \"REWARD POINTS\", \"AIR MILES\" or \"USER CREDITS\".", "enum": [ "REWARDPOINTS", "AIRMILES", "USERCREDITS", "ASSETTOKEN" ] }, "CustomCurrencyInfo": { "properties": { "currencyCode": { "type": "string", "description": "A unique code representing the custom currency, such as \"VAM\". Minimum 3 characters and maximum 6 charactetrs No lowercase letters, numbers, or special characters are allowed.", "pattern": "^[A-Z]*$", "minLength": 3, "maxLength": 6, "example": "VAM" }, "customCurrencyType": { "$ref": "#/components/schemas/CustomCurrencyType" }, "description": { "type": "string", "description": "A brief description of the custom currency.", "example": "Custom currency for Vistara Air miles" }, "metadata": { "type": "object", "nullable": true }, "additionalProperties": { "type": "string", "description": "Additional data represented as key-value pairs. Both the key and value must be strings." } }, "type": "object" }, "CurrencyInfo": { "oneOf": [ { "required": [ "fiatCurrencyCode" ] }, { "required": [ "customCurrencyInfo" ] } ], "properties": { "fiatCurrencyCode": { "type": "string", "description": "The `fiatCurrencyCode` parameter specifies the three-letter ISO code representing the fiat currency type, such as USD for U.S. Dollars. T this code determines the currency used in transactions.", "pattern": "^[A-Z]*$", "example": "USD" }, "customCurrencyInfo": { "$ref": "#/components/schemas/CustomCurrencyInfo" } }, "type": "object" }, "LedgerCreateRequest": { "required": [ "name", "currencyInfo", "decimals" ], "type": "object", "properties": { "name": { "type": "string", "description": "The name assigned to the ledger must be at least 3 characters long and no more than 40 characters. It should consist only of alphanumeric characters (letters and numbers), with no spaces or special characters allowed.", "minLength": 3, "maxLength": 40, "pattern": "^[a-zA-Z0-9]*$" }, "currencyInfo": { "$ref": "#/components/schemas/CurrencyInfo" }, "decimals": { "type": "integer", "description": "The `decimals` parameter defines the number of decimal places used for the transactions in the ledger. It is an integer value ranging from 0 to 255, allowing for precise currency calculations and representations.", "format": "uint8", "minimum": 0, "maximum": 255 }, "description": { "type": "string", "description": "The `description` field is an optional free-form text that provides additional information about the ledger.", "nullable": true }, "seed": { "type": "integer", "description": "The seed value for the ledger. Do not send this field for currency movement ledgers or when there is no fixed amount of tokens to be minted. Seed value 0 is same as not sending seed", "format": "uint64", "nullable": true }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Additional data represented as key-value pairs. Both the key and value must be strings.", "example": { "key": "value", "foo": "bar" }, "properties": {} } } } } }, "x-visibility": "external", "x-readme-id": "65cc5b61e764d4000f2012f3" } ```