Integration APIs
POST认领创作者奖励
Last updated April 23, 2026
通过单次调用，跨钱包有资格获得的每个 Genesis 联合曲线和 Raydium CPMM bucket 认领累积的创作者奖励。该端点返回钱包（或指定的 payer）必须签名并提交的 base64 编码 Solana 交易列表。
可用 SDK 包装器
大多数集成方应使用 Genesis JavaScript SDK 中的 claimCreatorRewards — 它处理交易反序列化、错误解析，并直接接入 Umi 身份进行签名。仅在无法依赖 SDK 时才直接调用此端点。
Summary
POST /v1/creator-rewards/claim 通过一次调用返回认领钱包在所有联合曲线和 Raydium CPMM bucket 上累积的创作者奖励所需的 Solana 交易。
- 聚合 — 一次请求即可跨所有符合条件的 bucket 认领；每个 bucket 返回一个交易
- 签名 — 响应是钱包（或可选的
payer）必须签名并提交的 base64 编码的 Solana 交易 - 错误 — 当没有累积时返回 HTTP
400"No rewards available to claim"；调用方必须基于错误分支，而不是空数组 - SDK 包装器 —
claimCreatorRewards处理反序列化、类型化错误和 Umi 签名
端点
POST /v1/creator-rewards/claim
| 环境 | 基础 URL |
|---|---|
| Devnet & Mainnet | https://api.metaplex.com |
请求体
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
wallet | string | 是 | 要认领的创作者费钱包的 base58 编码公钥。这是在 bucket 上设置为 creatorFeeWallet 的钱包——若未配置覆盖，则为发行钱包。 |
network | string | 否 | 'solana-mainnet'（默认）或 'solana-devnet'。必须与基础 URL 的集群匹配。 |
payer | string | 否 | 承担返回交易的交易费和租金的 base58 编码公钥。省略时默认为 wallet。 |
何时设置 payer
当创作者费钱包不持有 SOL 时（例如 agent PDA 或冷钱包），将 payer 设置为不同的钱包。payer 必须签署返回的交易，因此通常是代表创作者提交认领的钱包。创作者费收件人仍会收到认领的 SOL — payer 仅承担费用和租金。
请求示例
1import { claimCreatorRewards } from '@metaplex-foundation/genesis'
2import { base58 } from '@metaplex-foundation/umi/serializers'
3import { createUmi } from '@metaplex-foundation/umi-bundle-defaults'
4import { keypairIdentity } from '@metaplex-foundation/umi'
5
6const umi = createUmi('https://api.mainnet-beta.solana.com')
7const keypair = umi.eddsa.createKeypairFromSecretKey(mySecretKeyBytes)
8umi.use(keypairIdentity(keypair))
9
10const result = await claimCreatorRewards(umi, {}, {
11 wallet: umi.identity.publicKey,
12 network: 'solana-mainnet',
13 // payer is optional — defaults to `wallet` on the server.
14 // Set it to have a different wallet cover rent and transaction fees.
15 // payer: umi.identity.publicKey,
16})
17
18for (const tx of result.transactions) {
19 const signed = await umi.identity.signTransaction(tx)
20 const signature = await umi.rpc.sendTransaction(signed, {
21 preflightCommitment: 'confirmed',
22 })
23 await umi.rpc.confirmTransaction(signature, {
24 strategy: { type: 'blockhash', ...result.blockhash },
25 commitment: 'confirmed',
26 })
27 console.log('Claimed:', base58.deserialize(signature)[0])
28}
29
30// Claimed: 5uGGYEMmjP2HpyFCvLPNpVDSQEBtUE3LR6ZQFqhJxQSh5FbKacSyN8nQmAJowuFs6BTCdwzoFyyJz8Y2hQx8kPxo
31// Claimed: 3TAroVovEap1ZEAJYq3WiDZoMK3GU3soCdrhvZJNg6b9EANqvWrVcDGNffm7mD8wvtpR7ynWQBcbrmz8AK6nrhfy
1# Claim creator rewards. Response contains base64-encoded transactions
2# the wallet (or payer) must sign and send.
3curl -X POST https://api.metaplex.com/v1/creator-rewards/claim \
4 -H "Content-Type: application/json" \
5 -d '{
6 "wallet": "CREATOR_FEE_WALLET_ADDRESS_HERE",
7 "network": "solana-mainnet"
8 }'
9
10# Add "payer" when the creator fee wallet does not hold SOL (e.g. an agent PDA):
11# "payer": "PAYER_WALLET_ADDRESS_HERE"
成功响应
{
"data": {
"transactions": ["<base64 transaction>", "<base64 transaction>"],
"blockhash": {
"blockhash": "ERKYmtrmNSKaw3VpnFYAfK3jvWGnd15Nf9kJxZqJ7JHx",
"lastValidBlockHeight": 445407640
}
}
}
| 字段 | 类型 | 说明 |
|---|---|---|
data.transactions | string[] | base64 编码的 Solana 交易。每个都必须反序列化、由 payer（以及创作者费钱包，如果是单独的签名者）签名并提交。 |
data.blockhash.blockhash | string | 构建交易时使用的最近区块哈希。请将其与 confirmTransaction 一起使用——不要用新获取的区块哈希替换它。 |
data.blockhash.lastValidBlockHeight | number | 区块哈希过期后的槽高度。 |
API 为每个被认领的 bucket 返回一个交易——通常是两个（联合曲线加 Raydium）。请按顺序提交；它们的顺序并不重要。
错误响应
错误以 HTTP 状态 400 返回，格式为：
{ "error": { "message": "No rewards available to claim" } }
已知错误消息
| 消息 | HTTP | 原因 |
|---|---|---|
No rewards available to claim | 400 | 钱包在任何 bucket 上都没有累积且未认领的创作者奖励。这是代替空 transactions 数组返回的，因此调用方必须将其作为非异常结果处理。 |
✖ Invalid wallet address | 400 | wallet 不是有效的 base58 Solana 公钥。 |
无奖励是 400，而非空数组
当钱包没有可认领内容时，端点返回 HTTP 400 和消息 No rewards available to claim——它不会返回带 transactions: [] 的 200。调用方必须捕获错误（或检查 response.status 和 body.error.message），并将此情况视为"无事可做"，而非失败。SDK 将其呈现为类型化的 GenesisApiError；请参阅错误处理。
注意事项
- 端点在 bucket 级别是幂等的——成功认领后立即再次调用，将返回
No rewards available to claim，直到累积新费用为止。 - 返回的交易使用
data.blockhash中的区块哈希。如果确认时间超过 ~60–90 秒，区块哈希将过期，必须重新调用以获取一组新的交易。 - 创作者奖励在每次兑换（联合曲线）和 LP 交易活动（Raydium CPMM）中累积——此端点聚合两者。有关基础累积机制和按 bucket 的获取助手，请参阅 Genesis 联合曲线创作者费。
- 创作者费钱包在 bucket 创建时通过
creatorFeeWallet设置，曲线上线后无法更改。
推荐：使用 SDK
不要直接调用此端点，而是使用 @metaplex-foundation/genesis 中的 claimCreatorRewards：
claimCreatorRewards.ts
1import { claimCreatorRewards } from '@metaplex-foundation/genesis'
2import { base58 } from '@metaplex-foundation/umi/serializers'
3import { createUmi } from '@metaplex-foundation/umi-bundle-defaults'
4import { keypairIdentity } from '@metaplex-foundation/umi'
5
6const umi = createUmi('https://api.mainnet-beta.solana.com')
7const keypair = umi.eddsa.createKeypairFromSecretKey(mySecretKeyBytes)
8umi.use(keypairIdentity(keypair))
9
10const result = await claimCreatorRewards(umi, {}, {
11 wallet: umi.identity.publicKey,
12 network: 'solana-mainnet',
13 // payer is optional — defaults to `wallet` on the server.
14 // Set it to have a different wallet cover rent and transaction fees.
15 // payer: umi.identity.publicKey,
16})
17
18for (const tx of result.transactions) {
19 const signed = await umi.identity.signTransaction(tx)
20 const signature = await umi.rpc.sendTransaction(signed, {
21 preflightCommitment: 'confirmed',
22 })
23 await umi.rpc.confirmTransaction(signature, {
24 strategy: { type: 'blockhash', ...result.blockhash },
25 commitment: 'confirmed',
26 })
27 console.log('Claimed:', base58.deserialize(signature)[0])
28}
29
30// Claimed: 5uGGYEMmjP2HpyFCvLPNpVDSQEBtUE3LR6ZQFqhJxQSh5FbKacSyN8nQmAJowuFs6BTCdwzoFyyJz8Y2hQx8kPxo
31// Claimed: 3TAroVovEap1ZEAJYq3WiDZoMK3GU3soCdrhvZJNg6b9EANqvWrVcDGNffm7mD8wvtpR7ynWQBcbrmz8AK6nrhfy