Skill LienFi

LienFi est un marché pour les certificats de privilège fiscal américain tokenisés et les actes fiscaux remboursables, réglés on-chain en USDC sur Base (chain id 8453). Ce skill vous apprend à explorer le carnet, vous faire autoriser par votre opérateur, et acheter depuis le portefeuille que vous contrôlez.

Trois faits avant toute chose :

LienFi ne détient jamais votre clé et ne soumet jamais de transaction pour vous. Il signe le devis ; vous signez une reconnaissance et soumettez les transactions qu'il vous remet.
Les achats sont définitifs. Un privilège que vous achetez appartient à votre opérateur. La sortie se fait par remboursement du propriétaire ou relisting — il n'y a pas d'annulation.
Une seule étape humaine existe, et elle ne peut pas être contournée ou réessayée. Votre opérateur signe une autorisation dans un navigateur sur https://app.lienfi.com/agents/authorize et vous remet ce que la page affiche. Quand un tool répond not_registered avec un handoff_url — et votre appel portait le bearer — affichez le lien à votre opérateur et ARRÊTEZ.

Prérequis

Votre portefeuille

Deux façons de détenir un portefeuille Bankr, et chaque étape ci-dessous fonctionne dans les deux cas :

Vous êtes l'agent de Bankr lui-même (le terminal, X ou Telegram). Il n'y a rien à créer : vous signez des données typées et soumettez des transactions avec vos propres outils de portefeuille. Vérifié 2026-09-08 — une preuve de clé et deux consentements ont été signés avec eth_signTypedData_v4 et enregistrés alors que la seule clé Wallet API du compte était révoquée. Partout où une étape montre un curl vers api.bankr.bot, faites la même chose avec votre outil de portefeuille à la place.
Vous fonctionnez ailleurs et détenez un portefeuille Bankr via la Wallet API (Claude Code, OpenClaw, un bot personnel). Créez une clé sur https://bankr.bot/api-keys et conservez-la comme BANKR_API_KEY. La clé DOIT avoir walletApiEnabled activé (c'est le défaut) ; readOnly DÉSACTIVÉ — il est ACTIVÉ par défaut, et une clé en lecture seule répond 403 à la signature et à la soumission ; et allowedRecipients VIDE — une liste non-vide bloque eth_signTypedData_v4 sur /wallet/sign et toute soumission brute sur /wallet/submit, et ce skill a besoin des deux. Utilisez allowedIps pour la restriction à la place.

Dans les deux cas, dans les paramètres de sécurité Bankr, laissez les appels de contrats arbitraires ACTIVÉS (c'est le défaut) ; désactivés, les soumissions brutes sont bloquées. Les limites par transaction et sur 24 heures de Bankr (défauts de 500 $ chacun, relus 2026-09-07) s'appliquent à toutes les surfaces et doivent couvrir ce qu'un achat mobilise : une approve et une buyNFT, chacune pour le total du privilège. Que les deux comptent contre la limite quotidienne n'est pas documenté, donc faites en sorte que votre opérateur la définisse à au moins deux fois le prix du privilège. Seul votre opérateur peut modifier cela, dans l'app web Bankr. Sur X, Bankr répond seulement aux membres de Bankr Club.

Financez le portefeuille avec USDC sur Base — et pas plus que ce que votre opérateur est disposé à engager, car LienFi enregistre mais n'applique pas le plafond cumulatif. Le gaz sur Base est sponsorisé pour les portefeuilles embarqués Bankr.

Votre adresse de portefeuille

Chez Bankr, c'est le portefeuille que votre portfolio affiche. Via la Wallet API :

curl -s https://api.bankr.bot/wallet/me -H "X-API-Key: $BANKR_API_KEY"

L'adresse qui détient les fonds est celle que votre opérateur doit nommer comme portefeuille d'agent. Donnez-la-lui exactement comme retournée. Vérifié 2026-09-07 : Bankr signe avec cette même adresse (voir « Vérifié et non vérifié » à la fin).

Endpoints

LienFi MCP — JSON-RPC 2.0 sur HTTP sans état, rien à installer, pas de session : POST https://api.lienfi.com/api/v1/mcp avec content-type: application/json. Chaque appel LienFi dans ce skill est un curl vers lui. Les outils de recherche ne prennent aucun header ; les outils de portefeuille et d'achat prennent Authorization: Bearer $LIENFI_BEARER.
Research REST, aucune credential — https://api.lienfi.com/api/public/liens/{id} (un privilège, plat, portant le taux NET par an) et https://api.lienfi.com/api/v1/liens?... (le carnet avec filtres).
Lisez avant votre premier appel — https://app.lienfi.com/llms.txt (les conventions monétaires), https://app.lienfi.com/docs/api#mcp-walkthrough (la boucle ci-dessous avec un corps de requête pour chaque étape), https://app.lienfi.com/docs/api#mcp-refusals (chaque code de refus avec ce qu'il faut faire). Faites confiance à tools/list plutôt qu'à n'importe quel document, y compris celui-ci.

Conservez le bearer de l'opérateur à partir du moment où vous l'avez, et envoyez-le à chaque appel de portefeuille et d'achat aussi longtemps que l'autorisation dure — $LIENFI_BEARER ci-dessous correspond à l'endroit où votre runtime garde une credential ; LienFi ne se soucie que de son arrivée. L'enregistrement n'ouvre pas de session : un appel ultérieur sans le header est répondu comme not_registered même si vous l'êtes. N'imprimez jamais le bearer et ne l'envoyez nulle part ailleurs que vers api.lienfi.com. (L'agent de Bankr l'a porté entre les sessions sans aide dans les tests le 2026-09-08 ; un agent dont la mémoire ne persiste pas les secrets le garde comme variable d'env.)

Règles monétaires qui ne sont pas devinables à partir des noms de champs

Chaque rendement que l'API LienFi retourne est brut. LienFi prélève une part du GAIN sur le prix d'achat quand un privilège est remboursé (actuellement 10 %, lisez le taux en direct depuis fee_config), jamais de la valeur de remboursement. Classez par net_apy, que search_liens calcule avec la même arithmétique que le site affiche.
Un acheteur paie listing_price. La plupart des listings (deal_type: par) sont au prix DE la valeur de remboursement en direct, donc le prix monte avec l'accrual et un remboursement le jour de l'achat retourne la base et aucun gain.
Les privilèges à moins de 30 jours de l'échéance ne portent pas de taux par an ; search_liens les retourne dans une liste maturing_soon séparée. Ne les annualisez pas vous-même.
redemptive_value, accrued_interest et listing_price sur une rangée brute sont des captures gelées ; lisez le bloc calculated, qui est recompilé en direct.
redemption_deadline est la date limite statutaire et est immuable on-chain. Ne la recomputez jamais.

Étape 1 — Recherche (aucune credential)

Listez ce que le serveur sert, puis filtrez :

MCP=https://api.lienfi.com/api/v1/mcp
curl -s -X POST $MCP -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

curl -s -X POST $MCP -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call",
       "params":{"name":"market_overview","arguments":{}}}'

curl -s -X POST $MCP -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call",
       "params":{"name":"search_liens","arguments":{"budget_usd": 2000, "states": "FL", "limit": 5}}}'

curl -s -X POST $MCP -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":4,"method":"tools/call",
       "params":{"name":"get_lien","arguments":{"lien_id": "<lien-uuid>"}}}'

Chaque résultat est un bloc de contenu texte dont le text est JSON. search_liens répond liens classés par net_apy, plus maturing_soon, dropped (ce qui n'a pas pu être noté, compté plutôt que caché), fee_config et apy_labels. Gardez le lien_id que vous voulez.

Étape 2 — Se faire autoriser (l'étape humaine)

D'abord, vérifiez si cette étape est déjà faite. Si vous tenez un bearer pour ce portefeuille depuis une conversation antérieure, allez à l'étape 5 : l'autorisation dure jusqu'à son expires_at, et une nouvelle conversation ne l'éteint pas. Si vous n'êtes pas sûr que le portefeuille est enregistré, demandez à LienFi, sans credential :

curl -s https://api.lienfi.com/api/v1/agents/<agent-wallet-address>

Il répond registered, expiresAt et revokedAt. registered: true alors que vous ne tenez pas de bearer signifie que le blob est perdu pour vous, et une deuxième autorisation ne REMPLACE pas la première : votre opérateur doit appuyer sur Revoke sur celle existante sur https://app.lienfi.com/agents/authorize avant de signer à nouveau, ou l'enregistrement est refusé (registration_refused, "already has a different active authorization"). Dites-le avant qu'ils ne signent, pas après le refus.

Ensuite dites à votre opérateur, en ces termes : allez sur https://app.lienfi.com/agents/authorize, entrez l'adresse du portefeuille d'agent de la section Votre adresse de portefeuille ci-dessus exactement, choisissez le maximum que l'agent peut dépenser sur un privilège, un total cumulatif, et une expiration d'au plus 90 jours, et signez. La page ouvre ensuite un handoff avec un bouton Copy the prompt ; demandez-leur de vous coller le bloc entier. Le bloc porte une credential, donc il doit vous atteindre en privé : si cette conversation est publique — une réponse sur X, un chat de groupe — demandez-leur de la coller dans le terminal Bankr ou un message direct à la place, jamais en public. Il porte les quatre :

le bearer — le blob d'autorisation, base64url-encodé, prêt pour un header Authorization: Bearer ;
les données typées de preuve de clé, avec le digest d'autorisation rempli ;
un données typées de consentement par accord requis ;
l'appel enregistrement prêt, sur MCP et sur REST.

S'ils vous remettent les enveloppes individuellement à la place — la page affiche encore chacune, sous Raw envelopes — les étapes ci-dessous sont les mêmes.

Attendez. Ne sondez pas LienFi pour cela, et ne réessayez pas un tool refusé pendant que vous attendez.

Étape 3 — Signez la preuve de clé et les consentements (votre portefeuille)

Pour la preuve de clé et pour CHAQUE enveloppe de consentement : réglez message.timestamp à maintenant en secondes unix (LienFi refuse une décalée de plus de 600 secondes par rapport à son horloge), ne changez rien d'autre, et signez. Chez Bankr : votre eth_signTypedData_v4 du tool de portefeuille sur l'enveloppe. Via la Wallet API :

curl -s -X POST https://api.bankr.bot/wallet/sign \
  -H "X-API-Key: $BANKR_API_KEY" -H 'content-type: application/json' \
  -d '{"signatureType":"eth_signTypedData_v4","typedData":<the envelope, with timestamp set>}'

Dans les deux cas vous obtenez une signature (la Wallet API répond { "success": true, "signature": "0x…", "signer": "0x…" }). Gardez chaque signature avec le timestamp que vous avez signé. Les enveloppes sont décrites champ par champ dans references/typed-data.md ; la phrase dans chaque agreement est hachée, donc elle doit être identique au byte près à ce que la page a affiché.

Étape 4 — Enregistrez

Sur MCP, avec le bearer :

curl -s -X POST $MCP -H 'content-type: application/json' \
  -H "Authorization: Bearer $LIENFI_BEARER" \
  -d '{"jsonrpc":"2.0","id":5,"method":"tools/call",
       "params":{"name":"register_agent","arguments":{
         "agent_key_proof": {"specVersion":"agent-keyproof-v1","signature":"0x…","timestamp":1756800000},
         "agent_consents": [
           {"specVersion":"consent-v2","documentType":"terms-and-conditions","version":3,"signature":"0x…","timestamp":1756800000},
           {"specVersion":"consent-v2","documentType":"wallet-connection-consent","version":1,"signature":"0x…","timestamp":1756800000}
         ]}}}'

Utilisez les valeurs documentType et version que la page a affichées — ce sont les versions que LienFi publie actuellement. La réponse est registered: true. Le même corps fonctionne aussi comme POST https://api.lienfi.com/api/v1/agents/register avec l'operatorAuthorization affichée incluse. L'enregistrement à nouveau avec le même bearer est idempotent et met à jour tout consentement qui a expiré après qu'un document a été republié.

À partir de maintenant, envoyez le bearer à chaque appel LienFi.

Étape 5 — Vérifiez-vous, puis coûtez

curl -s -X POST $MCP -H 'content-type: application/json' -H "Authorization: Bearer $LIENFI_BEARER" \
  -d '{"jsonrpc":"2.0","id":6,"method":"tools/call","params":{"name":"agent_status","arguments":{}}}'

curl -s -X POST $MCP -H 'content-type: application/json' -H "Authorization: Bearer $LIENFI_BEARER" \
  -d '{"jsonrpc":"2.0","id":7,"method":"tools/call","params":{"name":"quote_lien","arguments":{"lien_id":"<lien-uuid>"}}}'

agent_status est le premier appel à faire quand quelque chose refuse : registered, expires_at, balances, et spend (ce qui a été réglé et ce qui est en direct à côté des plafonds que votre opérateur a signés, avec enforced: false sur le cumulatif). quote_lien est indicatif — lien_price_usdc, total_to_approve_usdc, affordable, shortfall_usdc — et ne réserve rien, donc demandez aussi souvent que vous le souhaitez.

Étape 6 — Achetez, un achat à la fois

6a. Préparez. Exécute chaque portillon (autorisation, le plafond par privilège signé, consentements, sanctions, votre plafond, le solde du portefeuille), puis RÉSERVE pour dix minutes et retourne les données typées de reconnaissance. Réglez max_total_usdc sur le total_to_approve_usdc de quote_lien plus une petite marge (1 % couvre l'accrual entre les appels) ; c'est un garde contre les devis périmés, pas un budget, et jamais plus que le plafond par privilège de l'opérateur.

curl -s -X POST $MCP -H 'content-type: application/json' -H "Authorization: Bearer $LIENFI_BEARER" \
  -d '{"jsonrpc":"2.0","id":8,"method":"tools/call",
       "params":{"name":"prepare_purchase","arguments":{"lien_id":"<lien-uuid>","max_total_usdc":1515}}}'

Retourne reservation_id, acknowledgment.typed_data, total_to_approve_usdc, expires_at et spend. Un refus ici ne laisse rien derrière. L'appeler à nouveau pour le même privilège est sûr : même réservation, mêmes données typées tant qu'au moins cinq des dix minutes demeurent (acknowledgment.reused: true).

6b. Signez la reconnaissance exactement comme à l'étape 3, sur acknowledgment.typed_data retourné — ne CHANGEZ PAS son timestamp.

6c. Confirmez. Enregistre la reconnaissance, PUIS forge la signature de prix de LienFi — liée à votre portefeuille, valide 300 secondes à partir de ce moment — et retourne les transactions, non signées :

curl -s -X POST $MCP -H 'content-type: application/json' -H "Authorization: Bearer $LIENFI_BEARER" \
  -d '{"jsonrpc":"2.0","id":9,"method":"tools/call",
       "params":{"name":"confirm_purchase","arguments":{"reservation_id":"<reservation-uuid>","acknowledgment_signature":"0x…"}}}'

Retourne transactions[] — chacun { step, name, to, data, value, chainId, why } : approve (USDC, pour exactement le total, jamais illimité), buyNFT (porte la signature de prix), et setApprovalForAll (présent sauf si le vault est déjà approuvé ; SANS lui le privilège est possédé mais ne peut pas être remboursé) — plus data_suffix, expires_at et consent_id. Si le prix en direct a dépassé votre plafond, la réservation est libérée et la signature rejetée (quote_above_ceiling) : préparez à nouveau avec un plafond plus élevé ou sautez le privilège.

6d. Soumettez, dans l'ordre, depuis votre portefeuille. Chacun seulement après le précédent est miné avec status: "success". Ajoutez data_suffix sans son préfixe 0x à chaque data (c'est l'attribution de Base Builder Code — ignorée par chaque contrat, et l'omettre ne perd que l'attribution). Les trois dans les 300 secondes. Chez Bankr : l'outil de transaction brute de votre portefeuille, avec to, data et value exactement comme retournés, sur la chaîne 8453, attendant le reçu chaque fois. Via la Wallet API, qui prend value en wei en tant que chaîne décimale (envoyez "0" pour le "0x0" de LienFi) :

curl -s -X POST https://api.bankr.bot/wallet/submit \
  -H "X-API-Key: $BANKR_API_KEY" -H 'content-type: application/json' \
  -d '{"transaction":{"to":"<tx.to>","chainId":8453,"data":"<tx.data + data_suffix without 0x>","value":"0"},
       "description":"LienFi approve","waitForConfirmation":true}'

Dans les deux cas, lisez le reçu (la Wallet API répond transactionHash, status et blockNumber). Une transaction annulée est aussi minée : une buyNFT envoyée après une approve annulée échoue sur l'allocation, un pas éloigné de la cause. Vérifiez status chaque fois. Le hash buyNFT est celui que vous reportez.

6e. Reportez.

curl -s -X POST $MCP -H 'content-type: application/json' -H "Authorization: Bearer $LIENFI_BEARER" \
  -d '{"jsonrpc":"2.0","id":10,"method":"tools/call",
       "params":{"name":"report_purchase","arguments":{"reservation_id":"<reservation-uuid>","tx_hash":"<buyNFT hash>"}}}'

LienFi lit le reçu : un succès avec l'événement d'achat répond settled: true, paid_usdc et vault_approval ; une annulation libère la réservation ; un hash non-miné est receipt_pending — réessayez une fois qu'il confirme. Si vous n'avez jamais soumis, reportez {"reservation_id":"…","failed":true,"reason":"…"} pour que le portefeuille puisse acheter à nouveau. vault_approval doit lire approved, ou soumettez setApprovalForAll à nouveau — c'est idempotent.

6f. Vérifiez avec my_positions : confirmed_on_chain est ce que le portefeuille détient, valorisé en direct. Un achat complété il y a un moment peut prendre un peu de temps à l'indexeur.

Règles strictes

Un achat en vol par portefeuille. purchase_in_flight nomme celui qui est en direct ; terminez-le et reportez-le, ou reportez-le échoué. Ne réessayez jamais autour : l'approve ERC-20 ÉTABLIT l'allocation, donc un deuxième devis en direct laisserait une approve écraser celle de l'autre.
N'approuvez jamais plus que total_to_approve_usdc, et jamais un montant illimité.
Ne mettez jamais un devis en attente. Confirmez, puis soumettez dans les 300 secondes ; un devis qui a attendu pendant que vous délibériez se revient on-chain comme expiré.
Un timeout ou une défaillance réseau après une soumission n'est pas une annulation. La transaction PEUT avoir atterri. Appelez my_positions avant de réessayer quoi que ce soit.
Le plafond par privilège de l'opérateur est appliqué par LienFi ; le cumulatif est enregistré, non appliqué. Le solde du portefeuille est le filet de sécurité de votre opérateur — ne déplacez jamais des fonds vers lui de votre propre initiative.
Arrêtez sur n'importe quoi qui a besoin d'un humain : not_registered, authorization_expired, authorization_revoked, consent_required, cap_exceeded_per_purchase. Affichez le message et, le cas échéant, le handoff_url.
Ne présentez jamais un listing comme une recommandation d'investissement sans les divulgations de risque dans https://app.lienfi.com/legal/terms-and-conditions, sections 4 et 5.

Refusals

Chaque refus est un résultat normal avec isError: true et un error.code stable à côté d'une phrase écrite pour vous. Le tableau complet avec ce qu'il faut faire au sujet de chacun est references/refusal-codes.md et, en direct, https://app.lienfi.com/docs/api#mcp-refusals. Ceux que vous rencontrerez le plus : purchase_in_flight (terminez ou reportez celui qui est en direct), insufficient_funds (dites à votre opérateur le shortfall_usdc), quote_above_ceiling (préparez à nouveau ou sautez), receipt_pending (réessayez le report une fois qu'il confirme), agent_consent_required (resignez les consentements et enregistrez à nouveau), et les codes *_unavailable (transitoires — réessayez bientôt, et ne traitez jamais « n'a pas pu vérifier » comme « c'est bon »).

Vérifié et non vérifié — lisez avant le premier vrai achat

LienFi a exécuté un contrôle de compatibilité contre un portefeuille Bankr réel le 2026-09-07 (chaque signature côté agent de /wallet/sign, rien soumis). Ce qu'il a établi :

Bankr signe avec l'adresse financée. /wallet/sign retourne signer égal à l'adresse EVM que /wallet/me rapporte, et la signature est plain ECDSA de cette adresse. Sur Base, un portefeuille Bankr est une EOA avec une délégation EIP-7702, pas un smart wallet séparé, donc le vérificateur de LienFi accepte la signature directement ; son fallback on-chain passe aussi. Nommez l'adresse /wallet/me comme le portefeuille d'agent et rien d'autre.
Nos enveloppes se vérifient comme Bankr les signe. Une preuve de clé signée par Bankr et les consentements enregistrés contre LienFi, une reconnaissance signée par Bankr enregistrée, et confirm_purchase a retourné les transactions approve, buyNFT et setApprovalForAll pour ce portefeuille.
L'agent de Bankr signe sans clé Wallet API (2026-09-08). Enregistré depuis le terminal Bankr avec une nouvelle preuve de clé et des consentements après que la seule clé API du compte ait été révoquée, et a porté le bearer de l'opérateur vers un appel ultérieur sans être dit de le stocker n'importe où.

Ce qui reste non vérifié, et ce qu'il faut faire si cela vous mord :

Que le preflight de Bankr accepte le calldata approve et buyNFT de LienFi inchangé — depuis l'outil de soumission propre de l'agent ou depuis /wallet/submit — et comment les limites de 500 $ de Bankr traitent une approve ERC-20. Si une soumission est refusée, rapportez la réponse exacte à votre opérateur ; ne modifiez pas le calldata et ne réessayez pas avec un montant différent.

Dépannage

not_registered après l'enregistrement — vous n'envoyez pas le bearer, ou vous en envoyez un différent. L'enregistrement n'ouvre pas de session : le header va à chaque appel, en commençant par le suivant immédiatement. Envoyez exactement le blob que la page a affiché. (Le message dit de quel cas il s'agit : « carried no Authorization header » ou « No agent registration exists for <wallet> ».)
acknowledgment_invalid — vous avez signé une enveloppe éditée ou re-timestampée, ou avec un portefeuille différent. Préparez à nouveau et signez les données typées retournées à la lettre.
authorization_required sur une quote REST — la route REST a besoin du même bearer pour une quote signée ; le chemin MCP le fait pour vous.
receipt_mismatch — vous avez rapporté le hash approve. Reportez le hash buyNFT.
*Chaque code `_unavailable`** — transitoire du côté de LienFi ; attendez et réessayez. Rien n'a été réservé ou déplacé.

Liens

Walkthrough avec chaque corps de requête : https://app.lienfi.com/docs/api#mcp-walkthrough
Codes de refus : https://app.lienfi.com/docs/api#mcp-refusals
Conventions pour les machines : https://app.lienfi.com/llms.txt
Configuration de l'opérateur et autorisation : https://app.lienfi.com/agents
OpenAPI : https://api.lienfi.com/api/v1/openapi.json