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

# 共享钱包与充提

市场余额与外部余额分别记录。外部来源可以是经济插件、原版经验或匹配的实物货币；充值扣除外部余额后计入市场，提现从市场扣款后交给对应来源。购买、竞价与供货在市场账本内部结算，不会每次成交都调用各节点的外部经济接口。

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

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

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

![共享钱包：绿宝石币与充提网关](https://mintcdn.com/kitemc/i9Oi52nmTzZoWu-6/images/kitemarket/v1-1/wallet.png?fit=max\&auto=format\&n=i9Oi52nmTzZoWu-6\&q=85\&s=1b2400af981a27fd90a0031a6372903f)

共享钱包：绿宝石币与充提网关

## 经验与物品币

除经济插件外，钱包也可使用原版经验或真实物品作为充提来源：

| `provider` | 单位与要求 |
| - | - |
| `experience` | 经验点，`scale: 0` |
| `experience-level` | 经验等级，`scale: 0`；与经验点模式在整个市场网络中二选一 |
| `item` | 真实物品币，`scale: 0`；需要完整 `item-sample` 和正整数面额 `denomination` |

经验点与等级不是线性兑换关系，同一网络只能启用其中一种模式。充提会检查玩家在线、存活状态和真实经验，仍须在所选网关节点执行。

物品币按完整样品属性比较，只有相同材料还不够。例如面额为10时，8枚匹配样品可充值80；提现30发回3枚样品。充提金额必须是面额的整数倍，提现按物品原有堆叠上限和实际背包容量发放，空间不足不会硬塞超大堆叠。

样品、面额、provider 和精度都是币种身份的一部分。旧余额仍依赖原身份时不能直接替换配置；详细字段见[币种配置](https://www.kitemc.asia/kitemarket/configuration/currencies.md#v11-native-currency-configuration)。

## 金额输入与真实上限

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

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

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

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

## 交易缺口补款

购买或出价所需的市场余额不足时，补款页展示真实缺口、所选币种和将从外部扣除的金额。确认充值后，资金先进入市场钱包。

**充值成功不会自动完成原交易。** 系统重新读取订单、数量、费用与余额，再打开新的交易确认。订单变化或已经结束时保留已充值余额，按当前状态提示下一步；不会沿用旧报价静默购买，也不会因交易失败重复充值。

网关不可用或充值结果为 `UNKNOWN` 时先处理该笔充提，不继续提交交易。操作结果与交易收据分别查看。

![竞拍前的缺口补款说明](https://mintcdn.com/kitemc/i9Oi52nmTzZoWu-6/images/kitemarket/v1-1/shortfall-top-up.png?fit=max\&auto=format\&n=i9Oi52nmTzZoWu-6\&q=85\&s=44ee2dffd00e0d9e3d93885a4b0180fd)

竞拍前的缺口补款说明

## 收益预约与个人自动化

从钱包入口或 `/km automation` 查看个人设置。以下三项分别确认启用，默认均关闭：

| 设置 | 行为 |
| - | - |
| 未来成交收益提现 | 为后续成交收入建立独立提现预约 |
| 登录提现 | 登录后按当前网关、余额与会话条件处理可提现资金 |
| 自动领取 | 按实际背包空间处理待领取物品 |

预约、冻结、普通可用余额与待领物品分别展示。关闭未来收益提现只停止建立后续预约，**不会自动释放已有预约**；到预约页查看状态，再明确选择执行或释放。

任务分有界批次执行，不保证一轮清空全部余额或资产。网关不可用、背包空间不足、会话变化或存在未知外部结果时暂停；领取不会突破物品本来的堆叠量。

`UNKNOWN` 不作为失败自动重试。先查看原操作及证据，按[异常核对](https://www.kitemc.asia/kitemarket/operations.md#核对-unknown)处理，再恢复相关任务。手动领取、分类和当前页批量确认见[领取资产](https://www.kitemc.asia/kitemarket/trading/claims.md)。

![收益、登录提现与自动领取的独立入口](https://mintcdn.com/kitemc/i9Oi52nmTzZoWu-6/images/kitemarket/v1-1/automation.png?fit=max\&auto=format\&n=i9Oi52nmTzZoWu-6\&q=85\&s=e2d081341d91c462ad4d0741acb781a1)

收益、登录提现与自动领取的独立入口

## 网关节点

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

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

## 启用适配器

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

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

## 失败与 UNKNOWN

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

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


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