### One-Click Self-Hosted Installation

Source: https://github.com/dv-net/dv-merchant/blob/main/docs/README.zh.md

Use this command to quickly install the DV.net Merchant Backend on your own infrastructure.

```bash
sudo bash -c "$(curl -fsSL https://dv.net/install.sh)"
```

--------------------------------

### Install Casbin Middleware for Fiber

Source: https://github.com/dv-net/dv-merchant/blob/main/third_party/fiber_casbin/README.md

Install the Fiber framework and the Casbin contrib package. Also, install a Casbin adapter, such as the xorm-adapter, for policy management.

```go
go get -u github.com/gofiber/fiber/v3
go get -u github.com/gofiber/contrib/casbin
```

```go
go get -u github.com/casbin/xorm-adapter
```

--------------------------------

### Setup Development Environment

Source: https://github.com/dv-net/dv-merchant/blob/main/CONTRIBUTING.md

Clone the repository, add the upstream remote, and build the project. Run `go mod download` if dependencies are missing.

```bash
git clone https://github.com/YOUR_USERNAME/dv-merchant.git
cd dv-merchant
git remote add upstream https://github.com/dv-net/dv-merchant.git
make build
make test
```

--------------------------------

### Local Development Docker Setup

Source: https://github.com/dv-net/dv-merchant/blob/main/docs/README.zh.md

Clone the DV.net bundle repository and use Docker Compose to set up a local development environment.

```bash
git clone --recursive https://github.com/dv-net/dv-bundle.git
cd dv-bundle && cp .env.example .env
docker compose up -d
```

--------------------------------

### Create External Wallet via GET

Source: https://context7.com/dv-net/dv-merchant/llms.txt

Initiates the creation of an external wallet for a customer using query parameters. Useful for redirect-based payment flows.

```bash
curl -X GET "http://localhost:80/api/v1/external/wallet?api_key=sk_live_abc123...&store_external_id=order-12345&amount=150.00&currency=usdt_tron"
```

--------------------------------

### Conventional Commits Example

Source: https://github.com/dv-net/dv-merchant/blob/main/CONTRIBUTING.md

An example of a commit message following the Conventional Commits specification, including type, scope, subject, body, and footer.

```bash
feat(exchange): add Binance withdrawal support

Add support for Binance exchange withdrawals with proper
error handling and retry logic.

Closes #123
```

--------------------------------

### API Error Handling Examples

Source: https://context7.com/dv-net/dv-merchant/llms.txt

Examples of consistent API error response structures, including HTTP status codes and the 'errors' array.

```json
# Example: invalid credentials
# HTTP 400
{
  "errors": [
    { "message": "no matches found" }
  ],
  "success": false
}

```

```json
# Example: validation error
# HTTP 422
{
  "errors": [
    { "field": "email", "message": "invalid email format" },
    { "field": "password", "message": "password too short" }
  ],
  "success": false
}

```

```json
# Example: duplicate request_id on withdrawal
# HTTP 422
{
  "errors": [{ "message": "withdrawal with this request_id already exists" }],
  "success": false
}

```

--------------------------------

### DV Merchant Configuration File

Source: https://context7.com/dv-net/dv-merchant/llms.txt

Example YAML configuration file for DV Merchant. All fields can be overridden by environment variables with the MERCHANT_ prefix.

```yaml
# configs/config.yaml
roles_model_path: configs/rbac_model.conf
roles_policies_path: configs/rbac_policies.csv

http:
  host: "0.0.0.0"
  port: "80"
  cors:
    enabled: true
    allowed_origins: ["https://admin.myshop.com"]

postgres:
  addr: "127.0.0.1:5432"
  db_name: "merchant_db"
  user: "merchant"
  password: "secret"
  max_open_conns: 100
  max_idle_conns: 100

redis:
  addr: "127.0.0.1:6379"
  db_index: 0

e_proxy:               # ConnectRPC connection to blockchain explorer proxy
  grpc:
    name: "connectrpc-client"
    addr: "https://explorer-proxy.dv.net"

web_hook:
  max_tries: 30        # Maximum webhook delivery retry attempts

aml:
  check_interval: "2m"
  max_attempts: 5
  bit_ok:
    enabled: true
    base_url: "https://kyt-api.bitok.org/"
  aml_bot:
    enabled: true
    base_url: "https://extrnlapiendpoint.silencatech.com/"

blockchain:
  bitcoin:
    address_type: P2WPKH   # P2PKH | P2SH | P2WPKH | P2TR
  litecoin:
    address_type: P2WPKH
  dogecoin:
    address_type: P2PKH

ops:
  enabled: true
  metrics:
    enabled: true
    path: /metrics
    port: "10000"
  healthy:
    enabled: true
    path: /healthy
    port: "10000"

```

--------------------------------

### Create Wallet (GET)

Source: https://context7.com/dv-net/dv-merchant/llms.txt

Creates a new external wallet using query parameters, useful for redirect-based payment flows.

```APIDOC
## GET /api/v1/external/wallet

### Description
Creates a new external wallet using query parameters, which is useful for redirect-based payment flows.

### Method
GET

### Endpoint
/api/v1/external/wallet

### Parameters
#### Query Parameters
- **api_key** (string) - Required - Your API key.
- **store_external_id** (string) - Required - The external ID of the store.
- **amount** (string) - Required - The payment amount.
- **currency** (string) - Required - The currency to be used (e.g., `usdt_tron`).

### Response
#### Success Response (200)
- **data** (object) - Contains wallet details.
  - **id** (string) - The unique ID of the wallet.
  - **pay_url** (string) - The URL to redirect the user for payment.
  - **address** (array) - List of blockchain addresses for the wallet.
    - **currency_id** (string) - The ID of the currency.
    - **blockchain** (string) - The blockchain network.
    - **address** (string) - The blockchain address.
- **success** (boolean) - Indicates if the operation was successful.
```

--------------------------------

### CLI Commands for DV Merchant

Source: https://context7.com/dv-net/dv-merchant/llms.txt

Provides essential CLI commands for starting the HTTP server, managing database migrations, loading/dropping seed data, and validating configurations.

```bash
# Start the HTTP server
.bin/dv-merchant start --configs configs/config.yaml

# Apply database migrations
.bin/dv-merchant migrate up --configs configs/config.yaml

# Roll back last migration
.bin/dv-merchant migrate down --configs configs/config.yaml

# Load seed data
.bin/dv-merchant seed --mode up --configs configs/config.yaml

# Drop seed data
.bin/dv-merchant seed --mode down

# Validate config and print all recognized env vars
.bin/dv-merchant config validate --configs configs/config.yaml
.bin/dv-merchant config genenvs   # regenerates ENVS.md and config.template.yaml
```

--------------------------------

### Get Hot Wallet Summary

Source: https://context7.com/dv-net/dv-merchant/llms.txt

Returns a currency-grouped summary of all hot wallet balances for the current user.

```APIDOC
## Get Hot Wallet Summary

### Description
Returns a currency-grouped summary of all hot wallet balances for the current user.

### Method
GET

### Endpoint
`/api/v1/dv-admin/wallet/summary`

### Parameters
#### Query Parameters
- **min_balance** (string) - Optional - The minimum balance to include in the summary.

### Request Example
```bash
curl -X GET "http://localhost:80/api/v1/dv-admin/wallet/summary?min_balance=0.01" \
  -H "Authorization: Bearer $TOKEN"
```

### Response
#### Success Response (200)
- **data** (array of objects) - A summary of hot wallet balances grouped by currency.
  - **currency_id** (string) - The ID of the currency.
  - **total_balance** (string) - The total balance for the currency.
  - **total_usd** (string) - The total balance in USD.
  - **wallet_count** (integer) - The number of wallets for the currency.
- **success** (boolean) - Indicates if the operation was successful.
```

--------------------------------

### Get Exchange Balance

Source: https://context7.com/dv-net/dv-merchant/llms.txt

Fetches live spot balances from the connected exchange.

```APIDOC
## GET /api/v1/dv-admin/exchange/{exchange_slug}/balance

### Description
Fetches live spot balances from the connected exchange.

### Method
GET

### Endpoint
http://localhost:80/api/v1/dv-admin/exchange/{exchange_slug}/balance

### Parameters
#### Path Parameters
- **exchange_slug** (string) - Required - The slug of the exchange to get the balance from.

### Response
#### Success Response (200)
- **data** (object) - Contains balance information.
  - **balances** (array) - A list of currency balances.
    - **currency** (string) - The currency symbol.
    - **free** (string) - The available balance.
    - **locked** (string) - The locked balance.
  - **total_usd** (string) - The total balance in USD.
- **success** (boolean) - True if the operation was successful, false otherwise.

### Response Example
```json
{
  "data": {
    "balances": [ { "currency": "USDT", "free": "5000.00", "locked": "0.00" } ],
    "total_usd": "5000.00"
  },
  "success": true
}
```
```

--------------------------------

### Role Authorization with Casbin

Source: https://github.com/dv-net/dv-merchant/blob/main/third_party/fiber_casbin/README.md

Implement role-based access control for routes using Casbin. This example shows how to restrict access to specific roles, such as 'admin'.

```go
package main

import (
  "github.com/gofiber/fiber/v3"
  "github.com/gofiber/contrib/casbin"
  _ "github.com/go-sql-driver/mysql"
  "github.com/casbin/xorm-adapter/v2"
)

func main() {
  app := fiber.New()

  authz := casbin.New(casbin.Config{
      ModelFilePath: "path/to/rbac_model.conf",
      PolicyAdapter: xormadapter.NewAdapter("mysql", "root:@tcp(127.0.0.1:3306)/"),
      Lookup: func(c fiber.Ctx) string {
          // fetch authenticated user subject
      },
  })
  
  app.Put("/blog/:id",
    func(c fiber.Ctx) error {
      // your handler
    },
    authz.RequiresRoles([]string{"admin"}),
  )

  app.Listen(":8080")
}
```

--------------------------------

### Key Environment Variables for DV Merchant

Source: https://context7.com/dv-net/dv-merchant/llms.txt

Example environment variables to configure DV Merchant. These variables correspond to the settings in the YAML configuration file.

```bash
# Key environment variables
export MERCHANT_POSTGRES_ADDR="127.0.0.1:5432"
export MERCHANT_POSTGRES_DB_NAME="merchant_db"
export MERCHANT_POSTGRES_USER="merchant"
export MERCHANT_POSTGRES_PASSWORD="secret"
export MERCHANT_REDIS_ADDR="127.0.0.1:6379"
export MERCHANT_E_PROXY_GRPC_ADDR="https://explorer-proxy.dv.net"
export MERCHANT_HTTP_PORT="80"
export MERCHANT_LOG_LEVEL="info"        # debug | info | warn | error
export MERCHANT_LOG_FORMAT="json"       # json | console
export MERCHANT_KEY_VALUE_ENGINE="redis" # redis | in_memory
export MERCHANT_TURNSTILE_ENABLED="false"
export MERCHANT_OPS_METRICS_ENABLED="true"

```

--------------------------------

### Get Exchange Balance

Source: https://context7.com/dv-net/dv-merchant/llms.txt

Fetches live spot balances from a connected exchange. The response includes balances per currency and the total value in USD.

```bash
curl -X GET "http://localhost:80/api/v1/dv-admin/exchange/binance/balance" \
  -H "Authorization: Bearer $TOKEN"
```

--------------------------------

### Get Processing Wallets

Source: https://context7.com/dv-net/dv-merchant/llms.txt

Returns all processing (cold) wallet balances, grouped by blockchain. Requires Authorization header.

```bash
curl -X GET "http://localhost:80/api/v1/dv-admin/processing/wallets?blockchains=tron,ethereum" \
  -H "Authorization: Bearer $TOKEN"
```

```json
# Response:
# {
#   "data": [
#     { "address": "TXxx...", "blockchain": "tron", "assets": [...], "balance_usd": "1234.56" },
#     ...
#   ],
#   "success": true
# }
```

--------------------------------

### Get Hot Wallet Summary

Source: https://context7.com/dv-net/dv-merchant/llms.txt

Returns a currency-grouped summary of all hot wallet balances for the current user. Can filter by a minimum balance. Requires an Authorization Bearer token.

```bash
curl -X GET "http://localhost:80/api/v1/dv-admin/wallet/summary?min_balance=0.01" \
  -H "Authorization: Bearer $TOKEN"
```

--------------------------------

### Custom Permission Check with Casbin

Source: https://github.com/dv-net/dv-merchant/blob/main/third_party/fiber_casbin/README.md

Implement custom permission checks for routes using Casbin. This example demonstrates requiring specific permissions and using different validation rules like MatchAllRule.

```go
package main

import (
  "github.com/gofiber/fiber/v3"
  "github.com/gofiber/contrib/casbin"
  _ "github.com/go-sql-driver/mysql"
  "github.com/casbin/xorm-adapter/v2"
)

func main() {
  app := fiber.New()

  authz := casbin.New(casbin.Config{
      ModelFilePath: "path/to/rbac_model.conf",
      PolicyAdapter: xormadapter.NewAdapter("mysql", "root:@tcp(127.0.0.1:3306)/"),
      Lookup: func(c fiber.Ctx) string {
          // fetch authenticated user subject
      },
  })

  app.Post("/blog",
      func(c fiber.Ctx) error {
        // your handler
      },
      authz.RequiresPermissions([]string{"blog:create"}, casbin.WithValidationRule(casbin.MatchAllRule)),
  )
  
  app.Delete("/blog/:id",
    func(c fiber.Ctx) error {
      // your handler
    },
    authz.RequiresPermissions([]string{"blog:create", "blog:delete"}, casbin.WithValidationRule(casbin.AtLeastOneRule)),
  )

  app.Listen(":8080")
}
```

--------------------------------

### Get Top-Up Form Data

Source: https://context7.com/dv-net/dv-merchant/llms.txt

Retrieves all necessary data to render a payment form for a wallet, including currencies, addresses, and rates. This endpoint does not require authentication.

```APIDOC
## GET /api/v1/public/wallet/<user-uuid>/top-up-form

### Description
Returns all data needed to render the payment form (currencies, addresses, rates) for a wallet without requiring authentication.

### Method
GET

### Endpoint
/api/v1/public/wallet/<user-uuid>/top-up-form

### Parameters
#### Path Parameters
- **user-uuid** (string) - Required - The unique identifier for the user's wallet.

### Request Example
```bash
curl -X GET "http://localhost:80/api/v1/public/wallet/TXxxxx.../top-up-form"
```

### Response
#### Success Response (200)
- **currencies** (array) - List of available currencies with real-time rates.
- **addresses** (object) - Deposit addresses for each currency.
- **rates** (object) - Real-time exchange rates.
```

--------------------------------

### Get External Hot Wallet Balances

Source: https://context7.com/dv-net/dv-merchant/llms.txt

Retrieves the summary of hot wallet balances for the store owner. Requires an API key and optionally a minimum balance for filtering.

```bash
curl -X GET "http://localhost:80/api/v1/external/wallet/balance/hot?api_key=sk_live_abc123...&min_balance=1.00"
```

--------------------------------

### Get Top-Up Form Data API

Source: https://context7.com/dv-net/dv-merchant/llms.txt

Public API endpoint to retrieve all data needed for rendering a payment form, including currencies, addresses, and rates, without authentication.

```bash
curl -X GET "http://localhost:80/api/v1/public/wallet/TXxxxx.../top-up-form"

# Response includes available currencies with real-time rates and deposit addresses

```

--------------------------------

### Get Wallet Private Keys (Hot Wallet)

Source: https://context7.com/dv-net/dv-merchant/llms.txt

Downloads private keys for hot wallet addresses. Requires 2FA (TOTP) verification. Returns a downloadable file.

```APIDOC
## Get Wallet Private Keys (Hot Wallet)

### Description
Downloads private keys for hot wallet addresses. Requires 2FA (TOTP) verification. Returns a downloadable file.

### Method
POST

### Endpoint
`/api/v1/dv-admin/wallet/keys/hot`

### Parameters
#### Request Body
- **totp** (string) - Required - The Time-based One-Time Password for 2FA verification.
- **file_type** (string) - Required - The desired file type for the download (e.g., "csv").
- **wallet_address_ids** (array of strings) - Required - A list of wallet address IDs for which to download private keys.

### Request Example
```bash
curl -X POST http://localhost:80/api/v1/dv-admin/wallet/keys/hot \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ 
    "totp": "123456",
    "file_type": "csv",
    "wallet_address_ids": ["addr-uuid-1", "addr-uuid-2"]
  }' \
  --output hot_wallet_keys.csv
```
```

--------------------------------

### Get Wallet Private Keys (Hot Wallet)

Source: https://context7.com/dv-net/dv-merchant/llms.txt

Downloads private keys for hot wallet addresses. Requires 2FA (TOTP) verification and specifies the file type and wallet address IDs. Returns a downloadable file.

```bash
curl -X POST http://localhost:80/api/v1/dv-admin/wallet/keys/hot \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "totp": "123456",
    "file_type": "csv",
    "wallet_address_ids": ["addr-uuid-1", "addr-uuid-2"]
  }' \
  --output hot_wallet_keys.csv
```

--------------------------------

### Running the Server

Source: https://github.com/dv-net/dv-merchant/blob/main/CONTRIBUTING.md

Build and run the application server, or run it directly using go run.

```bash
# Build and run
make run start
```

```bash
# Or run directly
go run ./cmd/app start
```

--------------------------------

### Manual Backend Build

Source: https://github.com/dv-net/dv-merchant/blob/main/docs/README.zh.md

Steps to manually clone, update frontend, and build the DV.net Merchant Backend from source.

```bash
git clone https://github.com/dv-net/dv-merchant.git
cd dv-merchant

make update-frontend
make build
```

--------------------------------

### Get Withdrawal Status (External)

Source: https://context7.com/dv-net/dv-merchant/llms.txt

Retrieves the status of a withdrawal using its ID or `request_id`.

```APIDOC
## GET /api/v1/external/withdrawal-from-processing/{id}

### Description
Retrieves the status of a withdrawal. You can query by either the withdrawal's unique ID or its `request_id`.

### Method
GET

### Endpoint
/api/v1/external/withdrawal-from-processing/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID or `request_id` of the withdrawal.

#### Query Parameters
- **api_key** (string) - Required - Your API key.

### Response
#### Success Response (200)
- The response will contain the details of the withdrawal, including its current status.
```

--------------------------------

### Get Processing Wallets

Source: https://context7.com/dv-net/dv-merchant/llms.txt

Retrieves all processing (cold) wallet balances, grouped by blockchain.

```APIDOC
## GET /api/v1/dv-admin/processing/wallets

### Description
Returns all processing (cold) wallet balances grouped by blockchain.

### Method
GET

### Endpoint
/api/v1/dv-admin/processing/wallets

### Parameters
#### Path Parameters
- **Authorization** (string) - Required - Bearer token for authentication.

#### Query Parameters
- **blockchains** (string) - Optional - A comma-separated list of blockchains to filter by (e.g., "tron,ethereum").

### Response
#### Success Response (200)
- **data** (array) - A list of wallet objects.
  - **address** (string) - The wallet address.
  - **blockchain** (string) - The blockchain network.
  - **assets** (array) - List of assets in the wallet.
  - **balance_usd** (string) - The total balance in USD.
- **success** (boolean) - Indicates if the operation was successful.
```

--------------------------------

### Run Linter

Source: https://github.com/dv-net/dv-merchant/blob/main/CONTRIBUTING.md

Build custom plugins if this is the first time running the linter, then execute the lint command.

```bash
make build_plugins
make lint
```

--------------------------------

### Get Transaction by Hash

Source: https://context7.com/dv-net/dv-merchant/llms.txt

Retrieves detailed information about a specific transaction using its blockchain hash.

```APIDOC
## GET /api/v1/dv-admin/transaction/{hash}

### Description
Looks up detailed information about a specific transaction using its blockchain hash.

### Method
GET

### Endpoint
/api/v1/dv-admin/transaction/{hash}

### Parameters
#### Path Parameters
- **hash** (string) - Required - The blockchain transaction hash.

#### Query Parameters
- **api_key** (string) - Required - Your API key.

### Response
#### Success Response (200)
- The response includes full transaction details, associated wallet information, USD equivalent, and webhook history.
```

--------------------------------

### Get Webhook Delivery History

Source: https://context7.com/dv-net/dv-merchant/llms.txt

Returns paginated history of all webhook attempts with response codes and retry status.

```APIDOC
## GET /api/v1/dv-admin/webhook/history

### Description
Returns paginated history of all webhook attempts with response codes and retry status.

### Method
GET

### Endpoint
/api/v1/dv-admin/webhook/history

### Query Parameters
- **page** (integer) - Optional - The page number for pagination. Defaults to 1.
- **page_size** (integer) - Optional - The number of items per page. Defaults to 20.

### Response
#### Success Response (200)
- Includes webhook payload snapshots, response status codes, and retry counts.
```

--------------------------------

### Code Formatting and Static Analysis

Source: https://github.com/dv-net/dv-merchant/blob/main/docs/README.zh.md

Run these commands to ensure code style consistency and perform static analysis before committing.

```bash
# 静态分析与格式化
make lint
go fmt ./...
```

--------------------------------

### Create External Wallet via POST

Source: https://context7.com/dv-net/dv-merchant/llms.txt

Initiates the creation of an external wallet for a customer. Requires a JSON body with order details. Use this for direct payment flows.

```bash
curl -X POST "http://localhost:80/api/v1/external/wallet?api_key=sk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "store_external_id": "order-12345",
    "email": "customer@example.com",
    "amount": "150.00",
    "currency": "usdt_tron",
    "locale": "en",
    "ip": "1.2.3.4"
  }'
```

--------------------------------

### Get Withdrawal Status by UUID

Source: https://context7.com/dv-net/dv-merchant/llms.txt

Retrieves the status of a withdrawal using its unique UUID. This is an alternative to using the `request_id`.

```bash
curl -X GET "http://localhost:80/api/v1/external/withdrawal-from-processing/withdrawal-uuid-...?api_key=sk_live_abc123..."
```

--------------------------------

### Running Tests

Source: https://github.com/dv-net/dv-merchant/blob/main/CONTRIBUTING.md

Execute all tests, specific packages, or tests with coverage and verbose output.

```bash
make test
go test ./internal/service/package
go test -cover ./...
go test -v ./...
```

--------------------------------

### Get Wallet Seed Phrase

Source: https://context7.com/dv-net/dv-merchant/llms.txt

Returns the BIP39 mnemonic seed phrase for the processing owner. Requires 2FA.

```APIDOC
## Get Wallet Seed Phrase

### Description
Returns the BIP39 mnemonic seed phrase for the processing owner. Requires 2FA.

### Method
GET

### Endpoint
`/api/v1/dv-admin/wallet/addresses/seeds`

### Parameters
#### Query Parameters
- **totp** (string) - Required - The Time-based One-Time Password for 2FA verification.

### Request Example
```bash
curl -X GET "http://localhost:80/api/v1/dv-admin/wallet/addresses/seeds?totp=123456" \
  -H "Authorization: Bearer $TOKEN"
```

### Response
#### Success Response (200)
- **data** (object) - Contains the seed phrase details.
  - **mnemonic** (string) - The BIP39 mnemonic seed phrase.
  - **owner_id** (string) - The ID of the owner.
- **success** (boolean) - Indicates if the operation was successful.
```

--------------------------------

### Create Wallet with Addresses

Source: https://context7.com/dv-net/dv-merchant/llms.txt

Creates or retrieves a hot wallet for a customer in a specific store, pre-generating deposit addresses for all store-enabled currencies. Requires an Authorization Bearer token and specifies customer details, amount, currency, and locale.

```bash
curl -X POST http://localhost:80/api/v1/dv-admin/wallet/addresses \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "store_id": "550e8400-e29b-41d4-a716-446655440000",
    "store_external_id": "customer-order-789",
    "email": "customer@example.com",
    "amount": "99.99",
    "currency": "usdt_tron",
    "locale": "en"
  }'
```

--------------------------------

### Get AML Check History

Source: https://context7.com/dv-net/dv-merchant/llms.txt

Retrieves paginated history of past AML checks with optional date and provider filtering.

```APIDOC
## GET /api/v1/dv-admin/aml/history

### Description
Retrieves paginated history of past AML checks with optional date and provider filtering.

### Method
GET

### Endpoint
/api/v1/dv-admin/aml/history

### Query Parameters
- **provider_slug** (string) - Optional - Filter by AML provider slug.
- **date_from** (string) - Optional - Filter by date from (YYYY-MM-DD).
- **page** (integer) - Optional - The page number for pagination. Defaults to 1.
- **page_size** (integer) - Optional - The number of items per page. Defaults to 20.

### Response
#### Success Response (200)
- **data** (object)
  - **items** (array) - List of AML check records.
    - **id** (string) - Unique identifier of the check.
    - **tx_id** (string) - Transaction ID.
    - **risk_score** (integer) - The calculated risk score.
    - **risk_level** (string) - The risk level (e.g., "low").
    - **provider** (string) - The AML provider used.
    - **checked_at** (string) - Timestamp of when the check was performed.
  - **pagination** (object)
    - **total** (integer) - Total number of items.
    - **page** (integer) - Current page number.
    - **page_size** (integer) - Items per page.
- **success** (boolean) - True if the operation was successful.

### Response Example
{
  "data": {
    "items": [
      { "id": "...", "tx_id": "...", "risk_score": 12, "risk_level": "low", "provider": "bitok", "checked_at": "..." }
    ],
    "pagination": { "total": 150, "page": 1, "page_size": 20 }
  },
  "success": true
}
```

--------------------------------

### Get Unconfirmed Transfer Transactions (External)

Source: https://context7.com/dv-net/dv-merchant/llms.txt

Returns a list of in-flight transfer transactions that are currently awaiting blockchain confirmation.

```APIDOC
## GET /api/v1/external/transactions/unconfirmed/transfer

### Description
Retrieves a list of in-flight transfer transactions that are awaiting confirmation on the blockchain.

### Method
GET

### Endpoint
/api/v1/external/transactions/unconfirmed/transfer

### Parameters
#### Query Parameters
- **api_key** (string) - Required - Your API key.

### Response
#### Success Response (200)
- **data** (object)
  - **transactions** (array) - List of unconfirmed transactions.
    - **hash** (string) - The transaction hash.
    - **amount** (string) - The transaction amount.
    - **status** (string) - The current status (e.g., `pending`).
- **success** (boolean) - Indicates if the operation was successful.
```

--------------------------------

### Database Migration Commands

Source: https://github.com/dv-net/dv-merchant/blob/main/CONTRIBUTING.md

Use these make commands to manage database migrations. Never edit generated files directly.

```bash
# Create new migration
make db-create-migration migration_name
```

```bash
# Apply migrations
make migrate up
```

```bash
# Rollback migrations
make migrate down
```

--------------------------------

### Create Store

Source: https://context7.com/dv-net/dv-merchant/llms.txt

Creates a new merchant store, which includes its own API keys, webhooks, and currency configuration. Requires Authorization header, Content-Type, and JSON payload.

```bash
curl -X POST http://localhost:80/api/v1/dv-admin/store/ \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Online Shop",
    "site": "https://myshop.com"
  }'
```

```json
# Response:
# {
#   "data": {
#     "id": "550e8400-e29b-41d4-a716-446655440000",
#     "name": "My Online Shop",
#     "site": "https://myshop.com",
#     "external_id": "...",
#     "minimal_payment": "10.00"
#   },
#   "success": true
# }
```

--------------------------------

### Release Tagging Process

Source: https://github.com/dv-net/dv-merchant/blob/main/CONTRIBUTING.md

Steps for tagging releases, including development in the 'dev' branch, testing, and creating release candidate and stable tags.

```text
1. Development in `dev` branch
2. Testing and stabilization
3. Tag release candidate: vX.X.X-RC1
4. Merge to `main`
5. Tag stable release: vX.X.X
```

--------------------------------

### Get Unconfirmed Transfer Transactions

Source: https://context7.com/dv-net/dv-merchant/llms.txt

Retrieves a list of transfer transactions that are currently in flight and awaiting confirmation on the blockchain. Useful for monitoring.

```bash
curl -X GET "http://localhost:80/api/v1/external/transactions/unconfirmed/transfer?api_key=sk_live_abc123..."
```

--------------------------------

### Get Withdrawal Status by Request ID

Source: https://context7.com/dv-net/dv-merchant/llms.txt

Retrieves the status of a withdrawal using its unique `request_id`. This is an alternative to using the withdrawal UUID.

```bash
curl -X GET "http://localhost:80/api/v1/external/withdrawal-from-processing/unique-idempotency-key-001?api_key=sk_live_abc123..."
```

--------------------------------

### Create Wallet (POST)

Source: https://context7.com/dv-net/dv-merchant/llms.txt

Creates a new external wallet for a given store, accepting payment details via JSON body or query parameters.

```APIDOC
## POST /api/v1/external/wallet

### Description
Creates a new external wallet for a given store. Payment details can be provided either in the JSON request body or as query parameters.

### Method
POST

### Endpoint
/api/v1/external/wallet

### Parameters
#### Query Parameters
- **api_key** (string) - Required - Your API key.

#### Request Body
- **store_external_id** (string) - Required - The external ID of the store.
- **email** (string) - Required - The customer's email address.
- **amount** (string) - Required - The payment amount.
- **currency** (string) - Required - The currency to be used (e.g., `usdt_tron`).
- **locale** (string) - Optional - The locale for the payment page (e.g., `en`).
- **ip** (string) - Optional - The IP address of the customer.

### Request Example
```json
{
  "store_external_id": "order-12345",
  "email": "customer@example.com",
  "amount": "150.00",
  "currency": "usdt_tron",
  "locale": "en",
  "ip": "1.2.3.4"
}
```

### Response
#### Success Response (200)
- **data** (object) - Contains wallet details.
  - **id** (string) - The unique ID of the wallet.
  - **pay_url** (string) - The URL to redirect the user for payment.
  - **address** (array) - List of blockchain addresses for the wallet.
    - **currency_id** (string) - The ID of the currency.
    - **blockchain** (string) - The blockchain network.
    - **address** (string) - The blockchain address.
- **success** (boolean) - Indicates if the operation was successful.
```

--------------------------------

### Development Workflow

Source: https://github.com/dv-net/dv-merchant/blob/main/CONTRIBUTING.md

Update the main branch, create a feature branch, and make changes. Ensure code is formatted, linted, and tested before committing.

```bash
git checkout main
git pull upstream main
git checkout -b feature/your-feature-name
make fmt
make lint
make test
```

--------------------------------

### Linting and Formatting Go Code

Source: https://github.com/dv-net/dv-merchant/blob/main/README.md

Run static analysis and formatting tools to maintain code consistency.

```bash
# Static analysis & formatting
make lint
go fmt ./...
```

--------------------------------

### Initialize Processing Connection

Source: https://context7.com/dv-net/dv-merchant/llms.txt

Registers the backend with the blockchain processing node. This must be called once after root user creation to link the backend to the processing service. Requires Authorization header, Content-Type, and JSON payload.

```bash
curl -X POST http://localhost:80/api/v1/dv-admin/processing/init \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "host": "https://processing.dv.net",
    "merchant_domain": "https://admin.myshop.com",
    "merchant_pay_form_domain": "https://pay.myshop.com",
    "callback_domain": "https://api.myshop.com"
  }'
```

```json
# Response:
# {
#   "data": {
#     "base_url": "https://processing.dv.net",
#     "processing_client_id": "uuid-.",
#     "processing_client_key": "secret-key-"
#   },
#   "success": true
# }
```

--------------------------------

### Get Public Currency Rates

Source: https://context7.com/dv-net/dv-merchant/llms.txt

Retrieves the current exchange rates for all enabled currencies. This is used by the payment form to display USD equivalents and is publicly accessible.

```APIDOC
## GET /api/v1/public/currency/rates

### Description
Returns current exchange rates for all enabled currencies. Used by the payment form to display USD equivalents.

### Method
GET

### Endpoint
/api/v1/public/currency/rates

### Response
#### Success Response (200)
- **rates** (object) - An object containing currency codes as keys and their current exchange rates as values.
```

--------------------------------

### Get External Hot Wallet Balances

Source: https://context7.com/dv-net/dv-merchant/llms.txt

Retrieves the total hot wallet balance summary for the store's owner, accessible via the store API key.

```APIDOC
## GET /api/v1/external/wallet/balance/hot

### Description
Returns the total hot wallet balance summary for the store's owner. This endpoint is accessible using the store API key.

### Method
GET

### Endpoint
/api/v1/external/wallet/balance/hot

### Parameters
#### Query Parameters
- **api_key** (string) - Required - Your API key.
- **min_balance** (string) - Optional - Minimum balance to filter by.

### Response
#### Success Response (200)
- The response format is the same as the admin `/wallet/summary` endpoint.
```

--------------------------------

### Connect Exchange (Set API Keys)

Source: https://context7.com/dv-net/dv-merchant/llms.txt

Connects a CEX account by storing API credentials. Provide the exchange slug, API key, secret, and passphrase.

```bash
curl -X POST "http://localhost:80/api/v1/dv-admin/exchange/binance/keys" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "your-binance-api-key",
    "secret": "your-binance-api-secret",
    "passphrase": ""
  }'
```

--------------------------------

### Register New User

Source: https://context7.com/dv-net/dv-merchant/llms.txt

Registers a regular user. This requires that user registration is enabled in the root settings. Requires Content-Type and JSON payload.

```bash
curl -X POST http://localhost:80/api/v1/dv-admin/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "merchant@example.com",
    "password": "Pass123!",
    "language": "en",
    "timezone": "America/New_York"
  }'
```

--------------------------------

### Create Store

Source: https://context7.com/dv-net/dv-merchant/llms.txt

Creates a new merchant store. Each store is configured with its own API keys, webhooks, and currency settings.

```APIDOC
## POST /api/v1/dv-admin/store/

### Description
Creates a new merchant store. Each store has its own API keys, webhooks, and currency configuration.

### Method
POST

### Endpoint
/api/v1/dv-admin/store/

### Parameters
#### Path Parameters
- **Authorization** (string) - Required - Bearer token for authentication.

#### Request Body
- **name** (string) - Required - The name of the store.
- **site** (string) - Required - The website URL of the store.

### Request Example
```json
{
  "name": "My Online Shop",
  "site": "https://myshop.com"
}
```

### Response
#### Success Response (200)
- **data** (object) - Contains details of the created store.
  - **id** (string) - The unique identifier of the store.
  - **name** (string) - The name of the store.
  - **site** (string) - The website URL of the store.
  - **external_id** (string) - The external identifier for the store.
  - **minimal_payment** (string) - The minimum payment amount configured for the store.
- **success** (boolean) - Indicates if the operation was successful.
```

--------------------------------

### Register Root User

Source: https://context7.com/dv-net/dv-merchant/llms.txt

Creates the first admin user. This operation only succeeds when no users exist in the system. Requires Content-Type and JSON payload.

```bash
curl -X POST http://localhost:80/api/v1/dv-admin/auth/register-root \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@example.com",
    "password": "StrongPass123!",
    "language": "en"
  }'
```

```json
{
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  },
  "success": true
}
```

--------------------------------

### Get Wallet Seed Phrase

Source: https://context7.com/dv-net/dv-merchant/llms.txt

Returns the BIP39 mnemonic seed phrase for the processing owner. Requires 2FA (TOTP) verification. Requires an Authorization Bearer token.

```bash
curl -X GET "http://localhost:80/api/v1/dv-admin/wallet/addresses/seeds?totp=123456" \
  -H "Authorization: Bearer $TOKEN"
```

--------------------------------

### Send Test Webhook

Source: https://context7.com/dv-net/dv-merchant/llms.txt

Emulates a webhook event to a configured store webhook URL for integration testing. Requires the webhook ID and the event type to be specified.

```bash
curl -X POST http://localhost:80/api/v1/dv-admin/webhook/send-test \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "wh_id": "webhook-uuid-…",
    "event_type": "deposit"
  }'

# Response:
# {
#   "data": { "status_code": 200, "response_body": "ok", "sent_at": "..." },
#   "success": true
# }
```

--------------------------------

### Initialize Processing Connection

Source: https://context7.com/dv-net/dv-merchant/llms.txt

Registers the backend with the blockchain processing node. This must be called once after root user creation to link the backend to the processing service.

```APIDOC
## POST /api/v1/dv-admin/processing/init

### Description
Registers the backend with the blockchain processing node. Must be called once after root user creation to link the backend to the processing service.

### Method
POST

### Endpoint
/api/v1/dv-admin/processing/init

### Parameters
#### Path Parameters
- **Authorization** (string) - Required - Bearer token for authentication.

#### Request Body
- **host** (string) - Required - The base URL of the processing node.
- **merchant_domain** (string) - Required - The domain of the merchant admin interface.
- **merchant_pay_form_domain** (string) - Required - The domain of the merchant payment form.
- **callback_domain** (string) - Required - The domain for receiving callbacks.

### Request Example
```json
{
  "host": "https://processing.dv.net",
  "merchant_domain": "https://admin.myshop.com",
  "merchant_pay_form_domain": "https://pay.myshop.com",
  "callback_domain": "https://api.myshop.com"
}
```

### Response
#### Success Response (200)
- **data** (object) - Contains processing connection details.
  - **base_url** (string) - The base URL of the processing node.
  - **processing_client_id** (string) - The client ID for the processing node.
  - **processing_client_key** (string) - The client key for the processing node.
- **success** (boolean) - Indicates if the operation was successful.
```

--------------------------------

### Get Public Currency Rates API

Source: https://context7.com/dv-net/dv-merchant/llms.txt

Public API endpoint that returns current exchange rates for all enabled currencies. This is used by the payment form to display USD equivalents.

```bash
curl -X GET "http://localhost:80/api/v1/public/currency/rates"

```

--------------------------------

### Register Owner in Processing

Source: https://context7.com/dv-net/dv-merchant/llms.txt

Links the root user's HD wallet (via BIP39 mnemonic) to the processing node, enabling wallet address generation. Requires Authorization header, Content-Type, and JSON payload.

```bash
curl -X POST http://localhost:80/api/v1/dv-admin/processing/register-owner \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "mnemonic": "word1 word2 word3 word4 word5 word6 word7 word8 word9 word10 word11 word12"
  }'
```

```json
# Response:
# {
#   "data": { "owner_id": "uuid-." },
#   "success": true
# }
```

--------------------------------

### Get Webhook Delivery History

Source: https://context7.com/dv-net/dv-merchant/llms.txt

Retrieves paginated history of all webhook delivery attempts. The response includes webhook payload snapshots, response status codes, and retry counts.

```bash
curl -X GET "http://localhost:80/api/v1/dv-admin/webhook/history?page=1&page_size=20" \
  -H "Authorization: Bearer $TOKEN"

# Response includes webhook payload snapshots, response status codes, and retry status
```

--------------------------------

### Configure Store Webhook

Source: https://context7.com/dv-net/dv-merchant/llms.txt

Registers a webhook URL to receive deposit and withdrawal notifications from the store. Specify the URL, events to listen for, and activation status. Requires an Authorization Bearer token.

```bash
STORE_ID="550e8400-e29b-41d4-a716-446655440000"

curl -X POST "http://localhost:80/api/v1/dv-admin/store/${STORE_ID}/webhooks" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://myshop.com/webhooks/crypto",
    "events": ["deposit", "withdrawal", "transfer"],
    "is_active": true
  }'
```

--------------------------------

### Get AML Check History

Source: https://context7.com/dv-net/dv-merchant/llms.txt

Retrieves paginated history of AML checks. Supports filtering by provider slug and date range. The response includes items and pagination details.

```bash
curl -X GET "http://localhost:80/api/v1/dv-admin/aml/history?provider_slug=bitok&date_from=2025-01-01&page=1&page_size=20" \
  -H "Authorization: Bearer $TOKEN"

# Response:
# {
#   "data": {
#     "items": [
#       { "id": "...", "tx_id": "...", "risk_score": 12, "risk_level": "low", "provider": "bitok", "checked_at": "..." }
#     ],
#     "pagination": { "total": 150, "page": 1, "page_size": 20 }
#   },
#   "success": true
# }
```

--------------------------------

### Get Transaction Details by Hash

Source: https://context7.com/dv-net/dv-merchant/llms.txt

Looks up detailed information for a specific transaction using its blockchain hash. Requires an Authorization token. Response includes wallet details and webhook history.

```bash
curl -X GET "http://localhost:80/api/v1/dv-admin/transaction/0xabc123def456..." \
  -H "Authorization: Bearer $TOKEN"
```

--------------------------------

### Running Unit Tests

Source: https://github.com/dv-net/dv-merchant/blob/main/README.md

Execute unit tests to ensure critical flows are covered. Add or update tests when shipping new features or fixes.

```bash
# Unit tests
make test
```