Register Reward Addresses

Reward addresses are the blockchain addresses you want monitored for rewards. Each address must be assigned to a payout group — the payout group associated to each address determines how rewards accrued by that address will be paid. Addresses begin accruing rewards once they are in ACTIVE status. There are no retroactive payouts, so submit addresses as early as possible.

If you previously registered reward addresses without a payout group (through the Monitoring Addresses API), you can find them by querying List Reward Addresses with payout_group_id set to the zero UUID (00000000-0000-0000-0000-000000000000). Use Update Reward Address to assign each one to a payout group.

Required scope: rewards:write_monitoring_address

Only submit addresses you are authorized to claim rewards for under your rewards agreement. Addresses already registered to another partner will be rejected.

Single address

Use Create a Reward Address for individual registrations:

Show Request

curl -X POST 'https://api.sandbox.paxos.com/v2/rewards/addresses' \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "address": {
      "address": "0xabc123...def456",
      "payout_group_id": "{payout_group_id}",
      "asset_type": "USDG",
      "name": "Treasury Wallet 1"
    }
  }'

Show Response

{
  "address": {
    "id": "{reward_address_id}",
    "address": "0xabc123...def456",
    "payout_group_id": "{payout_group_id}",
    "asset_type": "USDG",
    "name": "Treasury Wallet 1",
    "status": "UNREGISTERED",
    "created_at": "2024-01-15T10:00:00Z"
  }
}

Batch registration

Use Batch Create Reward Addresses to register up to 1,000 addresses in a single request:

Show Request

curl -X POST 'https://api.sandbox.paxos.com/v2/rewards/addresses/batch' \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "addresses": [
      {
        "address": "0xabc123...def456",
        "payout_group_id": "{payout_group_id}",
        "asset_type": "USDG",
        "name": "Treasury Wallet 1"
      },
      {
        "address": "0x999eee...777fff",
        "payout_group_id": "{payout_group_id}",
        "asset_type": "USDG",
        "name": "Treasury Wallet 2"
      }
    ]
  }'

Show Response

{
  "successful_addresses": [
    {
      "id": "{reward_address_id_1}",
      "address": "0xabc123...def456",
      "payout_group_id": "{payout_group_id}",
      "status": "UNREGISTERED"
    },
    {
      "id": "{reward_address_id_2}",
      "address": "0x999eee...777fff",
      "payout_group_id": "{payout_group_id}",
      "status": "UNREGISTERED"
    }
  ],
  "failed_addresses": []
}

Any addresses that fail validation are returned in failed_addresses with an error description. Successfully created addresses are independent of failures — a partial success is possible.

Address status

Addresses begin with UNREGISTERED status and move to ACTIVE once validated against the network. Balances are not snapshotted until the address reaches ACTIVE status. The current status is returned as onchain_status on each address in the List Reward Addresses response.

Status	Description
`UNREGISTERED`	Submitted but not yet registered on-chain
`UNREGISTERED_INSUFFICIENT_BALANCE`	Registration skipped because the address does not meet the minimum balance required for rewards accrual. Automatically retried once the minimum balance is met.
`PENDING_REGISTRATION`	On-chain registration in progress
`ACTIVE`	Registered and accruing rewards
`FAILED_REGISTRATION`	Registration failed; contact support if this persists
`NEEDS_REREGISTRATION`	The address’s payout group was changed. The address may still be on-chain under the old group and is pending re-registration under the new one.
`PENDING_DELETION`	Removal from monitoring in progress
`FAILED_DELETION`	On-chain removal failed; contact support

Address verification confirms that you control a submitted address. Verification is not currently required to accrue rewards, but will be required in the near future. See the Address Verification guide to integrate before it becomes mandatory.

Next step

Monitor Reward Details

Check current rates, accruals, and available rewards

Get Started

Identity

Travel Rule

Stablecoin Orchestration

Fiat Transfers

Rewards Engine

Address Verification

Stablecoin Payments

Crypto Brokerage

Webhooks

Additional Guides

Versioning

Single address

Batch registration

Address status

Next step

Monitor Reward Details

​Single address

​Batch registration

​Address status

​Next step

Monitor Reward Details

Single address

Batch registration

Address status

Next step