tronzap-sdk 1.0.0

data/README.ru.md

@@ -0,0 +1,392 @@
+# Покупка энергии Tron через API
+## Ruby SDK от TronZap.com
+
+[English](README.md) | [Español](README.es.md) | [Português](README.pt-br.md) | **[Русский](README.ru.md)**
+
+[![Gem Version](https://img.shields.io/gem/v/tronzap-sdk.svg)](https://rubygems.org/gems/tronzap-sdk)
+[![CI](https://github.com/tron-energy-market/tronzap-sdk-ruby/actions/workflows/ci.yml/badge.svg)](https://github.com/tron-energy-market/tronzap-sdk-ruby/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+Официальный Ruby SDK для API TronZap.
+Этот SDK позволяет легко интегрировать сервисы TronZap для аренды энергии TRON.
+
+TronZap.com позволяет [покупать энергию TRON](https://tronzap.com/), существенно снижая комиссии при переводах USDT (TRC20).
+
+👉 [Зарегистрируйтесь для получения API ключа](https://tronzap.com), чтобы начать использовать TronZap API и интегрировать его через SDK.
+
+- Сайт: https://tronzap.com/
+- Справочник API: https://docs.tronzap.com/
+- RubyGems: https://rubygems.org/gems/tronzap-sdk
+- Исходный код: https://github.com/tron-energy-market/tronzap-sdk-ruby
+
+## Установка
+
+Добавьте gem в Gemfile:
+
+```ruby
+gem "tronzap-sdk"
+```
+
+или установите его напрямую:
+
+```bash
+gem install tronzap-sdk
+```
+
+## Требования
+
+- Ruby 3.3 или новее
+- Одна runtime-зависимость, `bigdecimal`. SDK не зависит от Rails.
+
+## Быстрый старт
+
+```ruby
+require "tronzap"
+
+client = Tronzap::Client.new(
+  api_token: "ваш_api_token",
+  api_secret: "ваш_api_secret"
+)
+
+begin
+  balance = client.get_balance
+  puts "balance: #{balance.balance.to_s("F")} (deposit to #{balance.address})"
+
+  # Оцениваем, сколько энергии нужно для перевода USDT, и покупаем ровно столько.
+  estimate = client.estimate_energy(from_address: "TSenderAddress", to_address: "TRecipientAddress")
+
+  transaction = client.create_energy_transaction(
+    address: "TRecipientAddress",
+    energy: estimate.energy,
+    duration: 1,
+    external_id: "order-42",
+    activate_address: true
+  )
+  puts "transaction #{transaction.id} costs #{transaction.amount.to_s("F")} and is #{transaction.status}"
+rescue Tronzap::Error => e
+  warn "TronZap call failed: #{e.message}"
+end
+```
+
+`require "tronzap"` загружает SDK. С Bundler его также загружает строка `gem "tronzap-sdk"` в Gemfile.
+
+Запускаемый пример со всеми операциями находится в
+[`examples/basic_usage.rb`](examples/basic_usage.rb):
+
+```bash
+export TRONZAP_API_TOKEN=ваш_api_token
+export TRONZAP_API_SECRET=ваш_api_secret
+export TRONZAP_BASE_URL=api.tronzap.com   # необязательно
+ruby -Ilib examples/basic_usage.rb
+```
+
+По умолчанию пример только читает данные и ничего не тратит. С
+`TRONZAP_ALLOW_PURCHASES=1` он также вызывает endpoints, которые создают транзакции
+и AML-проверки и списывают средства с баланса. Остальные необязательные переменные
+описаны в комментарии в начале файла.
+
+## Настройка
+
+Клиент принимает два ключа из личного кабинета: API-токен передаётся как bearer
+token, а API-секрет подписывает тело каждого запроса и никогда не передаётся.
+Всё остальное необязательно. Настройки можно передать именованными аргументами,
+в блоке или обоими способами; блок выполняется последним:
+
+```ruby
+client = Tronzap::Client.new(
+  api_token: api_token,
+  api_secret: api_secret,
+  base_url: "api.tronzap.com",   # по умолчанию Tronzap::Configuration::DEFAULT_BASE_URL
+  timeout: 10,                   # секунды; по умолчанию 30
+  user_agent: "my-app/1.0"
+)
+
+client = Tronzap::Client.new do |config|
+  config.api_token = ENV.fetch("TRONZAP_API_TOKEN")
+  config.api_secret = ENV.fetch("TRONZAP_API_SECRET")
+  config.timeout = 10
+end
+```
+
+`base_url` принимает домен или полный URL: если схема не указана, используется
+`https`, а завершающий слэш удаляется, поэтому `"api.tronzap.com"`,
+`"api.tronzap.com/"` и `"https://api.tronzap.com"` равнозначны. Чтобы этого
+избежать, укажите схему явно, например `"http://localhost:8080"` для локального
+мока.
+
+`timeout` действует на установку соединения и на каждое чтение и запись, а не на
+запрос целиком.
+
+SDK не хранит глобального состояния. Каждый клиент проверяет свои настройки при
+создании и замораживает их, поэтому клиент неизменяем и безопасен для
+использования из нескольких потоков. Создайте один клиент на набор ключей.
+`inspect` никогда не показывает ключи.
+
+### Свой HTTP-адаптер
+
+Адаптер по умолчанию использует `Net::HTTP` из стандартной библиотеки, открывает
+новое соединение для каждого запроса, всегда проверяет TLS-сертификаты и учитывает
+переменную окружения `https_proxy`. Чтобы доверять частному центру сертификации,
+передайте его PEM-файл:
+
+```ruby
+adapter = Tronzap::HttpAdapter::NetHttp.new(ca_file: "/etc/ssl/corporate-ca.pem")
+client = Tronzap::Client.new(api_token: api_token, api_secret: api_secret, adapter: adapter)
+```
+
+Его можно заменить любым объектом с методом `call`. Он получает
+`Tronzap::HttpAdapter::Request` (`http_method`, `url`, `headers`, `body`,
+`timeout`) и возвращает `Tronzap::HttpAdapter::Response` (`status`, `headers`,
+`body`). Отправляйте тело без изменений: оно подписывается побайтно.
+
+```ruby
+class FaradayAdapter
+  def initialize(connection)
+    @connection = connection
+  end
+
+  def call(request)
+    response = @connection.post(request.url, request.body, request.headers) do |req|
+      req.options.timeout = request.timeout
+    end
+    Tronzap::HttpAdapter::Response.new(status: response.status, headers: response.headers.to_h,
+                                       body: response.body.to_s)
+  rescue Faraday::TimeoutError => e
+    raise Tronzap::TimeoutError, e.message
+  rescue Faraday::SSLError => e
+    raise Tronzap::SslError, e.message
+  rescue Faraday::ConnectionFailed => e
+    raise Tronzap::ConnectionError, e.message
+  end
+end
+```
+
+Стандартные сетевые ошибки Ruby, которые выбрасывает адаптер (`Timeout::Error`,
+`OpenSSL::SSL::SSLError`, `SocketError`, `SystemCallError`, `IOError`),
+автоматически сообщаются как подклассы `Tronzap::NetworkError`. Ошибки других
+HTTP-библиотек адаптер должен преобразовать сам, как в примере выше.
+
+## Доступные методы
+
+| Метод | Endpoint | Описание |
+|---|---|---|
+| `get_services` | `/v1/services` | Доступные сервисы и цены |
+| `get_balance` | `/v1/balance` | Текущий баланс аккаунта |
+| `get_address_info(address)` | `/v1/address-info` | Ресурсы (энергия, bandwidth) и балансы (TRX, USDT) адреса |
+| `estimate_energy(from_address:, to_address:, contract_address: nil)` | `/v1/estimate-energy` | Сколько энергии нужно для перевода и сколько она стоит |
+| `calculate(address:, energy:, duration: 1)` | `/v1/calculate` | Стоимость покупки без создания транзакции |
+| `create_energy_transaction(address:, energy:, duration: 1, external_id: nil, activate_address: false)` | `/v1/transaction/new` | Купить энергию |
+| `create_bandwidth_transaction(address:, bandwidth:, external_id: nil)` | `/v1/transaction/new` | Купить bandwidth |
+| `create_resource_bundle_transaction(address:, energy:, bandwidth:, duration: 1, external_id: nil, activate_address: false)` | `/v1/transaction/new` | Купить энергию и bandwidth одной транзакцией |
+| `create_address_activation_transaction(address:, external_id: nil)` | `/v1/transaction/new` | Активировать адрес TRON |
+| `check_transaction(id: nil, external_id: nil)` | `/v1/transaction/check` | Статус транзакции по id или внешнему id |
+| `get_direct_recharge_info` | `/v1/direct-recharge-info` | Адрес и тарифы прямого пополнения |
+| `get_aml_services` | `/v1/aml-checks` | AML-сервисы и цены |
+| `create_aml_check(type:, network:, address:, transaction_hash: nil, direction: nil)` | `/v1/aml-checks/new` | Запустить AML-проверку |
+| `check_aml_status(id)` | `/v1/aml-checks/check` | Статус и результат AML-проверки |
+| `get_aml_history(page: 1, per_page: 10, status: nil)` | `/v1/aml-checks/history` | История AML-проверок с пагинацией |
+
+Методы с параметрами принимают либо именованные аргументы, либо объект запроса из
+`Tronzap::Requests`, поэтому запрос можно создать, проверить и передать дальше до
+отправки:
+
+```ruby
+request = Tronzap::Requests::EnergyTransaction.new(address: "TRecipientAddress", energy: 65000)
+client.create_energy_transaction(request)
+```
+
+Запрос проверяется при создании, поэтому невалидный запрос вызывает
+`ArgumentError` и никогда не доходит до API. Количества должны быть
+положительными `Integer`. Значения по умолчанию совпадают с API: `duration` —
+1 час, история AML начинается со страницы 1 по 10 элементов.
+
+Результаты — неизменяемые объекты `Data` в `Tronzap::Responses` и
+`Tronzap::Models`, а не хеши: `transaction.status`, `estimate.energy`. Коллекции
+заморожены и никогда не бывают `nil`, а значения, которые API может не прислать,
+равны `nil`.
+
+### Покупка ресурсов
+
+```ruby
+# Энергия, при необходимости с активацией адреса в том же вызове.
+client.create_energy_transaction(
+  address: "TRecipientAddress",
+  energy: 65000,
+  duration: 1,            # часы; доступные сроки смотрите в get_services
+  external_id: "order-42",
+  activate_address: true
+)
+
+# Bandwidth.
+client.create_bandwidth_transaction(address: "TRecipientAddress", bandwidth: 345, external_id: "bandwidth-1")
+
+# Энергия и bandwidth вместе одной транзакцией.
+client.create_resource_bundle_transaction(
+  address: "TRecipientAddress",
+  energy: 65000,
+  bandwidth: 345,
+  external_id: "bundle-1"
+)
+
+# Только активация.
+client.create_address_activation_transaction(address: "TRecipientAddress", external_id: "activation-1")
+```
+
+Цена энергии указана за единицу, цена bandwidth — за 1000 единиц: в
+`get_services` `EnergyRate#price` × 65000 — это стоимость 65000 энергии, а 345
+bandwidth при `BandwidthRate#price`, равном 1, стоят 0.345.
+
+Сейчас API возвращает пакет ресурсов с `service`, равным `:energy`, а не
+`:resource_bundle`. Состав покупки смотрите в `params.amounts`.
+
+### Отслеживание транзакции
+
+Транзакция проходит путь `:new` → `:pending` → `:success` или `:failed`:
+
+```ruby
+transaction = nil
+loop do
+  sleep 2
+  transaction = client.check_transaction(external_id: "order-42")
+  break unless %i[new pending].include?(transaction.status)
+end
+
+puts "finished as #{transaction.status}, hash #{transaction.transaction_hash || "none"}"
+```
+
+### AML-проверка
+
+```ruby
+check = client.create_aml_check(Tronzap::Requests::AmlCheck.for_address("TRX", "TAddressToScreen"))
+# или Tronzap::Requests::AmlCheck.for_hash("BTC", "bc1RecipientAddress", "TX_HASH", direction: :withdrawal)
+
+result = client.check_aml_status(check.id)
+if result.status == :completed
+  puts "#{result.risk_level} #{result.risk_score.to_s("F")} #{result.risk_factors.size} factor(s)"
+end
+```
+
+`risk_score` равен `nil`, пока проверка не завершится. У завершённой проверки score
+может быть равен 0, и это не то же самое, что отсутствие результата.
+
+## Обработка ошибок
+
+Любой сбой вызова API — исключение `Tronzap::Error`. Перехватывайте подкласс, чтобы
+обработать конкретный вид сбоя:
+
+```
+Tronzap::Error
+├── Tronzap::ApiError              — API ответил ненулевым code
+├── Tronzap::HttpError             — ответ не 2xx без payload API
+│   ├── Tronzap::RateLimitError    — HTTP 429
+│   ├── Tronzap::UnauthorizedError — HTTP 401 или 403
+│   └── Tronzap::ServerError       — HTTP 5xx
+├── Tronzap::InvalidResponseError  — ответ 2xx, который SDK не смог прочитать
+└── Tronzap::NetworkError          — ответ не пришёл
+    ├── Tronzap::ConnectionError   — ошибка DNS, соединение отклонено
+    ├── Tronzap::TimeoutError      — запрос превысил timeout
+    └── Tronzap::SslError          — сбой TLS-рукопожатия или сертификата
+```
+
+`ApiError`, `HttpError` и `InvalidResponseError` содержат HTTP-статус
+(`status`) и сырое тело ответа (`response_body`). `ApiError` также содержит код
+ошибки API (`code`), ключ ошибки (`error_key`) и ID запроса (`request_id`).
+`RateLimitError#retry_after` хранит задержку из `Retry-After` в секундах, если API
+её прислал.
+
+Невалидные аргументы не являются сбоями API: они вызывают `ArgumentError` ещё до
+отправки.
+
+```ruby
+begin
+  client.create_energy_transaction(address: "TRecipientAddress", energy: 65000)
+rescue Tronzap::ApiError => e
+  # Ошибка уровня приложения: код точно говорит, что пошло не так.
+  case e.code
+  when Tronzap::ErrorCode::INVALID_TRON_ADDRESS
+    # Ключ может уточнить, например "invalid_tron_address.from_address"
+    warn "bad address: #{e.error_key}"
+  when Tronzap::ErrorCode::INSUFFICIENT_FUNDS
+    warn "top up the account"
+  when Tronzap::ErrorCode::ADDRESS_NOT_ACTIVATED
+    warn "activate the address first"
+  else
+    warn "api error #{e.code}: #{e.message} (request #{e.request_id || "-"})"
+  end
+rescue Tronzap::RateLimitError => e
+  # Подождите и повторите, через e.retry_after секунд, если API его прислал.
+rescue Tronzap::UnauthorizedError
+  # Неверный токен или подпись.
+rescue Tronzap::TimeoutError, Tronzap::ServerError
+  # Временный сбой; можно повторить.
+rescue Tronzap::NetworkError
+  # Сервер недоступен.
+end
+```
+
+`request_id` — идентификатор, который API присваивает каждому запросу. Указывайте
+его при обращении в поддержку.
+
+Ошибка API важнее HTTP-статуса: часть сбоев API возвращает со статусом 2xx, а
+часть — с 4xx или 5xx, поэтому читаемый payload с ненулевым кодом всегда
+сообщается как `Tronzap::ApiError`, а не как `Tronzap::HttpError`.
+
+### Коды ошибок API
+
+| Код | Константа | Описание |
+|------|----------|-------------|
+| 1 | `AUTH_ERROR` | Ошибка аутентификации: неверный API-токен или подпись |
+| 2 | `INVALID_SERVICE_OR_PARAMS` | Неверный сервис или параметры |
+| 5 | `WALLET_NOT_FOUND` | Внутренний кошелёк не найден. Обратитесь в поддержку. |
+| 6 | `INSUFFICIENT_FUNDS` | Недостаточно средств |
+| 10 | `INVALID_TRON_ADDRESS` | Неверный адрес TRON |
+| 11 | `INVALID_ENERGY_AMOUNT` | Неверное количество энергии |
+| 12 | `INVALID_DURATION` | Неверная длительность |
+| 20 | `TRANSACTION_NOT_FOUND` | Транзакция/подписка не найдена |
+| 21 | `CANNOT_STOP_SUBSCRIPTION` | Невозможно остановить подписку |
+| 24 | `ADDRESS_NOT_ACTIVATED` | Адрес не активирован |
+| 25 | `ADDRESS_ALREADY_ACTIVATED` | Адрес уже активирован |
+| 30 | `AML_CHECK_NOT_FOUND` | AML-проверка не найдена |
+| 35 | `SERVICE_NOT_AVAILABLE` | Сервис недоступен |
+| 50 | `INVALID_BANDWIDTH_AMOUNT` | Неверное количество bandwidth |
+| 500 | `INTERNAL_SERVER_ERROR` | Внутренняя ошибка сервера: обратитесь в поддержку |
+
+Константы находятся в `Tronzap::ErrorCode`. Код, который эта версия SDK не знает,
+по-прежнему доступен как число через `ApiError#code`.
+
+## Числовые поля и даты
+
+Суммы и цены — `BigDecimal`, поэтому сохраняют ровно то значение, которое прислал
+API. В одних ответах API кодирует деньги JSON-числом, в других — JSON-строкой; обе
+формы читаются одинаково. Чтобы вывести значение без экспоненциальной записи,
+используйте `to_s("F")`.
+
+Даты — объекты `Tronzap::Models::Timestamp`: `value` — разобранный `Time`, `raw` —
+текст ровно в том виде, в каком его прислал API. Поддерживаются все форматы,
+которые использует API, а время без смещения читается как UTC. Нераспознанная дата
+оставляет `value` равным `nil` и не ломает весь ответ.
+
+Поля-перечисления — символы, например `:energy` или `:completed`. Значение,
+которое API может добавить в будущем, например новый статус транзакции,
+сообщается как `:unknown` и не приводит к ошибке. Известные значения перечислены
+в `Tronzap::Models`.
+
+## Тестирование
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+Тесты запускаются против локального HTTP-сервера: точное тело запроса и
+подпись для каждого endpoint, ошибки API и HTTP, некорректный JSON, таймауты,
+сетевые и TLS-сбои, а также конкурентное использование.
+
+## Лицензия
+
+Лицензия MIT (MIT). Подробнее в [файле лицензии](LICENSE).
+
+## Поддержка
+
+По вопросам поддержки пишите на [support@tronzap.com](mailto:support@tronzap.com).

data/lib/tronzap/client.rb

@@ -0,0 +1,239 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+
+module Tronzap
+  # Client for the {https://docs.tronzap.com/ TronZap API}: buy TRON energy and bandwidth, activate addresses and
+  # run AML checks.
+  #
+  # A client is immutable and safe to share between threads. Create one per set of credentials.
+  #
+  # Methods that take parameters accept either a request object from {Requests} or the same values as keyword
+  # arguments. Invalid values raise +ArgumentError+ before anything is sent. Every failure of the call itself raises
+  # a {Tronzap::Error}: {ApiError} when the API rejected the request, {HttpError} for a non-2xx response without an
+  # API error code, {InvalidResponseError} for a response the SDK cannot read, and {NetworkError} when no response
+  # arrived.
+  #
+  # @example
+  #   client = Tronzap::Client.new(api_token: ENV.fetch("TRONZAP_API_TOKEN"),
+  #                                api_secret: ENV.fetch("TRONZAP_API_SECRET"))
+  #   transaction = client.create_energy_transaction(address: "TRecipientAddress", energy: 65000)
+  #   transaction.status # => :new
+  class Client
+    # @return [Configuration] the frozen configuration
+    attr_reader :config
+
+    # @param options [Hash] the settings of {Configuration#initialize}
+    # @yieldparam config [Configuration] the configuration to change before the client is created
+    # @raise [ArgumentError] when a setting is invalid
+    def initialize(**)
+      config = Configuration.new(**)
+      yield config if block_given?
+      @config = config.finalize!
+      freeze
+    end
+
+    # Available services and their prices.
+    #
+    # @return [Responses::ServiceRates]
+    # @raise [Error]
+    def get_services
+      post("/v1/services", {}) { Responses::ServiceRates.from_api(_1) }
+    end
+
+    # The current account balance.
+    #
+    # @return [Responses::AccountBalance]
+    # @raise [Error]
+    def get_balance
+      post("/v1/balance", {}) { Responses::AccountBalance.from_api(_1) }
+    end
+
+    # The resources (energy, bandwidth) and token balances (TRX, USDT) of a TRON address.
+    #
+    # @param address [String] the TRON address
+    # @return [Responses::AddressInfo]
+    # @raise [ArgumentError, Error]
+    def get_address_info(address)
+      body = { "address" => Requests::Validation.string(address, "address") }
+      post("/v1/address-info", body) { Responses::AddressInfo.from_api(_1) }
+    end
+
+    # The energy a token transfer needs, and its cost.
+    #
+    # @overload estimate_energy(request)
+    #   @param request [Requests::EstimateEnergy]
+    # @overload estimate_energy(from_address:, to_address:, contract_address: nil)
+    # @return [Responses::EnergyEstimate]
+    # @raise [ArgumentError, Error]
+    def estimate_energy(request = nil, **params)
+      body = build(Requests::EstimateEnergy, request, params).body
+      post("/v1/estimate-energy", body) { Responses::EnergyEstimate.from_api(_1) }
+    end
+
+    # Prices an energy purchase without creating a transaction.
+    #
+    # @overload calculate(request)
+    #   @param request [Requests::Calculate]
+    # @overload calculate(address:, energy:, duration: 1)
+    # @return [Responses::Calculation]
+    # @raise [ArgumentError, Error]
+    def calculate(request = nil, **params)
+      body = build(Requests::Calculate, request, params).body
+      post("/v1/calculate", body) { Responses::Calculation.from_api(_1) }
+    end
+
+    # Buys energy.
+    #
+    # @overload create_energy_transaction(request)
+    #   @param request [Requests::EnergyTransaction]
+    # @overload create_energy_transaction(address:, energy:, duration: 1, external_id: nil, activate_address: false)
+    # @return [Responses::Transaction]
+    # @raise [ArgumentError, Error]
+    def create_energy_transaction(request = nil, **params)
+      create_transaction(build(Requests::EnergyTransaction, request, params))
+    end
+
+    # Buys bandwidth.
+    #
+    # @overload create_bandwidth_transaction(request)
+    #   @param request [Requests::BandwidthTransaction]
+    # @overload create_bandwidth_transaction(address:, bandwidth:, external_id: nil)
+    # @return [Responses::Transaction]
+    # @raise [ArgumentError, Error]
+    def create_bandwidth_transaction(request = nil, **params)
+      create_transaction(build(Requests::BandwidthTransaction, request, params))
+    end
+
+    # Buys energy and bandwidth in one transaction.
+    #
+    # @overload create_resource_bundle_transaction(request)
+    #   @param request [Requests::ResourceBundleTransaction]
+    # @overload create_resource_bundle_transaction(address:, energy:, bandwidth:, duration: 1, external_id: nil,
+    #                                              activate_address: false)
+    # @return [Responses::Transaction]
+    # @raise [ArgumentError, Error]
+    def create_resource_bundle_transaction(request = nil, **params)
+      create_transaction(build(Requests::ResourceBundleTransaction, request, params))
+    end
+
+    # Activates a TRON address.
+    #
+    # @overload create_address_activation_transaction(request)
+    #   @param request [Requests::AddressActivation]
+    # @overload create_address_activation_transaction(address:, external_id: nil)
+    # @return [Responses::Transaction]
+    # @raise [ArgumentError, Error]
+    def create_address_activation_transaction(request = nil, **params)
+      create_transaction(build(Requests::AddressActivation, request, params))
+    end
+
+    # The status of a transaction, by its TronZap ID or by your external ID.
+    #
+    # @overload check_transaction(request)
+    #   @param request [Requests::CheckTransaction]
+    # @overload check_transaction(id: nil, external_id: nil)
+    # @return [Responses::Transaction]
+    # @raise [ArgumentError, Error]
+    def check_transaction(request = nil, **params)
+      body = build(Requests::CheckTransaction, request, params).body
+      post("/v1/transaction/check", body) { Responses::Transaction.from_api(_1) }
+    end
+
+    # The address to pay for a direct energy recharge and the rates energy is delivered at.
+    #
+    # @return [Responses::DirectRechargeInfo]
+    # @raise [Error]
+    def get_direct_recharge_info
+      post("/v1/direct-recharge-info", {}) { Responses::DirectRechargeInfo.from_api(_1) }
+    end
+
+    # AML services and their prices.
+    #
+    # @return [Array<Responses::AmlService>]
+    # @raise [Error]
+    def get_aml_services
+      post("/v1/aml-checks", {}) { Responses::AmlService.list_from_api(_1) }
+    end
+
+    # Starts an AML screening of an address or a transaction.
+    #
+    # @overload create_aml_check(request)
+    #   @param request [Requests::AmlCheck] see {Requests::AmlCheck.for_address} and {Requests::AmlCheck.for_hash}
+    # @overload create_aml_check(type:, network:, address:, transaction_hash: nil, direction: nil)
+    # @return [Responses::AmlCheck]
+    # @raise [ArgumentError, Error]
+    def create_aml_check(request = nil, **params)
+      body = build(Requests::AmlCheck, request, params).body
+      post("/v1/aml-checks/new", body) { Responses::AmlCheck.from_api(_1) }
+    end
+
+    # The status and result of an AML check.
+    #
+    # @param id [String] the AML check ID
+    # @return [Responses::AmlCheck]
+    # @raise [ArgumentError, Error]
+    def check_aml_status(id)
+      body = { "id" => Requests::Validation.string(id, "id") }
+      post("/v1/aml-checks/check", body) { Responses::AmlCheck.from_api(_1) }
+    end
+
+    # One page of past AML checks.
+    #
+    # @overload get_aml_history(request)
+    #   @param request [Requests::AmlHistory]
+    # @overload get_aml_history(page: 1, per_page: 10, status: nil)
+    # @return [Responses::AmlHistory]
+    # @raise [ArgumentError, Error]
+    def get_aml_history(request = nil, **params)
+      body = build(Requests::AmlHistory, request, params).body
+      post("/v1/aml-checks/history", body) { Responses::AmlHistory.from_api(_1) }
+    end
+
+    # @return [String] a description that leaves out the credentials
+    def inspect
+      "#<#{self.class.name} base_url=#{config.base_url.inspect}>"
+    end
+
+    private
+
+    def build(type, request, params)
+      raise ArgumentError, "pass either a #{type.name} or keyword arguments, not both" if request && !params.empty?
+
+      case request
+      when nil then type.new(**params)
+      when type then request
+      when Hash then type.new(**request.transform_keys(&:to_sym))
+      else raise ArgumentError, "expected a #{type.name}, got #{request.class}"
+      end
+    end
+
+    def create_transaction(request)
+      post("/v1/transaction/new", request.body) { Responses::Transaction.from_api(_1) }
+    end
+
+    def post(path, payload, &)
+      body = JSON.generate(payload)
+      request = HttpAdapter::Request.new(
+        http_method: :post,
+        url: "#{config.base_url}#{path}",
+        headers: headers(body),
+        body: body,
+        timeout: config.timeout
+      )
+      response = HttpAdapter.translate_errors { config.adapter.call(request) }
+      ResponseDecoder.decode(response, &)
+    end
+
+    def headers(body)
+      {
+        "Authorization" => "Bearer #{config.api_token}",
+        "X-Signature" => Digest::SHA256.hexdigest(body.b + config.api_secret.b),
+        "Content-Type" => "application/json",
+        "Accept" => "application/json",
+        "User-Agent" => config.user_agent
+      }.freeze
+    end
+  end
+end