Send rewards - Coinbase Developer Documentation

Send rewards

curl --request POST \
  --url https://payments.coinbase.com/api/v1/rewards/send \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --header 'x-idempotency-key: <x-idempotency-key>' \
  --data '
{
  "paymentOperationId": "<string>",
  "rewards": [
    {
      "campaignAddress": "<string>",
      "tokenAddress": "<string>",
      "chainId": 123
    }
  ],
  "metadata": {}
}
'

{
  "rewardOperations": [
    {
      "id": "<string>",
      "action": "REWARD_OPERATION_ACTION_ALLOCATE",
      "status": "REWARD_OPERATION_STATUS_PENDING",
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z",
      "reward": {
        "id": "<string>",
        "campaignAddress": "<string>",
        "paymentInfoHash": "<string>",
        "recipientAddress": "<string>",
        "tokenAddress": "<string>",
        "chainId": 123,
        "createdAt": "2023-11-07T05:31:56Z",
        "updatedAt": "2023-11-07T05:31:56Z"
      },
      "amount": "<string>",
      "transactionHash": "<string>",
      "error": "<string>",
      "errorCode": "<string>",
      "revertReason": "<string>",
      "blockNumber": "<string>",
      "metadata": {},
      "operationSteps": [
        {
          "entity": "<string>",
          "id": "<string>",
          "type": "OPERATION_STEP_TYPE_AUTH_ESCROW",
          "operationId": "<string>",
          "operationType": "OPERATION_TYPE_PAYMENT",
          "status": "OPERATION_STEP_STATUS_SUCCEEDED",
          "createdAt": "2023-11-07T05:31:56Z",
          "updatedAt": "2023-11-07T05:31:56Z",
          "params": {},
          "error": "<string>",
          "errorCode": "<string>",
          "transactions": [
            {
              "entity": "<string>",
              "transactionHash": "<string>",
              "blockNumber": "<string>",
              "createdAt": "2023-11-07T05:31:56Z",
              "updatedAt": "2023-11-07T05:31:56Z",
              "revertReason": "<string>",
              "operationStepId": "<string>"
            }
          ]
        }
      ]
    }
  ],
  "invalidRewardInputs": [
    {
      "rewardInput": {
        "campaignAddress": "<string>",
        "tokenAddress": "<string>",
        "chainId": 123
      },
      "invalidReason": "<string>"
    }
  ]
}

POST

api

rewards

send

Send rewards

curl --request POST \
  --url https://payments.coinbase.com/api/v1/rewards/send \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --header 'x-idempotency-key: <x-idempotency-key>' \
  --data '
{
  "paymentOperationId": "<string>",
  "rewards": [
    {
      "campaignAddress": "<string>",
      "tokenAddress": "<string>",
      "chainId": 123
    }
  ],
  "metadata": {}
}
'

{
  "rewardOperations": [
    {
      "id": "<string>",
      "action": "REWARD_OPERATION_ACTION_ALLOCATE",
      "status": "REWARD_OPERATION_STATUS_PENDING",
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z",
      "reward": {
        "id": "<string>",
        "campaignAddress": "<string>",
        "paymentInfoHash": "<string>",
        "recipientAddress": "<string>",
        "tokenAddress": "<string>",
        "chainId": 123,
        "createdAt": "2023-11-07T05:31:56Z",
        "updatedAt": "2023-11-07T05:31:56Z"
      },
      "amount": "<string>",
      "transactionHash": "<string>",
      "error": "<string>",
      "errorCode": "<string>",
      "revertReason": "<string>",
      "blockNumber": "<string>",
      "metadata": {},
      "operationSteps": [
        {
          "entity": "<string>",
          "id": "<string>",
          "type": "OPERATION_STEP_TYPE_AUTH_ESCROW",
          "operationId": "<string>",
          "operationType": "OPERATION_TYPE_PAYMENT",
          "status": "OPERATION_STEP_STATUS_SUCCEEDED",
          "createdAt": "2023-11-07T05:31:56Z",
          "updatedAt": "2023-11-07T05:31:56Z",
          "params": {},
          "error": "<string>",
          "errorCode": "<string>",
          "transactions": [
            {
              "entity": "<string>",
              "transactionHash": "<string>",
              "blockNumber": "<string>",
              "createdAt": "2023-11-07T05:31:56Z",
              "updatedAt": "2023-11-07T05:31:56Z",
              "revertReason": "<string>",
              "operationStepId": "<string>"
            }
          ]
        }
      ]
    }
  ],
  "invalidRewardInputs": [
    {
      "rewardInput": {
        "campaignAddress": "<string>",
        "tokenAddress": "<string>",
        "chainId": 123
      },
      "invalidReason": "<string>"
    }
  ]
}

Authorizations

Authorization

string

header

required

Authorization header using the Bearer scheme. Learn more about JWT tokens in the Coinbase Developer Portal.

Headers

x-idempotency-key

string

required

Unique identifier to ensure request idempotency

Body

application/json

Request payload for sending rewards.

paymentOperationId

string

required

The ID of the payment operation to associate rewards with.

rewards

RewardInput · object[]

required

List of rewards to process.

Show child attributes

rewards.campaignAddress

string

required

The onchain address of the campaign

rewards.tokenAddress

string

required

The token address for the rewards

rewards.chainId

integer<int32>

required

The chain ID where the campaign is deployed

metadata

Metadata · object

Metadata for the reward operations that will be returned in the webhook.

Response

A successful response.

Response payload for sending rewards.

rewardOperations

RewardOperation · object[]

List of successful reward operations with detailed information.

Show child attributes

rewardOperations.id

string

required

Unique identifier for the reward operation.

rewardOperations.action

enum<string>

required

Type of reward operation (e.g., REWARD_OPERATION_ACTION_DISTRIBUTE).

Available options:

REWARD_OPERATION_ACTION_ALLOCATE,

REWARD_OPERATION_ACTION_DEALLOCATE,

REWARD_OPERATION_ACTION_DISTRIBUTE,

REWARD_OPERATION_ACTION_SEND

rewardOperations.status

enum<string>

required

Current status of the reward operation.

Available options:

REWARD_OPERATION_STATUS_PENDING,

REWARD_OPERATION_STATUS_SUCCEEDED,

REWARD_OPERATION_STATUS_FAILED

rewardOperations.createdAt

string<date-time>

required

Timestamp when the reward operation was created.

rewardOperations.updatedAt

string<date-time>

required

Timestamp when the reward operation was last updated.

rewardOperations.reward

Reward · object

Detailed reward object associated with this operation.

Show child attributes

rewardOperations.reward.id

string

required

Unique identifier for the reward.

rewardOperations.reward.campaignAddress

string

required

Onchain address of the campaign contract.

rewardOperations.reward.paymentInfoHash

string

required

Hash of the payment info that this reward is associated with.

rewardOperations.reward.recipientAddress

string

required

Blockchain address that will receive the reward.

rewardOperations.reward.tokenAddress

string

required

Address of the token contract used for the reward.

rewardOperations.reward.chainId

integer<int32>

required

The blockchain network identifier where the reward is processed.

rewardOperations.reward.createdAt

string<date-time>

required

Timestamp when the reward was created.

rewardOperations.reward.updatedAt

string<date-time>

required

Timestamp when the reward was last updated.

rewardOperations.amount

string

Amount involved in this reward operation.

rewardOperations.transactionHash

string

Blockchain transaction hash for this reward operation.

rewardOperations.error

string

Error message if the reward operation failed.

rewardOperations.errorCode

string

Error code of the reward operation.

rewardOperations.revertReason

string

Blockchain revert reason of the reward operation.

rewardOperations.blockNumber

string<int64>

Block number of the reward operation.

rewardOperations.metadata

Metadata · object

Additional metadata as a free-form object.

rewardOperations.operationSteps

OperationStep · object[]

List of operation steps associated with this reward operation.

Show child attributes

rewardOperations.operationSteps.entity

string

required

Entity type, usually 'operation-step'.

rewardOperations.operationSteps.id

string

required

Unique identifier of the operation step.

rewardOperations.operationSteps.type

enum<string>

required

Type of the operation step (e.g., AUTH_ESCROW, CROSSCHAIN, FLYWHEEL).

Available options:

OPERATION_STEP_TYPE_AUTH_ESCROW,

OPERATION_STEP_TYPE_CROSSCHAIN,

OPERATION_STEP_TYPE_FLYWHEEL

rewardOperations.operationSteps.operationId

string

required

Identifier of the parent operation.

rewardOperations.operationSteps.operationType

enum<string>

required

Type of the parent operation (e.g., PAYMENT, REWARD).

Available options:

OPERATION_TYPE_PAYMENT,

OPERATION_TYPE_REWARD

rewardOperations.operationSteps.status

enum<string>

required

Current status of the operation step.

Available options:

OPERATION_STEP_STATUS_SUCCEEDED,

OPERATION_STEP_STATUS_FAILED,

OPERATION_STEP_STATUS_PENDING

rewardOperations.operationSteps.createdAt

string<date-time>

required

Timestamp when the operation step was created.

rewardOperations.operationSteps.updatedAt

string<date-time>

required

Timestamp when the operation step was last updated.

rewardOperations.operationSteps.params

Params · object

Parameters for the operation step as a free-form object.

rewardOperations.operationSteps.error

string

Error message if the operation step failed.

rewardOperations.operationSteps.errorCode

string

Error code if the operation step failed.

rewardOperations.operationSteps.transactions

Transaction · object[]

Blockchain transactions associated with this operation step.

Show child attributes

rewardOperations.operationSteps.transactions.entity

string

required

Entity type, usually 'transaction'.

rewardOperations.operationSteps.transactions.transactionHash

string

required

Blockchain transaction hash.

rewardOperations.operationSteps.transactions.blockNumber

string<int64>

required

Block number where the transaction was included.

rewardOperations.operationSteps.transactions.createdAt

string<date-time>

required

Timestamp when the transaction record was created.

rewardOperations.operationSteps.transactions.updatedAt

string<date-time>

required

Timestamp when the transaction record was last updated.

rewardOperations.operationSteps.transactions.revertReason

string

Revert reason if the transaction failed.

rewardOperations.operationSteps.transactions.operationStepId

string

Identifier of the operation step this transaction belongs to.

invalidRewardInputs

InvalidRewardInput · object[]

List of reward inputs that were invalid/unable to be processed with detailed reasoning.

Show child attributes

invalidRewardInputs.rewardInput

Reward Input · object

The reward input that was invalid

Show child attributes

invalidRewardInputs.rewardInput.campaignAddress

string

required

The onchain address of the campaign

invalidRewardInputs.rewardInput.tokenAddress

string

required

The token address for the rewards

invalidRewardInputs.rewardInput.chainId

integer<int32>

required

The chain ID where the campaign is deployed

invalidRewardInputs.invalidReason

string

Reason why this reward input is invalid

Deallocate rewards

Create webhook

⌘I

PAYMENT ACCEPTANCE

Authorizations

Headers

Body

Response