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

# Shared wallet and transfers

export const ScreenshotPlaceholder = ({image, src, title, caption, description, lang = "zh"}) => {
  const source = image || src;
  const label = title || caption || (lang === "en" ? "Gameplay screenshot" : "游戏截图");
  const [ready, setReady] = useState(false);
  const imageRef = useRef(null);
  useEffect(() => {
    const current = imageRef.current;
    setReady(Boolean(current && current.complete && current.naturalWidth > 0));
  }, [source]);
  return <figure className="km-screenshot">
      <div className="km-screenshot-frame">
        {source ? <img ref={imageRef} src={source} alt={label} className={ready ? "km-screenshot-image" : "km-screenshot-image km-screenshot-pending"} onLoad={() => setReady(true)} onError={() => setReady(false)} /> : null}
        {!ready ? <div className="km-screenshot-placeholder">
            <svg width="36" height="36" viewBox="0 0 36 36" fill="none" aria-hidden="true">
              <rect x="5" y="6" width="26" height="24" rx="4" stroke="currentColor" strokeWidth="1.5" />
              <circle cx="13" cy="13" r="2.5" stroke="currentColor" strokeWidth="1.5" />
              <path d="M6 26L14 19L19 23L24 16L31 24" stroke="currentColor" strokeWidth="1.5" strokeLinejoin="round" />
            </svg>
            <strong>{label}</strong>
            <p>{description || (lang === "en" ? "A real gameplay screenshot will be added here." : "此处预留真实游戏截图。")}</p>
          </div> : null}
      </div>
      <figcaption>{label}</figcaption>
    </figure>;
};

<span id="shared-wallet-and-transfers" />

Market funds and economy-plugin funds are separate balances. A deposit debits the external backend and credits the market; a withdrawal does the reverse. Purchases, bids, and fulfillment settle inside the market ledger instead of calling each node's economy plugin for every trade.

| Provider | Configuration and certification |
| - | - |
| `vault` | Requires an actual Economy implementation and its configured name; Vault alone is not an economy |
| `playerpoints` | Scale must be 0; amounts and resulting balances must fit the backend's integer range |
| `coinsengine` | Uses the legacy CoinsEngine API and native currency ID; an ExcellentEconomy shim is not a replacement |
| `excellenteconomy` | Separate renamed API adapter with its own native currency ID and scale |

Each currency has a stable ID, scale, native mapping, and transfer gateway. Changing an active currency's scale or provider requires migration and reconciliation; it is not a normal rename. There is no automatic currency exchange.

Player interfaces use display names such as “Coins” or “Points” without appending internal IDs. Customize each locale's `currency-names.<currency-id>` or an explicit shared/bilingual `currencies.<currency-id>.display-name`. Labels do not change balances or economy identity; see the [configuration guide](/en/kitemarket/guide#_3-currencies) for precedence and reload behavior.

<ScreenshotPlaceholder image="https://mintlify.s3.us-west-1.amazonaws.com/kitemc/images/kitemarket/screenshot-wallet.png" title="Market wallet" description="Real gameplay screenshot coming later: available and reserved currency balances, deposit and withdrawal entrances." lang="en" />

<h2 id="amount-input-and-actual-limits">
  Amount input and actual limits
</h2>

The currency page queries both the market wallet and the local economy backend's actual balance. Amount input offers increments, presets, a maximum button and custom chat input. The maximum is the minimum of these limits, calculated in the currency's minor units:

| Operation | Currently available limit |
| - | - |
| Deposit | Available external funds, currency per-operation amount limit, and remaining market-wallet integer capacity including available and reserved funds |
| Withdrawal | Available market funds, currency per-operation amount limit, and any known backend receive capacity |

Reserved funds cannot be withdrawn. When a backend cannot quote its receive capacity, the quote uses other known limits and the backend still validates execution; this does not mean it can receive unlimited funds. Failed balance queries report the reason and block transfers without inventing a zero balance or maximum amount.

Opening amount input, entering confirmation and executing the transfer query again. If changed funds or receive capacity make the amount too large, choose it again. After depositing funds, refresh and reconfirm the original trade as well. Only the compatible local gateway handles external balances; changing nodes does not silently call another server.

<h2 id="gateway-node">
  Gateway node
</h2>

Assign a `gateway` to each currency, matching the target node's `network.node-id`. **Players must switch to that node to deposit or withdraw.** There is no automatic remote RPC forwarding. Another node returns `GATEWAY_NODE`; market funds and internal trading remain shared.

A Folia node without a certified economy backend can still participate in internal trading, while a compatible Paper node on the same Minecraft version handles transfers. Gateway downtime pauses transfers for that currency; other nodes must not start debiting it directly.

<h2 id="enabling-an-adapter">
  Enabling an adapter
</h2>

`certified-versions` must contain the target plugin versions you have actually validated. An empty list blocks transfers. For `vault`, list the Vault version itself, pin the actual Economy service name with `vault-provider`, and independently test that economy implementation. This is an operator allowlist; **entering a version does not create official KiteMC certification**. Folia providers are blocked by default unless verified; do not set `certified-folia: true` merely to bypass checks.

Test deposits, withdrawals, insufficient funds, precision and amount limits, backend cancellation/failure, disconnects, restarts, and concurrent external changes. See the [configuration example](/en/kitemarket/guide) and [certification matrix](/en/kitemarket/compatibility).

<h2 id="failure-and-unknown">
  Failure and UNKNOWN
</h2>

A rejected external call is handled according to its operation state, including release of reservations where appropriate. An uncertain result becomes `UNKNOWN` and must not be called again automatically. Administrators need external evidence and market operation records; the player's current balance alone does not prove a historical transfer.

Some backends update memory before asynchronously persisting it. API success is not a cross-system commit. Internal market transactions do not guarantee automatic recovery of external transfers across every process crash. Keep untested backend combinations disabled.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.