# Home

## EthosFlow Merchant API v2

EthosFlow Merchant API v2 provides a secure HTTPS interface for merchant-side address assignment, payout submission, reconciliation, and webhook-based event delivery.

This documentation is intended for engineering teams integrating EthosFlow into merchant applications and backend systems.

### What This Documentation Covers

* Business API request structure and field constraints
* Request signing and webhook verification
* Payin and payout callback behavior
* Reconciliation workflows
* Recommended integration sequence

### Supported Scope

* Protocol: `HTTPS POST + JSON`
* Endpoint pattern: `https://<your-api-host>/api/{merchant_id}`
* Request envelope: unified RPC-style JSON body
* Current supported request token: `usdt`
* Current documented production chains: `tron_mainnet`, `bsc_mainnet`

### Core Capabilities

#### Address Assignment

Use `new_user` to create or reuse a deposit address for a merchant user.

#### Payout Submission

Use `new_payout` to submit a payout order from the merchant system.

#### Configuration Discovery

Use `get_chain_configs` to retrieve chain metadata, token metadata, and routing-related configuration.

#### Reconciliation

Use:

* `query_payin_notifications`
* `query_payout_notifications`

to retrieve payin and payout records for operational verification and exception handling.

#### Event Notifications

The platform sends webhook callbacks for:

* `new_payin`
* `new_payout`

Merchant systems are expected to verify signatures, process events idempotently, and return the required success acknowledgment.

### Integration Requirements

Before integrating, ensure that your team has the following:

* A platform-issued `merchant_id`
* An assigned API endpoint
* A configured callback URL
* An Ed25519 key pair for request signing
* The platform public key for webhook verification

### High-Level Integration Flow

#### Payin Flow

1. Call `new_user` to assign a deposit address to a merchant user.
2. Present the assigned address to the end user.
3. Receive the `new_payin` webhook after funds are detected.
4. Update internal business state and complete reconciliation when required.

#### Payout Flow

1. Call `new_payout` to create a payout request.
2. Store the merchant business order reference together with the returned platform payout reference.
3. Receive the `new_payout` webhook after processing.
4. Use reconciliation endpoints when operational verification is required.

### Security Model

All business requests and webhook callbacks use the `X-Signature` header with Ed25519 signing.

Key rules:

* The request body must be signed exactly as transmitted
* Signature timestamps must be within the permitted time window
* Merchant systems should enforce idempotency for all webhook handlers
* Public callback endpoints should be protected with HTTPS and additional network controls where appropriate

### Recommended Reading Order

1. Overview
2. Quick Start
3. API Reference
4. Webhooks
5. Models

### Next Step

Proceed to the Quick Start guide for the fastest path to a working integration.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://ethosflow.gitbook.io/ethosflow-docs-1/J5a9oVqkiex3Ca9IpW4z/home.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.