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

# Payee Destinations

> Register and manage receiving routes using ERC-7828 interop addresses

## Overview

Payee destinations define where payments are received. Each destination encodes a wallet address, chain, and token into a single **ERC-7828 interop address**, creating a unique receiving route.

Destinations are used by:

* **Secure payments** — to resolve the payee, chain, and token from a `destinationId`
* **Client IDs** — to bind a receiving route to a client ID for orchestrator flows

## ERC-7828 Address Format

A destination ID combines the interop address with the token address:

```
{walletAddress}@eip155:{chainId}#{checksum}:{tokenAddress}
```

**Example:**

```
0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7@eip155:8453#ABCD1234:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
```

This encodes:

* **Wallet:** `0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7`
* **Chain:** Base (chainId `8453`)
* **Checksum:** `ABCD1234` (auto-generated by the API for address verification)
* **Token:** USDC (`0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`)

<Info>
  The checksum portion (`#ABCD1234`) is generated automatically by the API when you create a destination. You do not need to compute it yourself.
</Info>

## How It Works

<Steps>
  <Step title="Authenticate with wallet">
    Destinations require a SIWE wallet session. See [Wallet Authentication](/api-reference/wallet-authentication) for the challenge/verify flow.
  </Step>

  <Step title="Create a destination">
    Call `POST /v1/payee-destination` with the token address and chain ID. The API generates the full destination ID with interop address. EVM and Tron destinations use the same endpoint and shape — only the address format and chain ID differ.

    <Tabs>
      <Tab title="EVM (USDC on Base)">
        ```bash theme={null}
        curl -X POST "https://auth.request.network/v1/payee-destination" \
          -H "Cookie: session=YOUR_SESSION_TOKEN" \
          -H "Content-Type: application/json" \
          -d '{
            "tokenAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
            "chainId": 8453
          }'
        ```
      </Tab>

      <Tab title="Tron (USDT-TRC20)">
        ```bash theme={null}
        curl -X POST "https://auth.request.network/v1/payee-destination" \
          -H "Cookie: session=YOUR_SESSION_TOKEN" \
          -H "Content-Type: application/json" \
          -d '{
            "tokenAddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
            "chainId": 728126428
          }'
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Use the destination ID">
    The returned `destinationId` can be used in:

    * `POST /v2/secure-payments` — as `requests[].destinationId`
    * Client ID creation — as `payeeDestinationId` to bind the receiving route
  </Step>
</Steps>

## Endpoints

All endpoints require a SIWE wallet session (httpOnly cookie).

### POST /v1/payee-destination

Create a new payee destination or reactivate an existing one.

<ParamField body="tokenAddress" type="string" required>
  ERC20 token contract address (EVM `0x...` or Tron `T...` format).
</ParamField>

<ParamField body="chainId" type="number" required>
  Chain ID for the receiving network (e.g., `8453` for Base, `1` for Ethereum).
</ParamField>

<ParamField body="accessPolicy" type="object">
  Optional KYT (Know Your Transaction) compliance policy applied to payments into this destination. When set, every payer wallet that connects to a payment link backed by this destination is screened before the payment can proceed. See [Compliance-gated payments](/use-cases/compliance-gated-payments) for the full guide.

  <Expandable title="accessPolicy fields">
    <ParamField body="mode" type="&#x22;off&#x22; | &#x22;kyt_all_wallets&#x22;">
      `off` (default): no screening. `kyt_all_wallets`: every payer wallet is screened.
    </ParamField>

    <ParamField body="screeningProvider" type="&#x22;hypernative&#x22; | &#x22;merklescience&#x22;">
      KYT provider used for screening. Required when `mode` is `kyt_all_wallets` (must be omitted or `null` when `mode` is `off`). `merklescience` (Merkle Science) is available where enabled for your account.
    </ParamField>

    <ParamField body="hideUntilApproved" type="boolean">
      When `true`, payment metadata is hidden in the payer UI until the wallet passes screening.
    </ParamField>

    <ParamField body="hidePayeeAddress" type="boolean">
      When `true`, the payee address is masked in the payer UI (no copy / no explorer link).
    </ParamField>
  </Expandable>
</ParamField>

```json Response (201) theme={null}
{
  "id": "01HXEXAMPLE123",
  "destinationId": "0x6923...C7D7@eip155:8453#ABCD1234:0x8335...2913",
  "walletAddress": "0x6923831ACf5c327260D7ac7C9DfF5b1c3cB3C7D7",
  "tokenAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "chainId": 8453,
  "accessPolicy": {
    "mode": "kyt_all_wallets",
    "screeningProvider": "hypernative",
    "hideUntilApproved": true,
    "hidePayeeAddress": true
  },
  "binaryInteropAddress": "0x...",
  "humanReadableInteropAddress": "0x6923...C7D7@eip155:8453#ABCD1234",
  "claimed": true,
  "active": true,
  "createdAt": "2026-03-15T10:00:00.000Z"
}
```

### PUT /v1/payee-destination

Update the token address and/or chain on the active destination.

<ParamField body="tokenAddress" type="string" required>
  New ERC20 token contract address.
</ParamField>

<ParamField body="chainId" type="number" required>
  New chain ID.
</ParamField>

Returns the updated destination object (same format as POST response).

### GET /v1/payee-destination

Returns the active payee destination for the authenticated wallet, or `null` if none exists.

### GET /v1/payee-destination/payout-lookup

Retrieve the active destination preference for a payout **recipient** wallet. Returns only the routing fields needed to prefill payout creation, or `null` if the recipient has no active destination.

Like the other endpoints on this page, this requires a SIWE wallet session (httpOnly cookie). Unlike the other endpoints, the `walletAddress` query parameter is the *recipient* you are looking up — not the authenticated caller — so a payout initiator can resolve where a recipient wants to be paid.

<ParamField query="walletAddress" type="string" required>
  Recipient wallet address to check for an active destination (Ethereum or Tron format).
</ParamField>

```json Response (200) theme={null}
{
  "destinationId": "0x742d...8f44e@eip155:1#4CA88C9C:0xa0b8...6eb48",
  "walletAddress": "0x742d35cc6634c0532925a3b844bc454e4438f44e",
  "tokenAddress": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
  "chainId": 1,
  "claimed": true
}
```

### GET /v1/payee-destination/lookup

Lookup a destination by its composite ID.

<ParamField query="destinationId" type="string" required>
  The full destination ID in ERC-7828 format.
</ParamField>

### PATCH /v1/payee-destination/deactivate

Deactivate the current destination.

<ParamField body="destinationId" type="string" required>
  The destination ID to deactivate.
</ParamField>

```json Response (200) theme={null}
{
  "success": true,
  "message": "Destination deactivated"
}
```

## Related Pages

<CardGroup cols={2}>
  <Card title="Client ID Management" icon="key" href="/api-features/client-id-management">
    Bind destinations to client IDs for orchestrator flows.
  </Card>

  <Card title="Secure Payments API" icon="lock" href="/api-reference/secure-payments">
    Use destination IDs when creating secure payments.
  </Card>
</CardGroup>