{ "openapi": "3.1.0", "info": { "title": "Alchimex API", "version": "1.0.0", "description": "No-account swaps. Read endpoints are public; creating a batch needs an API key. Amounts are decimal strings. The rate is fixed when a batch is created and held until deposit.expires_at." }, "servers": [ { "url": "https://alchimex.io/api/v1" } ], "components": { "securitySchemes": { "ApiKey": { "type": "http", "scheme": "bearer", "description": "Authorization: Bearer ax_\u2026 (or X-Api-Key: ax_\u2026)" } }, "schemas": { "AssetCode": { "type": "string", "enum": [ "BTC", "ETH", "XMR", "SOL", "TRX", "ZEC", "BNB", "ETH-ARB", "ETH-BASE", "ETH-RHC", "USDT", "USDT-TRX", "USDT-ARB", "USDT-BASE", "USDT-BSC", "USDT-SOL", "USDC", "USDC-ARB", "USDC-BASE", "USDC-BSC", "USDC-SOL", "USDC-TRX" ] }, "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_request", "invalid_api_key", "api_key_required", "rate_limited", "not_found", "amount_below_minimum", "no_route", "rate_unavailable", "batch_token_required", "idempotency_conflict", "in_progress", "upstream_busy", "upstream_unavailable", "upstream_error" ] }, "message": { "type": "string" }, "min_amount_usd": { "type": "number" }, "fields": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } } } } }, "Asset": { "type": "object", "properties": { "asset": { "$ref": "#/components/schemas/AssetCode" }, "symbol": { "type": "string" }, "name": { "type": "string" }, "network": { "type": "string" }, "network_code": { "type": "string" }, "contract": { "type": [ "string", "null" ] }, "decimals": { "type": "integer" }, "address_regex": { "type": "string" }, "explorer_tx_url": { "type": [ "string", "null" ] } } }, "Pair": { "type": "object", "properties": { "from": { "$ref": "#/components/schemas/AssetCode" }, "to": { "$ref": "#/components/schemas/AssetCode" }, "rate": { "type": [ "string", "null" ] }, "min_amount": { "type": [ "string", "null" ] }, "min_amount_usd": { "type": [ "number", "null" ] }, "eta_minutes": { "type": [ "integer", "null" ] } } }, "Rate": { "type": "object", "properties": { "from": { "$ref": "#/components/schemas/AssetCode" }, "to": { "$ref": "#/components/schemas/AssetCode" }, "type": { "type": "string", "enum": [ "indicative", "quote" ] }, "rate": { "type": "string" }, "amount_from": { "type": "string" }, "amount_to": { "type": "string" }, "fee_percent": { "type": "number" }, "min_amount": { "type": [ "string", "null" ] }, "min_amount_usd": { "type": [ "number", "null" ] }, "route": { "type": [ "string", "null" ], "description": "Routing protocol picked for this quote, e.g. \"Mayan\"; may differ at creation" }, "total_fee_percent": { "type": "number", "description": "Router fee + lab fee, all inside amount_to" }, "eta_minutes": { "type": [ "integer", "null" ] }, "quoted_at": { "type": "string", "format": "date-time" }, "valid_for": { "type": "integer" } } }, "Batch": { "type": "object", "properties": { "id": { "type": "string", "example": "AX-7F3Q-21" }, "status": { "type": "string", "enum": [ "awaiting_deposit", "confirming", "exchanging", "sending", "completed", "refunded", "expired", "failed", "action_required", "paused" ] }, "final": { "type": "boolean" }, "deposit_detected": { "type": "boolean" }, "from": { "type": "object", "properties": { "asset": { "$ref": "#/components/schemas/AssetCode" }, "symbol": { "type": "string" }, "network": { "type": "string" }, "amount": { "type": "string" } } }, "to": { "type": "object", "properties": { "asset": { "$ref": "#/components/schemas/AssetCode" }, "symbol": { "type": "string" }, "network": { "type": "string" }, "amount_expected": { "type": "string" }, "amount_received": { "type": "string" } } }, "rate": { "type": "string" }, "fee_percent": { "type": "number" }, "total_fee_percent": { "type": "number" }, "route": { "type": "array", "items": { "type": "string" }, "description": "Routing tool of the quote the batch was created from (toolUsed), e.g. [\"Mayan\"]" }, "deposit": { "type": "object", "properties": { "address": { "type": "string" }, "amount": { "type": "string" }, "payment_uri": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" } } }, "destination_address": { "type": "string", "description": "Masked unless X-Batch-Token is sent" }, "guarantee_letter": { "type": "string", "description": "OpenPGP clear-signed letter of guarantee (deposit address, amount, deadline, addresses). Owner only: creation response or X-Batch-Token. Verify against /pgp.asc" }, "refund_address": { "type": "string", "description": "Masked unless X-Batch-Token is sent" }, "confirmations": { "type": "object", "properties": { "current": { "type": "integer" }, "required": { "type": "integer" } } }, "eta_minutes": { "type": "integer" }, "transactions": { "type": "object", "properties": { "deposit": { "type": "string" }, "delivery": { "type": "string" }, "refund": { "type": "string" } } }, "batch_token": { "type": "string", "description": "Creation response only. Keep it: it authorises owner actions." }, "url": { "type": "string", "format": "uri" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } }, "paths": { "/assets": { "get": { "summary": "Supported assets", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Asset" } } } } } } } } } }, "/pairs": { "get": { "summary": "Every routable pair with its indicative formula", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Pair" } } } } } } } } } }, "/rate": { "get": { "summary": "Indicative formula, or a live quote when amount is given", "parameters": [ { "name": "from", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/AssetCode" } }, { "name": "to", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/AssetCode" } }, { "name": "amount", "in": "query", "required": false, "schema": { "type": "string", "example": "0.01" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Rate" } } } }, "422": { "description": "Invalid pair, amount below minimum or no route", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Upstream busy or unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/batches": { "post": { "summary": "Create a batch (fixed rate)", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "Same key + same body returns the same batch and batch_token" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "from", "to", "amount", "destination_address" ], "properties": { "from": { "$ref": "#/components/schemas/AssetCode" }, "to": { "$ref": "#/components/schemas/AssetCode" }, "amount": { "type": "string", "example": "0.01" }, "destination_address": { "type": "string" }, "refund_address": { "type": "string" } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Batch" } } } }, "200": { "description": "Idempotent replay", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Batch" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency conflict or in progress", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid request or refused by the route", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Upstream busy or unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/batches/{reference}": { "get": { "summary": "Batch status (public with the reference; full addresses with X-Batch-Token)", "parameters": [ { "name": "reference", "in": "path", "required": true, "schema": { "type": "string", "example": "AX-7F3Q-21" } }, { "name": "X-Batch-Token", "in": "header", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Batch" } } } }, "404": { "description": "Unknown reference", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/batches/{reference}/refund-address": { "put": { "summary": "Set or change the refund address", "parameters": [ { "name": "reference", "in": "path", "required": true, "schema": { "type": "string", "example": "AX-7F3Q-21" } }, { "name": "X-Batch-Token", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "address" ], "properties": { "address": { "type": "string" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Batch" } } } }, "403": { "description": "Missing or wrong X-Batch-Token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid address or refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/batches/{reference}/payout-address": { "put": { "summary": "Provide a new payout address when status is action_required", "parameters": [ { "name": "reference", "in": "path", "required": true, "schema": { "type": "string", "example": "AX-7F3Q-21" } }, { "name": "X-Batch-Token", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "address" ], "properties": { "address": { "type": "string" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Batch" } } } }, "403": { "description": "Missing or wrong X-Batch-Token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid address or refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } } }