> ## 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.

# 共享钱包与充提

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="共享钱包与充提" />

市场余额与经济插件余额是两份不同的账。充值从外部后端扣款后计入市场；提现从市场扣款后交给外部后端。购买、竞价与供货在市场账本内部结算，不应每次成交都分别调用各节点的经济插件。

| Provider | 配置与认证重点 |
| - | - |
| `vault` | 必须存在实际 Economy 实现，配置其名称；Vault 自身不是完整经济插件 |
| `playerpoints` | 精度必须为 0；金额与最终余额都需在后端整数范围内 |
| `coinsengine` | 匹配遗留 CoinsEngine API 和实际币种 ID；不要用 ExcellentEconomy 兼容层冒充 |
| `excellenteconomy` | 独立的新 API 适配；配置实际币种 ID 与精度 |

每个币种固定 ID、精度、原生币种和充提网关。已经使用的币种不能通过改名、改精度或改 provider 无缝变成另一种货币；这些变更需要完整迁移和对账。不同货币不自动兑换。

玩家界面使用币种显示名称，例如“金币”“点券”，不附加内部 ID。可在中英语言文件的 `currency-names.<币种ID>` 个性化名称，或使用 `currencies.<币种ID>.display-name` 字符串／双语映射；显示名称不改变余额归属或经济身份。具体优先级和重载方式见[配置指南](/kitemarket/guide#_3-配置币种)。

<ScreenshotPlaceholder image="https://mintlify.s3.us-west-1.amazonaws.com/kitemc/images/kitemarket/screenshot-wallet.png" title="市场钱包" description="真实游戏截图待补充：展示各币种可用余额、冻结资金和充值／提现入口。" lang="zh" />

<h2 id="金额输入与真实上限">
  金额输入与真实上限
</h2>

币种页同时查询市场钱包和本节点经济后端的真实余额。金额页提供增减、预设、最大值及聊天自定义输入；最大值按以下限制取最小值，使用币种最小单位计算：

| 操作 | 当前可用上限 |
| - | - |
| 充值 | 外部可用余额、币种单次金额上限、市场钱包整数余量（包含已有可用与冻结资金） |
| 提现 | 市场可用余额、币种单次金额上限、后端可预查的接收容量 |

冻结资金不能提现。后端未提供可预查的接收容量时，报价使用其他已知限额，最终仍由后端校验；这不代表后端可以无限接收。余额查询失败会显示不可用原因并阻止充提，不显示假零或虚构的最大金额。

进入金额页、打开确认和实际执行前重新查询。余额或接收容量变化导致金额超限时，会提示重新选择；重新充值后也要刷新并确认原交易。只有当前兼容网关处理外部余额，切服不会偷偷调用其他节点。

<h2 id="网关节点">
  网关节点
</h2>

按币种设置 `gateway`，它必须等于目标节点的 `network.node-id`。**玩家需要切换到该节点执行充提**；没有自动远程 RPC 转发。不在对应节点会返回 `GATEWAY_NODE`，市场内余额和交易仍然共享。

Folia 节点没有可认证经济后端时，可只参与市场内部交易，由同 Minecraft 版本的兼容 Paper 节点提供充提。网关停机时暂停该币种充提，不从其他节点临时直接扣款。

<h2 id="启用适配器">
  启用适配器
</h2>

`certified-versions` 必须列出经过你实际测试的目标插件版本；空列表会阻止充提。对 `vault` 填写 Vault 自身版本，另用 `vault-provider` 锁定实际 Economy 服务名称，并单独验证该经济实现。这个设置是部署方的准入控制，**填写版本号不会自动取得 KiteMC 官方认证**。Folia 上默认不允许未验证 provider；不要单纯设置 `certified-folia: true` 绕过验证。

测试应覆盖充值、提现、余额不足、精度和最大金额、后端取消/失败、断线、重启和并发外部余额变化。查看[配置示例](/kitemarket/guide)与[认证矩阵](/kitemarket/compatibility)。

<h2 id="失败与-unknown">
  失败与 UNKNOWN
</h2>

外部 API 返回失败时，按操作状态处理或返还预留资金；未确定是否生效时记为 `UNKNOWN`，不能自动再次调用。管理员必须检查外部记录及市场操作，不可只看玩家当前余额就强制“修复”。

部分后端先修改内存，再异步持久化，因此 API 成功不等于跨系统提交完成。市场内部账本事务不代表外部充提在任意进程崩溃下都能自动恢复。尚未实测的后端组合保持禁用。


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