> For the complete documentation index, see [llms.txt](https://pingpay.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://pingpay.gitbook.io/docs/pingpay-api/subscriptions/near-intents-setup.md).

# Near Intents Setup

Ping Subscriptions uses the NEAR intents protocol (`intents.near` contract) to execute recurring payments. Before you can receive subscription payments, your merchant wallet must be properly set up.

### Why This Matters

The `intents.near` contract on NEAR mainnet is the settlement layer for all Ping subscription payments. When a subscriber's payment is released, the signed intent is submitted to this contract, which transfers tokens from the subscriber to the merchant.

**If your merchant address has never interacted with `intents.near`, payment releases will fail.**

### Setup Steps

#### 1. Deposit Into `intents.near`

Your merchant NEAR address needs to have assets registered in the `intents.near` contract. The simplest way to do this:

1. Go to [near.com/](https://near.com/) (a DEX built on NEAR intents)
2. Connect your merchant NEAR wallet
3. Deposit a small amount of USDC (even 0.01 USDC works) into your intents balance
4. You can withdraw it immediately after — the important thing is that your address now has a record in the contract

#### 2. Verify Your Setup

After depositing, verify your address has a balance entry:

```bash
# Check your intents.near balance (replace with your NEAR account)
curl -s -X POST https://rpc.mainnet.fastnear.com \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "query",
    "params": {
      "request_type": "call_function",
      "finality": "final",
      "account_id": "intents.near",
      "method_name": "get_balances",
      "args_base64": "'$(echo -n '{"account_id":"YOUR_ACCOUNT.near"}' | base64)'"
    }
  }' | python3 -m json.tool
```

#### 3. Configure Your Payout Address in Ping

Make sure your Ping merchant account has your NEAR address set as the payout address. This is the address that will receive subscription payments.

### Troubleshooting

| Problem                           | Cause                                             | Fix                                                |
| --------------------------------- | ------------------------------------------------- | -------------------------------------------------- |
| Payments fail with no error       | Merchant address not registered in `intents.near` | Deposit any amount into intents.near via Defuse    |
| `payment.failed` webhook received | Subscriber may have insufficient USDC balance     | Subscriber needs to top up their NEAR USDC balance |
| Intent expired                    | Subscriber signed intents too long ago            | Create a new subscription session                  |

### Token Reference

| Asset | NEAR Token Contract ID                                                    |
| ----- | ------------------------------------------------------------------------- |
| USDC  | `nep141:17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1` |

> **V1 Note:** Only USDC on NEAR is supported. More assets and chains coming soon.