> For the complete documentation index, see [llms.txt](https://docs.ledig.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ledig.io/endpoints/endpoints-guide.md).

# Endpoints Guide

## Permissions & Scopes

To protect your Ledig account, API keys are issued with **specific scopes**.\
Scopes define which features your integration can access. If a key lacks the required scope, requests are rejected with a `403 forbidden` error.

**Available Scopes**

* `view_rates` → Read access to currency rates.
* `instant` → Access to instant liquidity contracts and conversions.
* `crypto_wallets` → Manage crypto wallets, balances, and payouts.
* `fiat_wallet` → Manage fiat balances, payouts, funding accounts, and virtual accounts.

**Examples**

* An API key with only `view_rates` can fetch rates but cannot execute conversions.
* An API key with `crypto_wallets` can create wallets, check balances, and request payouts.
* An API key with `fiat_wallet` can check NGN balances, request fiat payouts, and fetch virtual accounts.

***

## Endpoints

### Health & Rates

#### `GET /v1/health`

**Scope:** None\
**Description:** Returns the current status of the Ledig API. Useful for monitoring uptime.\
**Sample Response**

```json
{ "ok": true, "env": "sandbox" }
```

***

#### `GET /v1/rates`

**Scope:** `view_rates`\
**Description:** Fetch available currency pair rates. Use this to display exchange rates in your app before executing conversions.\
**Sample Response**

```json
{
  "results": [
    {
      "Base Currency": "USDT",
      "Quote Currency": "NGN",
      "Bid": 1604,
      "Ask": 1612,
      "Last Updated ": "2025-06-15T17:35:09.158Z"
    }
  ]
}
```

***

### Instant Liquidity

#### `GET /v1/instant_contracts`

**Scope:** `instant`\
**Description:** Lists all available instant liquidity contracts. These contracts allow you to convert between stablecoins and fiat instantly.\
**Sample Response**

```json
{
  "results": [
    {
      "contract_id": "1755972749562x729243549438643600",
      "From": "USDT",
      "to": "NGN",
      "rate": 1500,
      "fee": 0.1,
      "amount available": 50000,
      "Direction": "USDT to NGN"
    }
  ]
}
```

***

#### `POST /v1/instant_conversion`

**Scope:** `instant`\
**Description:** Executes an instant liquidity contract, converting from one asset to another at the quoted rate.\
**Sample Request**

```json
{ "contract_id": "1755972749562x729243549438643600", "from_amount": 1000 }
```

**Sample Response**

```json
{
  "status": "success",
  "response": {
    "transaction_status": "success",
    "id": "CytZlJixkSerWz7v",
    "from": "1000 USDT",
    "to": "1500000 NGN",
    "fee": "1500 NGN"
  }
}
```

***

#### `POST /v1/instant_transaction`

**Scope:** `instant`\
**Description:** Fetches the full details of a previously executed instant liquidity transaction.\
**Sample Request**

```json
{ "id": "CytZlJixkSerWz7v" }
```

**Sample Response**

```json
{
  "status": "success",
  "response": {
    "id": "CytZlJixkSerWz7v",
    "from": "1000 USDT",
    "to": "1500000 NGN",
    "fee": "1500 NGN",
    "status": "completed"
  }
}
```

***

### Crypto Wallets

#### `POST /v1/create_wallet`

**Scope:** `crypto_wallets`\
**Description:** Creates a new crypto wallet on Ledig for your business (e.g., USDT wallet).\
**Sample Request**

```json
{ "network": "ethereum", "wallet_name": "MainWallet" }
```

**Sample Response**

```json
{ "status": "success", "wallet_id": "WALLET123456", "network": "ethereum", "wallet_name": "MainWallet" }
```

***

#### `POST /v1/crypto_wallets`

**Scope:** `crypto_wallets`\
**Description:** Lists all crypto wallets you have created under your account.\
**Sample Request**

```json
{ "network": "ethereum" }
```

**Sample Response**

```json
{
  "status": "success",
  "response": [
    { "alias": "Vault1", "address": "0x123...", "coin": "USDT" }
  ]
}
```

***

#### `POST /v1/wallet_details`

**Scope:** `crypto_wallets`\
**Description:** Returns details of a single crypto wallet by alias (address, supported assets, etc).\
**Sample Request**

```json
{ "alias": "xtre" }
```

**Sample Response**

```json
{
  "status": "success",
  "response": {
    "Alias": "xtre",
    "Address": "0x8aD5fE2c89F70eA0C621B6Ad6Ff3B8920dE37",
    "Network": "Ethereum Erc20",
    "Assets Supported": ["USDT","USDC"]
  }
}
```

***

#### `POST /v1/coin_balance`

**Scope:** `crypto_wallets`\
**Description:** Checks the balance of a specific coin (USDT, USDC, etc) in your wallet.\
**Sample Request**

```json
{ "coin": "usdt" }
```

**Sample Response**

```json
{ "status": "success", "balance": "10000 USDT" }
```

***

#### `POST /v1/crypto_payout`

**Scope:** `crypto_wallets`\
**Description:** Requests a crypto payout to one of your whitelisted settlement wallets.\
**Sample Request**

```json
{ "coin": "usdt", "wallet_alias": "receiver A", "amount": 500 }
```

**Sample Response**

```json
{
  "status": "success",
  "response": {
    "id": "dfeff3fcdd31dsdd",
    "coin": "usdt",
    "status": "successful",
    "Amount sent": "500",
    "Wallet received alias": "receiver A",
    "fee": "5 usdt",
    "tx_hash": "0xabc123..."
  }
}
```

***

### Fiat Wallets

#### `POST /v1/fiat_balance`

**Scope:** `fiat_wallet`\
**Description:** Returns the current balance of a fiat currency account (e.g., NGN).\
**Sample Request**

```json
{ "currency": "ngn" }
```

**Sample Response**

```json
{ "status": "success", "balance": "1500000 NGN" }
```

***

#### `POST /v1/fiat_payout`

**Scope:** `fiat_wallet`\
**Description:** Initiates a payout in fiat to one of your settlement accounts.\
**Sample Request**

```json
{ "currency": "NGN", "amount": 500000, "account_alias": "Vendor A" }
```

**Sample Response**

```json
{
  "status": "success",
  "response": { "id": "abc123", "status": "pending", "currency": "NGN", "amount": "500000" }
}
```

***

#### `POST /v1/funding_account`

**Scope:** `fiat_wallet`\
**Description:** Returns the bank account details you should deposit into when funding your fiat wallet.\
**Sample Request**

```json
{ "currency": "NGN" }
```

**Sample Response**

```json
{
  "status": "success",
  "response": { "bank": "Providus Bank", "account_number": "001726334", "account_name": "Ledig Ltd" }
}
```

***

#### `POST /v1/funding_request`

**Scope:** `fiat_wallet`\
**Description:** Submits a proof of payment (POP) after you have funded your fiat wallet. Ledig admins verify before crediting your wallet.\
**Sample Request**

```json
{ "pop": "https://example.com/proof.jpg" }
```

**Sample Response**

```json
{ "status": "success", "response": { "message": "Funding request received, pending verification" } }
```

***

#### `POST /v1/fiat_virtuals`

**Scope:** `fiat_wallet`\
**Description:** Lists all your fiat virtual accounts. These are unique bank accounts assigned to you for receiving local deposits.\
**Sample Response**

```json
{
  "status": "success",
  "response": [
    { "alias": "Vault B", "Bank": "Providus", "Account Number": "0123456789", "Currency": "NGN" }
  ]
}
```

***

#### `POST /v1/virtual_details`

**Scope:** `fiat_wallet`\
**Description:** Fetches full details of a specific virtual account by alias.\
**Sample Request**

```json
{ "alias": "static vault" }
```

**Sample Response**

```json
{
  "status": "success",
  "response": {
    "alias": "static vault",
    "Bank": "Providus Bank",
    "Account Name": "Senju Ltd",
    "Account Number": "003322123",
    "Currency": "NGN"
  }
}
```

***

### Settlement Wallets & Accounts

#### `POST /v1/settlement_wallets`

**Scope:** None\
**Description:** Returns all crypto settlement wallets linked to your business. Use these when configuring outbound transfers.\
**Sample Request**

```json
{ "network": "tron" }
```

**Sample Response**

```json
{
  "status": "success",
  "response": [
    { "Alias": "Treasury Vault", "Address": "0x123...", "Network": "Tron" }
  ]
}
```

***

#### `POST /v1/settlement_wallet_details`

**Scope:** None\
**Description:** Returns details of a single settlement wallet by alias.\
**Sample Request**

```json
{ "alias": "vaulter" }
```

**Sample Response**

```json
{
  "status": "success",
  "response": {
    "Alias": "vaulter",
    "Address": "sse5dofd5dsdddd",
    "Status": "Whitelisted",
    "Network": "Ethereum Erc20",
    "Assets Supported": ["USDT","USDC"],
    "Aml Data": "vaulter"
  }
}
```

***

#### `POST /v1/add_settlement_wallet`

**Scope:** None\
**Description:** Requests a new settlement wallet to be added and whitelisted in the Ledig ecosystem. Once approved, this wallet can safely receive crypto.\
**Sample Request**

```json
{ "Alias": "api vault", "Network": "tron", "address": "TU3kjFuhtEo42tsCBtfYUAZxoqQ4yuSLQ5" }
```

**Sample Response**

```json
{
  "status": "success",
  "response": {
    "Status": "Pending",
    "Wallet Alias": "api vault",
    "Wallet Address": "TU3kjFuhtEo42tsCBtfYUAZxoqQ4yuSLQ5",
    "Network": "tron",
    "Message": "Please await Wallet whitelist"
  }
}
```

***

#### `POST /v1/settlement_accounts`

**Scope:** None\
**Description:** Lists all fiat settlement accounts linked to your business. Use these for payouts.\
**Sample Response**

```json
{
  "status": "success",
  "response": [
    { "alias": "qasq", "Account Number": "0129293239339", "Bank": "qa", "Currency": "KES" }
  ]
}
```

***

#### `POST /v1/settlement_account_details`

**Scope:** None\
**Description:** Returns full details of a settlement account by alias.\
**Sample Request**

```json
{ "alias": "qasq" }
```

**Sample Response**

```json
{
  "status": "success",
  "response": {
    "alias": "qasq",
    "Account Number": "0129293239339",
    "Account Name": "aaqaq",
    "Bank": "qa",
    "Status": "Whitelisted",
    "Currency": "KES",
    "Other Details": "ssaaa..."
  }
}
```

***

### Sandbox / Admin Endpoints

#### `POST /v1/fiat_balance_update`

**Scope:** None\
**Description:** Sandbox only. Updates fiat balance manually for testing.\
**Sample Request**

```json
{ "currency": "NGN", "amount": 10000 }
```

**Sample Response**

```json
{ "status": "success", "currency": "NGN", "amount": 10000 }
```

***

#### `POST /v1/crypto_balance_update`

**Scope:** None\
**Description:** Sandbox only. Updates crypto balance manually for testing.\
**Sample Request**

```json
{ "coin": "usdt", "amount": 5000 }
```

**Sample Response**

```json
{ "status": "success", "coin": "usdt", "amount": 5000 }
```