{ "openapi": "3.0.3", "info": { "title": "Heth.me transaction integration API — documented subset", "version": "2026-10-20", "description": "API reference for transaction flows and token configuration available to a Heth account. Requests that create payments can move real funds; review and authorize the exact terms before submitting. An HTTP success response does not prove settlement. Account permissions and payment-route availability apply to every operation." }, "servers": [ { "url": "https://app.heth.me", "description": "Heth gateway supplies organization context for this host." } ], "security": [ { "ApiKey": [] } ], "tags": [ { "name": "Transactions" }, { "name": "Configuration" } ], "paths": { "/api/v1/transactions": { "get": { "operationId": "listTransactions", "tags": [ "Transactions" ], "summary": "Read own transactions using timestamp cursor pagination", "parameters": [ { "name": "env", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "prod" ], "default": "prod" }, "description": "" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 }, "description": "" }, { "name": "order_by", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "started", "updated" ] }, "description": "" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Pass cursor.cursor_value, not the cursor object." }, { "name": "txid", "in": "query", "required": false, "schema": { "type": "string" }, "description": "" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "" }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "payment", "payout" ] }, "description": "" }, { "name": "started_from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "" }, { "name": "started_to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "" }, { "name": "updated_from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "" }, { "name": "updated_to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "" } ], "responses": { "200": { "description": "Response; inspect status, not only HTTP success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionList" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Authentication required" }, "403": { "description": "Forbidden" }, "404": { "description": "Not found or inaccessible" }, "409": { "description": "Conflict" }, "422": { "description": "Validation failed" }, "429": { "description": "Rate limited" }, "500": { "description": "Unexpected server error; recover the original operation before retrying" } } }, "post": { "operationId": "createTransaction", "tags": [ "Transactions" ], "summary": "Create a payment or payout on an enabled route", "description": "Can initiate a monetary operation. This is not a preview endpoint. Persist txid before sending and recover the original operation on timeout. Review and authorize the operation before sending.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTransaction" } } } }, "responses": { "200": { "description": "Response; inspect status, not only HTTP success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transaction" } } } }, "201": { "description": "Response; inspect status, not only HTTP success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transaction" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Authentication required" }, "403": { "description": "Forbidden" }, "404": { "description": "Not found or inaccessible" }, "409": { "description": "Conflict" }, "422": { "description": "Validation failed" }, "429": { "description": "Rate limited" }, "500": { "description": "Unexpected server error; recover the original operation before retrying" } } } }, "/api/v1/transactions/{id}": { "get": { "operationId": "getTransaction", "tags": [ "Transactions" ], "summary": "Read own transaction by internal id or external txid", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Internal UUID by default. With by=txid, the client operation string." }, { "name": "by", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "txid" ] }, "description": "" }, { "name": "env", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "prod" ], "default": "prod" }, "description": "" } ], "responses": { "200": { "description": "Response; inspect status, not only HTTP success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transaction" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Authentication required" }, "403": { "description": "Forbidden" }, "404": { "description": "Not found or inaccessible" }, "409": { "description": "Conflict" }, "422": { "description": "Validation failed" }, "429": { "description": "Rate limited" }, "500": { "description": "Unexpected server error; recover the original operation before retrying" } } } }, "/api/v1/contracts": { "get": { "operationId": "getTokenConfiguration", "tags": [ "Configuration" ], "security": [], "summary": "Public token configuration; not proof of account payment capability", "parameters": [ { "name": "env", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "prod" ], "default": "prod" }, "description": "" } ], "responses": { "200": { "description": "Configuration for the requested environment. Filter further by account availability.", "content": { "application/json": { "schema": { "type": "object", "required": [ "tokens" ], "properties": { "version": { "type": "string" }, "tokens": { "type": "array", "items": { "type": "object", "required": [ "symbol", "network", "decimals" ], "properties": { "symbol": { "type": "string" }, "network": { "type": "string" }, "decimals": { "type": "integer", "minimum": 0 }, "contract_address": { "type": "string", "nullable": true }, "visible": { "type": "boolean" } } } } } } } } }, "400": { "description": "Invalid environment" } } } } }, "components": { "securitySchemes": { "ApiKey": { "type": "apiKey", "in": "header", "name": "x-api-key" } }, "schemas": { "Transaction": { "type": "object", "required": [ "id", "status" ], "additionalProperties": true, "properties": { "id": { "type": "string", "format": "uuid" }, "txid": { "type": "string", "description": "Client operation string. UUID is not required." }, "status": { "type": "string", "description": "charged means success; unknown statuses are not proof of success." }, "amount": { "type": "string", "pattern": "^[0-9]+$", "description": "Exact integer string in minor units. Resolve decimals by currency, network and environment.", "example": "1000000" }, "amount_with_fee": { "type": "string", "pattern": "^[0-9]+$", "description": "Exact integer string in minor units. Resolve decimals by currency, network and environment.", "example": "1000000", "nullable": true }, "currency": { "type": "string" }, "env": { "type": "string", "enum": [ "prod" ], "default": "prod" }, "route": { "type": "string", "nullable": true }, "type": { "type": "string", "enum": [ "payment", "payout" ] }, "started": { "type": "string", "format": "date-time", "nullable": true }, "finished": { "type": "string", "format": "date-time", "nullable": true }, "error_description": { "type": "string", "nullable": true, "description": "Human-readable, not a stable machine code." } } }, "Cursor": { "type": "object", "additionalProperties": true, "properties": { "cursor_field": { "type": "string" }, "cursor_value": { "type": "string", "format": "date-time", "nullable": true } } }, "TransactionList": { "type": "object", "required": [ "data", "cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Transaction" } }, "cursor": { "$ref": "#/components/schemas/Cursor" } } }, "CreateTransaction": { "type": "object", "required": [ "params" ], "properties": { "params": { "type": "object", "description": "Subset for direct payment/payout examples. Instruments and required details depend on the enabled route. Specialized operations may have different requirements.", "required": [ "type", "amount", "currency", "money_storage" ], "additionalProperties": true, "properties": { "type": { "type": "string", "enum": [ "payment", "payout" ] }, "amount": { "type": "string", "pattern": "^[0-9]+$", "description": "Exact integer string in minor units. Resolve decimals by currency, network and environment.", "example": "1000000" }, "currency": { "type": "string" }, "env": { "type": "string", "enum": [ "prod" ], "default": "prod" }, "txid": { "type": "string", "description": "Persist a unique value before sending. Reuse it only for the same business instruction, account and environment.", "example": "example-order-001" }, "route": { "type": "string", "description": "Must be enabled for the account; not a tool for changing routing." }, "description": { "type": "string" }, "money_storage": { "type": "object", "additionalProperties": true, "description": "Instrument or recipient fields matching the documented flow. Credentials are secret." }, "money_storage_merchant": { "type": "object", "additionalProperties": true } } } } } } } }