Fund endpoints let an organization transfer funds to an Infini UID, withdraw funds, query withdrawal status and fees, and read its available USDT, USDC, and USD balances.

All Fund API prefix:

/v2/funds

All endpoints require Ed25519 v2 authentication, including the signed Digest on every request. Permissions fund.withdraw, card.create, card.reveal and payout.write require a matching non-empty IP allowlist.

IP whitelist: API keys that include fund.withdraw must be configured with a non-empty IP whitelist when created or updated in the merchant dashboard.

request_id is optional when creating a withdrawal:

• When omitted, Infini generates the withdrawal request ID and preserves the existing withdrawal behavior. Separate caller retries without a shared ID are not idempotent.
• When supplied, it must be a UUID and is used as the idempotency key.
• When the same merchant retries with the same request_id, the API returns the previously created withdrawal information with is_duplicate: true.
• Use one request_id for exactly one logical withdrawal. Do not reuse it for a different amount, chain, token, or destination address.

After gateway authentication, application responses use the standard code / message / data envelope. Business success is indicated by code === 0; a non-zero code indicates an error and message carries the details. Some downstream business failures can be returned with HTTP 200, a non-zero code, and data: null.

Authentication failures return HTTP 401; permission/IP failures return HTTP 403. Check the HTTP status and the business response code. Other business errors may return HTTP 200.

POST /v2/funds/swap — requires fund.withdraw.

Supports exchanges between different USDC, USDT, and USD WALLET accounts belonging to the merchant associated with the API key. Both accounts must exist. If either currency is USD, you must already have a USD Cash Account; USDC ↔ USDT does not require one. This operation does not open accounts or use Easy Earn balances.

USD amounts support two decimal places; USDC/USDT support six. Use plain decimal strings, without exponents; values in minor units must fit a signed 64-bit integer. The minimum uses target currency precision.

For a positive effective FX fee rate, the fee is rounded up to the smallest source currency unit: USD 0.01, USDC/USDT 0.000001. Explicit zero-rate merchant rules and exempt currency pairs still charge zero; there is no minimum fee for zero-rate merchants.

The swap executes synchronously at the current applicable rate and fee. There is no quote reservation. price means target currency per one unit of source currency. fx_fee is deducted from amount in fx_fee_currency, which is always the source currency. output_amount = truncate((amount - fx_fee) × price, target precision). Rates and fees in the example below are illustrative.

If the rounded net output is below min_output_amount, or is zero, the operation fails without debiting or crediting funds. Omitting the minimum accepts the execution-time rate; zero disables the minimum. Missing accounts, blocked funds, insufficient balance, invalid parameters, and rate limits also reject the operation. Check the response envelope's code for business errors.

Completed retries with the same merchant and UUID return the original amounts, price, and fee with is_duplicate=true, including after key rotation. Changing currencies, amount, or minimum under that ID is rejected. IDs are isolated by merchant and operation. Equivalent decimal representations are normalized; an omitted minimum and explicit zero are distinct request parameters. Failed attempts do not persist a completed result or reserve a rate. After a timeout, retry the same ID and parameters.

{
  "request_id": "e94b4e88-36c2-4550-907e-839742cf5fae",
  "source_currency": "USDC",
  "target_currency": "USD",
  "amount": "100",
  "min_output_amount": "99"
}

{
  "code": 0,
  "message": "",
  "data": {
    "request_id": "e94b4e88-36c2-4550-907e-839742cf5fae",
    "output_amount": "99.5",
    "price": "1",
    "fx_fee": "0.5",
    "fx_fee_currency": "USDC",
    "is_duplicate": false
  }
}

POST /v2/funds/internal-transfer

Transfers funds from the authenticated organization to a recipient identified by an Infini UID.

• Required permission: fund.withdraw
• V1 supports same-currency transfers in USDT, USDC, or USD only.
• The transfer has no fee: the amount deducted from the sender equals the amount received by the recipient.
• A successful V1 transfer completes synchronously and returns status: completed.

{
  "request_id": "4b4436ba-90a1-4f26-940d-97177a7a3400",
  "recipient_uid": "12345678",
  "token_type": "USDC",
  "source_currency": "USDC",
  "amount": "10.25",
  "note": "Customer refund"
}

{
  "code": 0,
  "message": "",
  "data": {
    "request_id": "4b4436ba-90a1-4f26-940d-97177a7a3400",
    "status": "completed",
    "is_duplicate": false
  }
}

request_id is optional. When supplied, it must be a UUID and is used as the idempotency key. A retry by the same organization with an already completed request_id returns the original request ID with is_duplicate: true. Use one request ID for exactly one logical transfer; do not reuse it for different transfer details.

POST /v2/funds/withdraw

Creates a withdrawal from the authenticated organization to an external wallet.

• Required permission: fund.withdraw

Use GET /v2/funds/withdraw/fees as the current source of truth for enabled chain/token pairs and their fees. Chain and token names in examples are uppercase.

{
  "request_id": "e94b4e88-36c2-4550-907e-839742cf5fae",
  "chain": "ETHEREUM",
  "token_type": "USDT",
  "source_currency": "USD",
  "amount": "10.00",
  "wallet_address": "0x5f716e5775b18409917e2a2f0762d29d6c385cb0",
  "note": "Treasury withdrawal"
}

{
  "code": 0,
  "message": "",
  "data": {
    "request_id": "e94b4e88-36c2-4550-907e-839742cf5fae",
    "status": "pending",
    "is_duplicate": false
  }
}

For an idempotent retry, data.is_duplicate is true and data.status is the existing withdrawal's current status.

Authentication failures return HTTP 401; permission/IP failures return HTTP 403. Check the HTTP status and the business response code. Other business errors may return HTTP 200.

GET /v2/funds/withdraw/status?request_id={request_id}

Returns the current state and amounts for a withdrawal owned by the authenticated organization.

• Required permission: fund.withdraw
• The Ed25519 signing path must include ?request_id={request_id}.

{
  "code": 0,
  "message": "",
  "data": {
    "request_id": "e94b4e88-36c2-4550-907e-839742cf5fae",
    "status": "completed",
    "amount": "11",
    "fee": "0.1",
    "actual_amount": "10.9",
    "transaction_hash": "0xabc123",
    "chain": "ETHEREUM",
    "token_type": "USDT",
    "source_currency": "USD",
    "gas_fee": "0.08",
    "gas_fee_currency": "USD",
    "fx_fee": "0.02",
    "fx_fee_currency": "USD",
    "fee_paid_by": "BENEFICIARY"
  }
}

POST /v2/funds/withdraw/status/batch

Returns withdrawals owned by the authenticated organization whose creation times fall within the requested range.

• Required permission: fund.withdraw
• start_time and end_time are Unix timestamps in seconds and form an inclusive range.
• Results are ordered by created_at descending.
• page defaults to 1; page_size defaults to 20 and cannot exceed 100.
• A range with no matching withdrawals returns HTTP 200 with an empty withdrawals array.
• Invalid time ranges or pagination values return HTTP 400. A failure that prevents processing the query returns HTTP 500.

{
  "start_time": 1787500000,
  "end_time": 1787599999,
  "page": 1,
  "page_size": 20
}

Because this is a POST request with a body, include the body Digest in the Ed25519-signed request and sign the path /v2/funds/withdraw/status/batch.

{
  "code": 0,
  "message": "",
  "data": {
    "withdrawals": [
      {
        "request_id": "e94b4e88-36c2-4550-907e-839742cf5fae",
        "created_at": 1787564636,
        "status": "completed",
        "amount": "11",
        "fee": "0.1",
        "actual_amount": "10.9",
        "transaction_hash": "0xabc123",
        "chain": "ETHEREUM",
        "token_type": "USDT",
        "source_currency": "USDT",
        "gas_fee": "0.1",
        "gas_fee_currency": "USDT",
        "fx_fee": "0",
        "fx_fee_currency": "USDT",
        "fee_paid_by": "BENEFICIARY"
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 20,
    "total_pages": 1
  }
}

Each item uses the same amount, fee, chain, and status semantics as the single-query endpoint and additionally returns created_at. Pagination metadata describes the complete matching time range, not only the current page.

GET /v2/funds/withdraw/fees

Returns currently enabled public chain/token pairs and their fees. Fees are dynamic; clients should query this endpoint instead of hard-coding a fee table.

• Required permission: fund.withdraw

{
  "code": 0,
  "message": "",
  "data": {
    "fees": [
      {
        "chain": "ARBITRUM",
        "token_type": "USDC",
        "withdraw_fee": "0.5"
      },
      {
        "chain": "ETHEREUM",
        "token_type": "USDT",
        "withdraw_fee": "2"
      }
    ]
  }
}

Each withdraw_fee is denominated in the corresponding token_type.

GET /v2/funds/balances

Returns only the authenticated organization's USDT, USDC, and USD Cash AVAILABLE_BALANCE values.

• Required permission: fund.withdraw

{
  "code": 0,
  "message": "",
  "data": {
    "available_balance_usdt": "120.50",
    "available_balance_usdc": "75.25",
    "available_balance_usd": "1000.00"
  }
}

When the organization has no balance entry for one of the currencies, its value is returned as "0". In particular, available_balance_usd is "0" when the USD Cash Account is not open.