> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nomadpay.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Core Concepts

Before you start integrating, it's important to understand these core concepts.

## Authentication & Security

Nomad Pay uses an **asymmetric Ed25519 key pair** model for all API communication to ensure maximum security and non-repudiation.

### API Requests (You -> Nomad Pay)

* **Signing:** You sign the request using your **Secret Key** (Private Key).
* **Verification:** We verify using your **Public Key** (sent in the `x-api-key` header).

### Webhooks (Nomad Pay -> You)

* **Signing:** We sign the webhook payload using the **Secret Key** associated with your account's **latest active API Key**.
* **Identification:** We include the corresponding Public Key in the `x-api-key` header of the webhook request.
* **Verification:** You use the Public Key provided in the header to verify the signature.

### Anti-Replay

* `nonce`**:** Every request must include a unique, strictly increasing integer (typically a **Unix timestamp in milliseconds**) to prevent replay attacks.

### HTTPS

* All communication must be over **HTTPS**. Unencrypted HTTP requests will be rejected.

## Non-Custodial Settlement

Nomad Pay operates on a **non-custodial** model. This affects how funds move and how you should track them.

* **Direct Transfer:** When a customer pays, the funds (minus the platform fee) are routed **directly** from the customer's wallet to your configured `Receiving Address`.
* **No Platform Balance:** We do not hold your funds. You will not see a "Withdraw" button in the dashboard because the money is already in your wallet.
* **Automatic Conversion:** If you configured a `Default Token` (e.g., USDC), incoming payments in other tokens (e.g., ETH) are automatically swapped before reaching your wallet.

## Payment Lifecycle

Understanding the status of a payment is crucial for your order fulfillment logic.

* `Pending`**:**
  * The payment intent has been created. The customer has not yet paid, or the transaction is broadcasting on the blockchain.
* `Success`**:**
  * The transaction has been confirmed on the blockchain and funds have successfully settled to your wallet. **You should ship goods/services only upon receiving this status via Webhook.**
* `Failed`**:**
  * The payment failed (e.g., insufficient funds, transaction reverted, or timeout).
* `Expired`**:**
  * The payment link/session has expired (default 1 hour) without a completed payment.

## Standard Responses

All API responses use a unified JSON structure.

**Success Response (200 OK):**

```
{
  "code": 0,
  "message": "success",
  "data": { ... } // Resource data
}
```

**Error Response (4xx/5xx):**

```
{
  "code": 1001,      // Specific error code
  "message": "Invalid parameter: amount" // Human-readable message
}
```

**Common Error Codes:**

* `1001`: Parameter validation failed
* `1002`: Authentication failed
* `1003`: Invalid signature
* `1004`: Nonce replay rejected
* `2001`: Internal server error

## Pagination

List endpoints (like `GET /v1/transactions`) support pagination via query parameters.

* **Request Parameters:**
  * `page`: The page number (default: 1).
  * `limit`: Number of items per page (default: 20, max: 100).
* **Response Structure:**

  ```
  {
    "code": 0,
    "data": {
      "list": [ ... ],
      "pagination": {
        "total": 150,
        "page": 1,
        "limit": 20
      }
    }
  }
  ```

## Rate Limiting

To ensure platform stability, API requests are rate-limited.

* **Standard Limit:** 100 requests per minute per IP address.
* **Headers:** Response headers `X-RateLimit-Limit` and `X-RateLimit-Remaining` indicate your current usage.
* **429 Too Many Requests:** If you exceed the limit, you will receive this HTTP status. Please implement a retry logic with exponential backoff.