CashLink File Vending API

Overview

This v2 API lets sellers manage BCH receiving wallets, files, public covers, listings, and sales. Buyers can create payment orders and download files after entitlement is granted.

Base URL: https://test-linking.cc/api/v2/file-vending

Seller authentication

Sellers need either a verified email or a verified Paytaca wallet identity and must complete receiving-wallet setup. They then issue a cldev_ token with the file-vending:sell scope in Security settings. A seller without a verified email is paused after 14 days without an interactive login until the next successful login; API-token activity does not extend this deadline. Tokens last at most 90 days, are shown once, and are stored only as HMACs. Upload and mutation requests require a 16–200 character Idempotency-Key.

Buyer payment

GET /listings/{file} publicly returns an active listing. POST /listings/{file}/purchase-orders requires an idempotency key and shows its clapi_ order token only when the order is first created. Use that bearer token for status, events, QR code, and download. An order UUID alone grants no authority; download stays unavailable until payment grants entitlement.

Sellers may set price_currency to sat with an integer base_price_satoshis, or to usd with an exact two-decimal base_price_usd string. USD listings are paid only in BCH. A new order obtains a fresh multi-source quote on the server, rounds the converted satoshi amount up, and stores the original USD price, rate, participating sources, and quote time as an immutable order snapshot. Clients cannot submit a rate or BCH amount.

The per-listing limit is US$1 for a standard seller and US$100 for a currently blue-check verified creator who also has an eligible identity. SAT prices are classified from a fresh multi-source quote whenever a listing version is created; unavailable quotes return 503. USD prices are checked directly. Later exchange-rate movement does not suspend a snapshotted listing. Only a currently verified creator can create or modify explicit content. Ineligible, explicit, and over-limit writes return 422.

Safety and responses

Files and covers must pass the existing scanning pipeline before becoming public. Pending, blocked, failed, or removed covers are never returned by the public listing. JSON uses data, links, and meta.contract_version=2; errors use RFC 9457 Problem Details. Private responses are no-store, and cross-origin CORS is not enabled.

Main endpoints

• Seller: GET /wallets, GET|POST /files, GET|PATCH /files/{file}, cover management, and GET /sales.
• Buyer: GET /listings/{file}, payment-order creation, order status, events, QR code, and download.

Use the OpenAPI 3.1 document for authoritative fields, states, and limits.