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

# 创建转账（法币兑换稳定币、稳定币兑换法币、稳定币互换）

> 创建转账（法币兑换稳定币、稳定币兑换法币、稳定币互换）

完整[认证、签名、数据约定与错误响应](https://docs.stablepayfi.ai/zh/api/stablecoin-exchange/overview)。每次重试均须重新生成时间戳、nonce 与签名。

`POST /transfer` 一次兑换执行：`on_ramp` 法币换稳定币、`off_ramp` 稳定币换法币、swap 稳定币互换。

## 请求头

**Authorization** `string` *required*

Bearer API Key。

**X-StablePay-Timestamp** `string` *required*

Unix 秒，允许与服务端相差最多 5 分钟。

**X-StablePay-Nonce** `string` *required*

每次请求唯一的随机串，16–64 字符。

**X-StablePay-Signature** `string` *required*

HMAC-SHA256 签名，小写十六进制；签名必须对应实际发送的请求体。

**Idempotency-Key** `string`

幂等键

## 请求参数

**merchant\_id** `string`

引用报价时须与报价商户一致

**transfer\_type** `string` *required*

`on_ramp`、`off_ramp`、swap

**amount** `integer` *required*

卖出金额；`on_ramp` 须等于充值记录金额

**external\_transfer\_id** `string`

业务参考号

**quote\_id** `string`

引用的报价，与 `rate_type` 互斥

**rate\_type** `string`

fixed 锁汇、floating 浮动

**fiat\_deposit\_id** `string`

`on_ramp` 必传，充值记录 ID

**source\_currency** `string`

swap 与 `off_ramp` 的卖出币种

**source\_network** `string`

卖出网络

**source\_account\_no** `string`

swap 与 `off_ramp` 必传

**target\_currency** `string`

买入币种

**target\_network** `string`

买入网络

**target\_account\_no** `string`

`on_ramp` 入账账户

**recipient\_id** `string`

`off_ramp` 必传；`on_ramp` 与 swap 可选

**metadata** `object`

自定义元数据

## 响应

**transfer\_id** `string` *required*

转账 ID，10 位数字

**merchant\_id** `string` *required*

商户 ID

**external\_transfer\_id** `string`

业务参考号

**transfer\_type** `string` *required*

`on_ramp`、`off_ramp`、swap

**quote\_id** `string`

执行的报价 ID

**fiat\_deposit\_id** `string`

`on_ramp` 的充值记录

**source\_currency** `string`

卖出币种

**target\_currency** `string`

买入币种

**source\_network** `string`

卖出网络

**target\_network** `string`

买入网络

**source\_amount** `integer`

卖出金额，不含费用

**target\_amount** `integer`

买入金额；floating 下为估算

**rate\_type** `string`

fixed 或 floating

**rate** `string`

汇率，十进制字符串

**fee\_amount** `integer`

手续费

**fee\_currency** `string`

费用币种

**source\_account\_no** `string`

转出账户

**target\_account\_no** `string`

入账账户

**recipient\_id** `string`

收款人 ID

**recipient** `object`

地址与 memo 或银行字段

**status** `string` *required*

processing、`payment_submitted`、completed、`funds_refunded`、`bounced_back`

**failure\_reason** `string`

失败原因

**metadata** `object`

自定义元数据

**created** `integer` *required*

创建时间

**updated** `integer`

最近更新时间

## 状态与错误

400 参数不合法；404 报价或充值记录不存在；409 报价已用或过期、余额不足。

```bash cURL theme={"system"}
curl --request POST \
  --url "https://api.stablepay.co/api/v1/transfer" \
  --header "Authorization: Bearer <API_KEY>" \
  --header "X-StablePay-Timestamp: <TIMESTAMP>" \
  --header "X-StablePay-Nonce: <NONCE>" \
  --header "X-StablePay-Signature: <SIGNATURE>" \
  --header "Content-Type: application/json" \
  --data '{
  "transfer_type": "on_ramp",
  "fiat_deposit_id": "9000000090",
  "amount": 100500,
  "target_currency": "USDC",
  "target_network": "solana",
  "rate_type": "fixed"
}'
```

```javascript JavaScript theme={"system"}
const response = await fetch("https://api.stablepay.co/api/v1/transfer", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <API_KEY>",
    "X-StablePay-Timestamp": "<TIMESTAMP>",
    "X-StablePay-Nonce": "<NONCE>",
    "X-StablePay-Signature": "<SIGNATURE>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "transfer_type": "on_ramp",
    "fiat_deposit_id": "9000000090",
    "amount": 100500,
    "target_currency": "USDC",
    "target_network": "solana",
    "rate_type": "fixed"
  })
});
console.log(await response.json());
```

```json 200 theme={"system"}
{
  "transfer_id": "9000000011",
  "merchant_id": "2000000001",
  "transfer_type": "on_ramp",
  "quote_id": "9000000017",
  "fiat_deposit_id": "9000000090",
  "source_amount": 100500,
  "target_amount": 100479,
  "rate_type": "fixed",
  "rate": "0.9998",
  "fee_amount": 5,
  "fee_currency": "USD",
  "target_account_no": "00000001",
  "status": "processing",
  "created": 1718726400
}
```


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