---
title: "Follow an entity (live fills)"
method: POST
path: "/v1/account/subscriptions"
tags: ["Push"]
---

# Follow an entity (live fills)

`POST /v1/account/subscriptions`

## Request

- Base URL: `https://api.pmwallets.com`
- URL: `https://api.pmwallets.com/v1/account/subscriptions`
- Auth: API key in header `x-api-key`

Pushes the entity's fills to your WebSocket/webhook. Unlock its address first (402 address_not_unlocked). CHARGES 1 cent now for the first hour, then hourly until canceled (free within plan push slots). Spends 1 daily distinct-entity unit. Starts ~96 s (65 blocks) behind the head.

## Request body

- object
  - `entityId` string, required: A 12-character entity handle (Crockford base32, e.g. 7KQ2MF9X4B1C) or a full 0x address (40 hex).
  - `channels` string[]: Where to deliver. Default ["ws"].
  - `acceptInactive` boolean: Subscribe even if the entity has had no fill for 7 days (otherwise 409).

## Response `201`

Subscribed, first hour paid (HTTP 201). Hours with no feed are not charged; pauses when the balance runs out. At most 200 active.

- Subscription
  - `id` string
  - `userId` string
  - `chain` integer
  - `entityId` string: The 0x address once paid for and still held; a handle otherwise (never-charged or plan-locked rows).
  - `label` string
  - `channels` string[]
  - `status` 'active' | 'paused' | 'canceled'
  - `pausedReason` string, nullable: e.g. insufficient_balance, webhook_disabled, no_webhook, plan_ended, plan_limit, address_locked.
  - `fromBlock` integer: Fills strictly after this block are delivered.
  - `syncedBlock` integer
  - `tier` string
  - `priceCents` integer: Hourly price frozen on the subscription.
  - `billedThrough` string, date-time, nullable: Prepaid up to here.
  - `planCovered` boolean: The last billed hour was covered by a plan push slot (free).
  - `activations` integer
  - `createdAt` string, date-time
  - `canceledAt` string, date-time, nullable
  - `followedAt` string, date-time, nullable
  - `categories` object[]: List endpoint only.
    - `category` string
    - `share` number
  - `lastFillTs` string, nullable: List endpoint only.
  - `fills24h` integer, nullable: List endpoint only.

## Other responses

- `400`: Bad entityId/channels, or 200 active subscriptions already.
- `401`: No valid API key (missing, malformed, unknown or revoked).
- `402`: `error: address_not_unlocked` (unlock it first), or not enough balance for the first hour (priceCentsPerHour, balanceCents). Nothing charged.
- `403`: Daily distinct-entity limit reached.
- `404`: Entity is not in any published window.
- `409`: Dormant entity (resend with acceptInactive: true), already subscribed, a concurrent create, or the only channel is a missing/switched-off webhook. Nothing charged.
- `503`: Fill feed or chain head unavailable; nothing charged.

---

[API](https://skmtc.dev/pmwallets/apis/pmwallets-api.md) · [All operations](https://skmtc.dev/pmwallets/apis/pmwallets-api/llms.txt) · [OpenAPI document](https://skmtc.dev/pmwallets/apis/pmwallets-api/revisions/d5023fb40430?raw)