# ipfs.family API > Drop a file, get its CID, keep it pinned on IPFS. Pay once per gigabyte per month on Robinhood Chain (chain 4663) with a plain > transfer; the payment tx is the on-chain receipt. Base URL: https://api.ipfs.family. Gateway: https://gw.ipfs.family/ipfs/. Open CORS. JSON. Pricing: $0.04 per GB per month, paid up front, $0.01 minimum per order. First 100 MB free per wallet (one signature, no gas; free pins keep up to 12 months and renew free). Hold $15 of $IPFS and 10 GB are free ($IPFS is not launched yet). Pay in ETH, USDG or any Robinhood Chain token with a live price (stock tokens too). Unpin and the unused paid time comes back as credit. Pins past their date stay 3 days, then the node lets them go. Where files live: our IPFS node (Kubo) on our server, announced to the public IPFS network, so any gateway can fetch them while pinned. Payment wallet: 0x9432509A97431e732d0Fa960eb3B1495420Ac681. No storage contract: an order's tx is a transfer to this wallet with the order tag in the calldata (ETH: data = tag; tokens: transfer(wallet, amount) + tag appended). Send pay.{to, value, data} exactly as returned. ## Pin a file (wallet or agent) 1. Hash it yourself if you like (CIDv1, raw leaves, 256 KiB chunks: what `ipfs add --cid-version 1` makes). 2. POST /orders {items:[{name, bytes, cid}], months: 12, token: "USDG"} signed (action "pin.order") or with an API key. 3. PUT /orders//files/ with the raw bytes for each file (uploadsLeft counts down). 4. If dueUsd > 0: send order.pay (a plain transfer) from any wallet; POST /orders//pay {tx} or wait ~15 s. 5. Pinned: GET /pins/, open https://gw.ipfs.family/ipfs/. Renew with POST /pins/renew, stop with POST /pins/unpin. Links: items [{url}] are fetched by our node. Existing CIDs: POST /psa/pins (or MCP pin_cid), paid from free allowance or credit. `ipfs pin remote service add ipfsfamily https://api.ipfs.family/psa ipfs_sk_...` then `ipfs pin remote add --service=ipfsfamily `. ## Private files IPFS is public: anyone with the CID can fetch the bytes. The site encrypts private files in the browser first (AES-GCM, key from a wallet signature), so the CID is of the ciphertext. Over the API, encrypt before you upload. private: true also hides the name from lists. ## Signing Signed actions: body {owner, ts, sig, ...args}. sig = personal_sign of "ipfs.family\n\n\nts:" canonical = JSON with object keys sorted recursively, arrays in order, undefined dropped. ts = Date.now() in ms, valid 10 minutes, each signature works once. Agents: POST /keys once (signed), then Authorization: Bearer ipfs_sk_... instead of signing. Private reads (your private names, keys): ?owner=&ts=&sig= signing action "read" with args {} (reusable for 10 minutes). ## Endpoints - GET /health: ok, database, ipfs node (peer id, peers), latest block, worker heartbeat age - GET /config: chain, the payment wallet, pricing (per GB a month, minimum, free tier, holder tier), limits, gateway, MCP - GET /stats: files pinned, distinct CIDs, bytes stored, floppies worth, wallets, payments, USD paid, opens in 7 days, node peers - GET /quote: price for bytes kept for months: ?bytes=&months=&token=&owner= (owner applies your free 100 MB and credit) -> {usd, dueUsd, tier, pay:{sym, amount}} - GET /tokens: coins you can pay with, live USD prices: ETH, USDG, stock tokens and more. ?q= name, ticker or a 0x address - POST /orders: start a pin: {items:[{name, bytes, cid, mime?, dir?, private?, listed?} | {url}], months, token}. Free inside your allowance (smallest files first), else returns pay:{to, value, data} to send as is. Then upload each file (PUT /orders/{id}/files/{pin}). A link item is fetched by our node right away (up to 250 MB). A CID already on our node needs no upload. Action "pin.order". signed: body {owner, ts, sig, ...args}, or Authorization: Bearer ipfs_sk_... - PUT /orders/{id}/files/{pin}: the raw bytes of one file (body = the file, Content-Length = its declared bytes, up to 2 GB). Our node hashes it with the same settings as the site (CIDv1, raw leaves, 256 KiB chunks), so the CID matches the one you saw. The order id is the capability: no signature needed - GET /orders/{id}: an order: status (open, done, expired), uploadsLeft, paid, pay (the tx to send while due), payTx (the receipt) and its pins - POST /orders/{id}/pay: {tx}: point the API at your payment tx (the worker also finds it on its own within ~15 s). Returns {state: paid | partial | credited | pending} - POST /orders/{id}/quote: {token?}: a fresh price and tx for what is still due (price moved, or pay with another coin). Action "order.quote". signed: body {owner, ts, sig, ...args}, or Authorization: Bearer ipfs_sk_... - GET /pins: public files people chose to share: ?sort=new|big|opens ?kind= ?q= (name, wallet or CID) ?owner= ?limit= ?offset=. Also kinds and top pinners this week - GET /pins/{cid}: one CID: file (name, size, kind), keepers, paid until, every pin row, receipts (payment txs), opens by day, gateway links. Private names show only to their owner (?owner=&ts=&sig=, action "read") - GET /pins/{cid}/dag: the root block's links: the 256 KiB blocks (or files of a folder) under a pinned CID, first 64, with their CIDs and sizes - POST /pins/renew: {cid | cids, months, token}: keep pins longer. Free-tier pins renew free up to 12 months ahead; paid pins cost the same rate. Returns an order (paid from credit first). Action "pin.renew". signed: body {owner, ts, sig, ...args}, or Authorization: Bearer ipfs_sk_... - POST /pins/unpin: {cid | cids}: stop keeping it. Our node drops it when nobody else pins it. Unused paid time comes back as credit. Action "pin.unpin". signed: body {owner, ts, sig, ...args}, or Authorization: Bearer ipfs_sk_... - POST /credit: {usd, token}: top up your credit (0.5 to 1000 USD); returns an order with the tx to send. Credit pays orders, renewals and PSA pins first. Action "credit.topup". signed: body {owner, ts, sig, ...args}, or Authorization: Bearer ipfs_sk_... - GET /vault/{address}: a wallet: files, ends soon, usage (stored, free allowance used and left, credit, holder), payments, open orders. Private names and API keys only for the owner (?owner=&ts=&sig=, action "read", or an API key) - GET /activity: latest pins and renewals (private files without names): ?limit= - GET /contracts: on-chain addresses: the payment wallet (and $IPFS once live), what each does and cannot do - POST /keys: a new API key for your wallet (shown once): {label}. Action "key.create". signed: body {owner, ts, sig, ...args} - GET /psa/pins: IPFS Pinning Service API (Bearer ipfs_sk_...): list your remote pins. ?cid= ?name= ?match= ?status=queued,pinning,pinned,failed ?before= ?after= ?limit= - POST /psa/pins: Pinning Service API: {cid, name?, origins?, meta?: {months}}. Our node fetches it from IPFS, then it is paid from your free allowance or credit (else failed with the amount needed) - GET /psa/pins/{requestid}: Pinning Service API: one pin request - POST /psa/pins/{requestid}: Pinning Service API: replace a pin request - DELETE /psa/pins/{requestid}: Pinning Service API: remove a pin - GET /events: SSE: pinned, renewed, unpinned, payment, order. ?types=pinned,payment - GET /mcp: MCP server info + config snippet - POST /mcp: MCP over streamable HTTP (JSON-RPC). Tools: get_quote, pin_url, pin_cid, get_order, submit_payment, get_pin, list_my_pins, list_public_pins, renew_pin, unpin, top_up, list_tokens, get_stats, list_contracts - GET /llms.txt: this file - GET /openapi.json: OpenAPI 3.1 ## MCP URL https://api.ipfs.family/mcp (streamable HTTP, JSON). Header Authorization: Bearer ipfs_sk_... for the acting tools. - get_quote: Price to keep bytes pinned for months: $0.04 per GB a month, $0.01 minimum, first 100 MB free per wallet. Returns USD and the amount in the coin you pick. - pin_url: Pin a public file by link: our node fetches it (up to 250 MB), hashes it and pins it. Free inside your 100 MB, else returns the payment tx to send (or pays from credit). Needs an API key. - pin_cid: Pin a CID that already exists on IPFS (Pinning Service API queue): our node fetches it from the network, then it is paid from your free allowance or credit. Needs an API key. - get_order: An order: status, what is left to upload, the payment tx to send, the receipt tx once paid. - submit_payment: Tell the API about your payment tx for an order (the worker also finds it on its own within ~15 s). - get_pin: Everything about one CID: name, size, who keeps it until when, receipts (payment txs), gateway links, opens. - list_my_pins: Your files: CIDs, sizes, kept-until dates, free allowance left, credit. Needs an API key. - list_public_pins: Public files people chose to share: sort new|big|opens, kind (img, pdf, data, site, vid, aud, bin), q. - renew_pin: Keep a pin longer. Free-tier pins renew free up to 12 months ahead; paid pins cost the same rate. Returns the order (and payment tx if any is due). Needs an API key. - unpin: Stop keeping a CID. Unused paid time comes back as credit. Needs an API key. - top_up: Add credit to your wallet (pay once, then pin from credit through the API, MCP or `ipfs pin remote`). Returns the payment tx. Needs an API key. - list_tokens: Coins you can pay with, live USD prices (ETH, USDG, stock tokens...). q filters; a 0x address looks one up. - get_stats: Files pinned, bytes stored, wallets, payments, node peers. - list_contracts: On-chain addresses ipfs.family uses (the payment wallet, $IPFS once live) with what each can and cannot do. ## Links Site https://ipfs.family . X https://x.com/ipfs_family . Explorer https://robinhoodchain.blockscout.com/address/0x9432509A97431e732d0Fa960eb3B1495420Ac681 .