---
title: "Earn incentive claim"
method: POST
path: "/v1/wallets/{wallet_id}/earn/ethereum/incentive/claim"
tags: ["Wallet Actions"]
---

# Earn incentive claim

`POST /v1/wallets/{wallet_id}/earn/ethereum/incentive/claim`

## Request

- Base URL: `https://api.privy.io`
- URL: `https://api.privy.io/v1/wallets/{wallet_id}/earn/ethereum/incentive/claim`
- Auth: HTTP basic

Claim incentive rewards for a wallet.

## Path parameters

- `wallet_id` string, required: ID of the wallet.

## Headers

- `privy-app-id` string, required: ID of your Privy app.
- `privy-authorization-signature` string: Request authorization signature. If multiple signatures are required, they should be comma separated.
- `privy-request-expiry` string: Request expiry. Value is a Unix timestamp in milliseconds representing the deadline by which the request must be processed.
- `privy-idempotency-key` string: Idempotency keys ensure API requests are executed only once within a 24-hour window.

## Request body

- EarnIncentiveClaimRequestBody: Input for claiming incentive rewards.
  - `nonce` string: Unique caller-generated nonce used to prevent replaying a signed wallet action request. Must be at least 24 characters (e.g. a cuid2 or UUID).
  - `chain` string, required: The blockchain network on which to perform the incentive claim. Supported chains include: 'tempo', 'ethereum', 'base', 'arbitrum', 'polygon', 'solana', and more, along with their respective testnets.
  - `reference_id` string: Developer-provided identifier for this request. Must be unique per app.

## Response `200`

Earn incentive claim initiated successfully.

- EarnIncentiveClaimActionResponse: Response for an earn incentive claim action.
  - `id` string, required: The ID of the wallet action.
  - `status` 'pending' | 'succeeded' | 'rejected' | 'failed', required: The current status of the wallet action.
  - `wallet_id` string, required: The ID of the wallet involved in the action.
  - `created_at` string, date-time, required: ISO 8601 timestamp of when the wallet action was created.
  - `reference_id` string, nullable: Developer-provided reference ID, if one was included in the request.
  - `failure_reason` object: Top-level failure context for the wallet action. Present on rejected or failed actions when available.
    - `message` string, required: Human-readable failure message.
    - `details` unknown
  - `steps` WalletActionStep[]: The steps of the wallet action. Only returned if `?include=steps` is provided.
    - union: A step within a wallet action, representing a single onchain action.
      - object: A wallet action step consisting of an EVM transaction.
        - `type` 'evm_transaction', required
        - `failure_reason` FailureReason: A description of why a wallet action (or a step within a wallet action) failed.
          - `message` string, required: Human-readable failure message.
          - `details` unknown
        - `finalized` boolean: Whether this step has reached on-chain finality. Absent until finality is confirmed.
        - `gas_credits_charged` CurrencyAmount: A monetary value with its currency denomination.
          - `value` string, required: The monetary value as a string.
          - `currency` 'usd', required: Currency code
        - `gas_credits_charged_usd` string, nullable: Deprecated, use `gas_credits_charged` instead; gas credits charged in USD for this step, if sponsored, as a decimal string.
        - `status` 'preparing' | 'queued' | 'pending' | 'retrying' | 'confirmed' | 'rejected' | 'reverted' | 'replaced' | 'abandoned', required: EVM transaction status.
        - `caip2` string, required: CAIP-2 chain identifier of the transaction, containing the chain ID.
        - `transaction_hash` string, nullable, required: The transaction hash for this step. May change while the step status is non-terminal.
      - object: A wallet action step consisting of an EVM user operation.
        - `type` 'evm_user_operation', required
        - `failure_reason` FailureReason: A description of why a wallet action (or a step within a wallet action) failed.
          - `message` string, required: Human-readable failure message.
          - `details` unknown
        - `finalized` boolean: Whether this step has reached on-chain finality. Absent until finality is confirmed.
        - `gas_credits_charged` CurrencyAmount: A monetary value with its currency denomination.
          - `value` string, required: The monetary value as a string.
          - `currency` 'usd', required: Currency code
        - `gas_credits_charged_usd` string, nullable: Deprecated, use `gas_credits_charged` instead; gas credits charged in USD for this step, if sponsored, as a decimal string.
        - `status` 'preparing' | 'queued' | 'pending' | 'retrying' | 'confirmed' | 'rejected' | 'reverted' | 'replaced' | 'abandoned', required: User operation status.
        - `user_operation_hash` string, nullable, required: The user operation hash for this step. May change while the step status is non-terminal.
        - `bundle_transaction_hash` string, nullable, required: Transaction hash of the bundle in which this user operation was included. Null until included by a bundler.
        - `caip2` string, required: CAIP-2 network identifier, containing the chain ID of the user operation.
        - `entrypoint_version` '0.6' | '0.7' | '0.8' | '0.9', required: The entrypoint version of the user operation.
      - object: A wallet action step consisting of an SVM (Solana) transaction.
        - `type` 'svm_transaction', required
        - `failure_reason` FailureReason: A description of why a wallet action (or a step within a wallet action) failed.
          - `message` string, required: Human-readable failure message.
          - `details` unknown
        - `finalized` boolean: Whether this step has reached on-chain finality. Absent until finality is confirmed.
        - `gas_credits_charged` CurrencyAmount: A monetary value with its currency denomination.
          - `value` string, required: The monetary value as a string.
          - `currency` 'usd', required: Currency code
        - `gas_credits_charged_usd` string, nullable: Deprecated, use `gas_credits_charged` instead; gas credits charged in USD for this step, if sponsored, as a decimal string.
        - `status` 'preparing' | 'queued' | 'pending' | 'confirmed' | 'rejected' | 'reverted' | 'failed', required: SVM transaction status.
        - `caip2` string, required: CAIP-2 chain identifier for the Solana network.
        - `transaction_signature` string, nullable, required: The Solana transaction signature (base58-encoded). Null until broadcast.
      - object: A wallet action step consisting of a TVM (Tron) transaction.
        - `type` 'tvm_transaction', required
        - `failure_reason` FailureReason: A description of why a wallet action (or a step within a wallet action) failed.
          - `message` string, required: Human-readable failure message.
          - `details` unknown
        - `gas_credits_charged` CurrencyAmount: A monetary value with its currency denomination.
          - `value` string, required: The monetary value as a string.
          - `currency` 'usd', required: Currency code
        - `gas_credits_charged_usd` string, nullable: Deprecated, use `gas_credits_charged` instead; gas credits charged in USD for this step, if sponsored, as a decimal string.
        - `status` 'preparing' | 'queued' | 'pending' | 'confirmed' | 'rejected' | 'reverted' | 'failed', required: TVM transaction status.
        - `caip2` string, required: CAIP-2 chain identifier for the Tron network.
        - `transaction_id` string, nullable, required: The Tron transaction ID. Null until broadcast.
      - object: A wallet action step representing a cross-chain/cross-asset fill by an external provider.
        - `type` 'external_transaction', required
        - `failure_reason` FailureReason: A description of why a wallet action (or a step within a wallet action) failed.
          - `message` string, required: Human-readable failure message.
          - `details` unknown
        - `status` 'preparing' | 'queued' | 'pending' | 'confirmed' | 'rejected' | 'failed', required: External transaction step status.
      - object: A wallet action step representing a transaction executed by a custodian (e.g. Bridge).
        - `type` 'custodian_transaction', required
        - `failure_reason` FailureReason: A description of why a wallet action (or a step within a wallet action) failed.
          - `message` string, required: Human-readable failure message.
          - `details` unknown
        - `status` 'preparing' | 'queued' | 'custodian_reviewing' | 'pending' | 'confirmed' | 'rejected' | 'failed', required: Custodian transaction step status.
        - `custodian` string, required: Identifier of the custodian executing this transaction (e.g. "bridge").
        - `transaction_hash` string, nullable, required: Identifier of the transaction the custodian last reported on the destination chain. Set on a settled transfer, and also on a failed one when the custodian had already broadcast a payout that was later returned. Null until the custodian reports one.
      - object: A wallet action step representing a Tempo Zone settlement on its parent chain.
        - `type` 'tempo_zone_settlement', required
        - `failure_reason` FailureReason: A description of why a wallet action (or a step within a wallet action) failed.
          - `message` string, required: Human-readable failure message.
          - `details` unknown
        - `caip2` string, nullable, required: CAIP-2 identifier of the Tempo parent chain, or null when unavailable.
        - `transaction_hash` string, required: A hex-encoded string prefixed with '0x', capped at 300002 characters (150,000 bytes).
        - `status` 'preparing' | 'queued' | 'pending' | 'confirmed' | 'rejected' | 'failed', required: Tempo Zone settlement step status.
  - `type` 'earn_incentive_claim', required
  - `chain` string, required: EVM chain name (e.g. "tempo", "base").
  - `rewards` EarnIncetiveClaimRewardEntry[], nullable, required: Claimed reward tokens. Populated after the preparation step fetches from Merkl.
    - `token_address` string, required: Address of the reward token.
    - `token_symbol` string, required: Symbol of the reward token (e.g. "MORPHO").
    - `token_decimals` integer: Number of decimal places for the reward token.
    - `amount` string, required: Claimable amount in base units.

## Changes

- **2026-10-20** `527110c2c2f4`: 4 breaking, 8 info
  - the response property `steps/items/oneOf[subschema #1: EVMTransactionWalletActionStep]/gas_credits_charged_usd` became nullable for the status `200`
  - the response property `steps/items/oneOf[subschema #2: EVMUserOperationWalletActionStep]/gas_credits_charged_usd` became nullable for the status `200`
  - the response property `steps/items/oneOf[subschema #3: SVMTransactionWalletActionStep]/gas_credits_charged_usd` became nullable for the status `200`
  - the response property `steps/items/oneOf[subschema #4: TVMTransactionWalletActionStep]/gas_credits_charged_usd` became nullable for the status `200`
  - …8 more
- **2026-10-19** `a77e516e7c57`: 1 info
  - added the optional property `steps/items/oneOf[subschema #4: TVMTransactionWalletActionStep]/gas_credits_charged_usd` to the response with the `200` status
- **2026-10-16** `4facbfa7f9d4`: 1 breaking, 6 info
  - added `#/components/schemas/TempoZoneSettlementWalletActionStep` to the `steps/items/` response property `oneOf` list for the response status `200`
  - added the new optional request property `nonce`
  - added the new optional request property `reference_id`
  - added the optional property `reference_id` to the response with the `200` status
  - …3 more
- …earlier changes not shown

[Operation history](https://skmtc.dev/privy-io/apis/privy-api/changes/v1/wallets/:wallet_id/earn/ethereum/incentive/claim/post.md)

---

[API](https://skmtc.dev/privy-io/apis/privy-api.md) - [All operations](https://skmtc.dev/privy-io/apis/privy-api/llms.txt) - [OpenAPI document](https://skmtc.dev/privy-io/apis/privy-api/revisions/3a2288470053?raw)