{"openapi":"3.1.0","info":{"title":"LirChain API","version":"1.0.0","summary":"Wallet tracker, deposit wallets, one-time payments and payouts.","description":"LirChain is a crypto payments API for developers: a wallet tracker with webhooks on Bitcoin, Ethereum, Solana, Tron, BNB Chain and Polygon, a unique deposit address for every user, one-time USDT and USDC payments with a hosted payment page, and USDT and USDC payouts. It is a plain REST API with JSON, one API key header and a free plan, and it is documented in one markdown file and an OpenAPI description so that AI coding agents can integrate it without guessing.\n\nThe full reference in markdown is at https://lirchain.com/llms-full.txt.\n\nErrors:\n- 400: The request is not valid: a field is missing, an id is not an id, or the network and asset are not supported.\n- 401: The API key header is missing.\n- 402: Your balance is too low for the payout and its fee.\n- 403: The key is unknown, belongs to a project of another service, or the plan does not allow it (no active plan, or a limit is reached).\n- 404: The path does not exist, or the project has nothing with that id.\n- 429: Too many requests. The retry-after header says how many seconds to wait.\n- 500: Something went wrong on our side.\n- 503: Wallets cannot be created right now. Try again later.","contact":{"name":"LirChain support","email":"support@lirchain.com","url":"https://lirchain.com"}},"externalDocs":{"description":"API documentation","url":"https://lirchain.com/docs"},"servers":[{"url":"https://api.lirchain.com"}],"security":[{"api_key":[]}],"tags":[{"name":"General","description":"Works with the API key of any project. Works with the API key of any project."},{"name":"One-Time Payments","description":"Needs the API key of a project of the service one_time_payments. A payment request for one purchase, paid in USDT or USDC. Every payment gets its own address. It is pending until one transfer brings at least the amount to that address, then it is paid. Smaller transfers are not added up: they are added to your balance, but they do not pay the payment."},{"name":"Deposit Wallets","description":"Needs the API key of a project of the service deposit_wallets. A permanent address for one customer. Every transfer of the wallet's asset to it becomes a deposit of the project."},{"name":"Wallet Tracker","description":"Needs the API key of a project of the service wallet_tracker. Follows any address, on more networks than the other services: Ethereum, BNB Chain, Polygon, Tron, Solana and Bitcoin. Every transfer of USDT, USDC or the network's own coin to or from it becomes an event of the project."},{"name":"Payouts","description":"Needs the API key of a project of the service payouts. Money from your balance to an address you choose, for example to pay one of your users. The amount and the fee are taken from your balance the moment the payout is created, and a payout cannot be cancelled: once it is created it is sent."}],"paths":{"/merchant/ping":{"get":{"operationId":"check_api_key","summary":"Check an API key","description":"Answers when the key is valid and tells you which project and service it belongs to.","tags":["General"],"parameters":[],"responses":{"200":{"description":"The request succeeded.","content":{"application/json":{"schema":{"type":"object"},"example":{"status":"ok","project_id":"3d6b1130-da92-4ddf-bad2-93f898993c39","service":"one_time_payments"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/merchant/allowance":{"get":{"operationId":"get_allowance","summary":"Get your plan's limits","description":"How much of every limit of your plan is used and how much it allows.\n\nThe limits belong to your account and are shared by all its projects, so every key gives the same answer.\n\nprojects, deposit_wallets and wallet_trackers count what exists now. The others count what happened since your plan's current period started.\n\nWithout an active plan the answer is 403.","tags":["General"],"parameters":[],"responses":{"200":{"description":"The request succeeded.","content":{"application/json":{"schema":{"type":"object"},"example":{"projects":{"used":4,"limit":4},"deposit_wallets":{"used":12,"limit":1000},"one_time_payments":{"used":310,"limit":1000},"wallet_trackers":{"used":3,"limit":1000},"tracker_events":{"used":542,"limit":1000}}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/merchant/one-time-payment/create":{"post":{"operationId":"create_payment","summary":"Create a payment","description":"Creates a pending payment and the address your customer pays to.\n\nCounts towards the payments of your billing period. When the limit is reached the answer is 403.\n\nCreating a payment is free. The fee is charged when it is paid.\n\nexpire_ms is one hour after created_ms: the time you should give your customer to pay.\n\namount is the price in dollars, and also how many of the stablecoin the customer has to send in one transfer. pay_amount is the same number: what is to be paid.\n\nreceive_amount is what you receive on your balance for the payment: what is paid minus the fee. While the payment is pending it is worked out with the fee of your plan as it is now. Once it is paid it is what you did receive.","tags":["One-Time Payments"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"network":{"type":"string","description":"ethereum, bsc or polygon."},"asset":{"type":"string","description":"What it is paid in: USDT or USDC, by its symbol or its contract address."},"amount":{"type":"number","description":"What the customer pays, in dollars, at least 1. You receive it minus the fee. Give this or receive_amount."},"receive_amount":{"type":"number","description":"What you want to receive after the fee, in dollars. The customer pays that plus the fee, rounded up to a cent. Give this or amount."},"external_id":{"type":"string","description":"Your own id for the payment, e.g. your order id, up to 255 characters. We store it and give it back, also in webhooks."}},"required":["network","asset"]},"example":{"network":"polygon","asset":"USDT","amount":49.5,"external_id":"order-1042"}}}},"responses":{"201":{"description":"The request succeeded.","content":{"application/json":{"schema":{"type":"object"},"example":{"id":"ccf1c790-9d3d-4cda-98a9-5cd590a102df","external_id":"order-1042","network":"polygon","address":"0x20d5b8802fc43b24cdbc9cdaa59dd6690626ad2c","asset":"USDT","amount":49.5,"pay_amount":49.5,"receive_amount":"49.2525","status":"pending","fee":"0","created_ms":1791503932667,"expire_ms":1791507532667}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/merchant/one-time-payment/otp":{"get":{"operationId":"get_payment","summary":"Get a payment","description":"One payment of the project, with its current status.\n\nstatus is pending or paid.\n\nfee is what we charged for the transfer that paid the payment: the percentage of your plan. It is 0 until the payment is paid.","tags":["One-Time Payments"],"parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string","format":"uuid","description":"The id of the payment."},"example":"ccf1c790-9d3d-4cda-98a9-5cd590a102df"}],"responses":{"200":{"description":"The request succeeded.","content":{"application/json":{"schema":{"type":"object"},"example":{"id":"ccf1c790-9d3d-4cda-98a9-5cd590a102df","external_id":"order-1042","network":"polygon","address":"0x20d5b8802fc43b24cdbc9cdaa59dd6690626ad2c","asset":"USDT","amount":49.5,"pay_amount":49.5,"receive_amount":"49.2525","status":"paid","fee":"0.2475","created_ms":1791503932667,"expire_ms":1791507532667}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/merchant/one-time-payment/page":{"get":{"operationId":"list_payments","summary":"List payments","description":"The payments of the project, newest first.","tags":["One-Time Payments"],"parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"number","description":"The page to return, starting at 1. 50 items per page."},"example":1}],"responses":{"200":{"description":"The request succeeded.","content":{"application/json":{"schema":{"type":"object"},"example":{"items":[{"id":"ccf1c790-9d3d-4cda-98a9-5cd590a102df","external_id":"order-1042","network":"polygon","address":"0x20d5b8802fc43b24cdbc9cdaa59dd6690626ad2c","asset":"USDT","amount":49.5,"pay_amount":49.5,"receive_amount":"49.2525","status":"paid","fee":"0.2475","created_ms":1791503932667,"expire_ms":1791507532667}],"page":1,"total_pages":1}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/merchant/deposit-wallet/create":{"post":{"operationId":"create_deposit_wallet","summary":"Create a wallet","description":"Creates a wallet with a new address. It accepts one asset on one network.\n\nCounts towards the wallets of your plan. When the limit is reached the answer is 403.","tags":["Deposit Wallets"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"network":{"type":"string","description":"ethereum, bsc or polygon."},"asset":{"type":"string","description":"What it is paid in: a token by its symbol (USDT, USDC) or contract address, or the network's own coin by its symbol (ETH, BNB, POL)."},"external_id":{"type":"string","description":"Your own id for the wallet, e.g. the id of the customer it belongs to, up to 255 characters. We store it and give it back, also in webhooks."}},"required":["network","asset"]},"example":{"network":"polygon","asset":"USDC","external_id":"customer-7731"}}}},"responses":{"201":{"description":"The request succeeded.","content":{"application/json":{"schema":{"type":"object"},"example":{"id":"3f4911a7-2c26-4f9c-a97c-80b25b6feb8c","project_id":"3d6b1130-da92-4ddf-bad2-93f898993c39","merchant_id":"7c551c17-1a48-4e2b-b3ac-7ad389a753c6","network":"polygon","address":"0x748aaf6d861698dc3c4ee2fca3c27ba13edc7891","asset":"USDC","external_id":"customer-7731"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/merchant/deposit-wallet/delete":{"delete":{"operationId":"delete_deposit_wallet","summary":"Delete a wallet","description":"Deletes the wallet and frees its place in your plan. Deposits sent to its address afterwards are not recorded.","tags":["Deposit Wallets"],"parameters":[{"name":"wallet_id","in":"query","required":true,"schema":{"type":"string","format":"uuid","description":"The id of the wallet."},"example":"3f4911a7-2c26-4f9c-a97c-80b25b6feb8c"}],"responses":{"204":{"description":"The request succeeded. There is no body."},"default":{"$ref":"#/components/responses/Error"}}}},"/merchant/deposit-wallet/wallets":{"get":{"operationId":"list_deposit_wallets","summary":"List wallets","description":"The wallets of the project.","tags":["Deposit Wallets"],"parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"number","description":"The page to return, starting at 1. 50 items per page."},"example":1}],"responses":{"200":{"description":"The request succeeded.","content":{"application/json":{"schema":{"type":"object"},"example":{"items":[{"id":"3f4911a7-2c26-4f9c-a97c-80b25b6feb8c","project_id":"3d6b1130-da92-4ddf-bad2-93f898993c39","merchant_id":"7c551c17-1a48-4e2b-b3ac-7ad389a753c6","network":"polygon","address":"0x748aaf6d861698dc3c4ee2fca3c27ba13edc7891","asset":"USDC","external_id":"customer-7731"}],"page":1,"total_pages":1}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/merchant/deposit-wallet/deposits":{"get":{"operationId":"list_deposits","summary":"List deposits","description":"The deposits of the project, newest first.\n\namount is in whole units of the wallet's asset, as text so no precision is lost.\n\ntransfer_id is our id of the transfer on the chain this deposit is. It is the same as id: one transfer is only ever one deposit.\n\namount is what arrived, in the wallet's asset. pay_amount is what was paid in dollars: the same number for USDT and USDC, and for a network's own coin what it was exchanged for. fee is our fee, and receive_amount is what you receive on your balance: pay_amount without the fee. All three are 0 while processed_ms is null: the deposit was seen but is not on your balance yet, which for a coin takes until its exchange is confirmed.","tags":["Deposit Wallets"],"parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"number","description":"The page to return, starting at 1. 50 items per page."},"example":1},{"name":"wallet_id","in":"query","required":false,"schema":{"type":"string","format":"uuid","description":"Only the deposits of this wallet."},"example":"3f4911a7-2c26-4f9c-a97c-80b25b6feb8c"}],"responses":{"200":{"description":"The request succeeded.","content":{"application/json":{"schema":{"type":"object"},"example":{"items":[{"id":"41b0d4fe-8b49-4623-bd8f-6f04586b06c9","wallet_id":"3f4911a7-2c26-4f9c-a97c-80b25b6feb8c","project_id":"3d6b1130-da92-4ddf-bad2-93f898993c39","merchant_id":"7c551c17-1a48-4e2b-b3ac-7ad389a753c6","transfer_id":"41b0d4fe-8b49-4623-bd8f-6f04586b06c9","amount":"250.5","pay_amount":"250.5","fee":"1.2525","receive_amount":"249.2475","created_ms":1791503990112,"processed_ms":1791503991340}],"page":1,"total_pages":1}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/merchant/wallet-tracker/create":{"post":{"operationId":"create_wallet_tracker","summary":"Create a tracker","description":"Starts tracking an address on one network.\n\nCounts towards the trackers of your plan. When the limit is reached the answer is 403.\n\nAn address that is not a valid one for the network is refused with 400. Ethereum, BNB Chain and Polygon addresses are stored and returned in lowercase. The others are kept exactly as written: their capitals matter.\n\nA tracker reports what happens from the moment it is added, not what happened before.","tags":["Wallet Tracker"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"network":{"type":"string","description":"ethereum, bsc, polygon, tron, solana or bitcoin."},"address":{"type":"string","description":"The address to track, written the way that network writes addresses: 0x and 40 hex characters, T… on Tron, a base58 address on Solana, 1…, 3… or bc1… on Bitcoin."},"external_id":{"type":"string","description":"Your own id for the tracker, up to 255 characters. We store it and give it back, also in webhooks."}},"required":["network","address"]},"example":{"network":"ethereum","address":"0xdAC17F958D2ee523a2206206994597C13D831ec7","external_id":"treasury"}}}},"responses":{"201":{"description":"The request succeeded.","content":{"application/json":{"schema":{"type":"object"},"example":{"id":"67153a22-af19-4352-ab8e-041006c76c7b","project_id":"ea54aa6c-21d7-46a4-b1fe-c0703f74a2af","merchant_id":"7c551c17-1a48-4e2b-b3ac-7ad389a753c6","network":"ethereum","address":"0xdac17f958d2ee523a2206206994597c13d831ec7","external_id":"treasury"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/merchant/wallet-tracker/delete":{"delete":{"operationId":"delete_wallet_tracker","summary":"Delete a tracker","description":"Stops tracking the address and frees its place in your plan.","tags":["Wallet Tracker"],"parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string","format":"uuid","description":"The id of the tracker."},"example":"67153a22-af19-4352-ab8e-041006c76c7b"}],"responses":{"204":{"description":"The request succeeded. There is no body."},"default":{"$ref":"#/components/responses/Error"}}}},"/merchant/wallet-tracker/trackers":{"get":{"operationId":"list_wallet_trackers","summary":"List trackers","description":"The trackers of the project.","tags":["Wallet Tracker"],"parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"number","description":"The page to return, starting at 1. 50 items per page."},"example":1}],"responses":{"200":{"description":"The request succeeded.","content":{"application/json":{"schema":{"type":"object"},"example":{"items":[{"id":"67153a22-af19-4352-ab8e-041006c76c7b","project_id":"ea54aa6c-21d7-46a4-b1fe-c0703f74a2af","merchant_id":"7c551c17-1a48-4e2b-b3ac-7ad389a753c6","network":"ethereum","address":"0xdac17f958d2ee523a2206206994597c13d831ec7","external_id":"treasury"}],"page":1,"total_pages":1}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/merchant/wallet-tracker/events":{"get":{"operationId":"list_tracker_events","summary":"List events","description":"The events of the project with their transfers, newest first.\n\nasset and amount are the chain's own values: the token's contract address and the amount in its smallest unit. The network's own coin has the address 0x0000000000000000000000000000000000000000 and no log_index.\n\nsymbol and amount_units are the same transfer in readable form.\n\nThe tracked address is the sender when it equals from_address and the receiver when it equals to_address.\n\nOn Bitcoin and Solana one transaction can have many senders and receivers, so an event is what the transaction changed for your address: the amount it received minus what it spent, or the other way round. The other side is an empty string. On Solana the network fee your address paid is not counted.\n\nasset is written the way the network writes it: a T… contract on Tron, the token's mint on Solana. On Solana log_index holds the mint for a token event.\n\nA transfer that failed on its chain is never reported.\n\nSolana addresses are read about every 20 seconds, and only the usual token account of an address is watched for USDT and USDC.","tags":["Wallet Tracker"],"parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"number","description":"The page to return, starting at 1. 50 items per page."},"example":1},{"name":"wallet_tracker_id","in":"query","required":false,"schema":{"type":"string","format":"uuid","description":"Only the events of this tracker."},"example":"67153a22-af19-4352-ab8e-041006c76c7b"}],"responses":{"200":{"description":"The request succeeded.","content":{"application/json":{"schema":{"type":"object"},"example":{"items":[{"id":"95e04e32-5c98-4f68-8c62-f487bda0ed5c","tracker_id":"67153a22-af19-4352-ab8e-041006c76c7b","created_ms":1791504120904,"transfer":{"network":"ethereum","block_number":26151012,"tx_hash":"0x4e3a…9f21","log_index":"28","from_address":"0xdac17f958d2ee523a2206206994597c13d831ec7","to_address":"0x52ae0f1c8d4b7a90e3b6c2d15f8a47e09b3c91f3","asset":"0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48","amount":"102870865","symbol":"USDC","amount_units":"102.870865"}}],"page":1,"total_pages":1}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/merchant/payout/create":{"post":{"operationId":"create_payout","summary":"Create a payout","description":"Takes the amount and the fee from your balance and creates the payout to the address. This cannot be undone.\n\nThe fee is the percentage of your plan, taken from your balance on top of the amount. receive_amount is what the receiver gets (the amount), pay_amount is what leaves your balance for it (the amount and the fee).\n\nYour balance must cover the amount and the fee, otherwise the answer is 402 and nothing is taken.\n\nstatus is pending, processing, completed or failed. tx_hash is set once the payout is completed. A failed payout was not sent, and its amount and fee are back on your balance.\n\nA payout is sent within a few seconds of being created (processing) and becomes completed once the network has safely confirmed it, 12 blocks later. There is no webhook for payouts yet: read the payout to see its status.","tags":["Payouts"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"network":{"type":"string","description":"ethereum, bsc or polygon."},"asset":{"type":"string","description":"The token: its symbol (USDT, USDC) or its contract address."},"address":{"type":"string","description":"Where the money goes: 0x followed by 40 hex characters."},"amount":{"oneOf":[{"type":"number"},{"type":"string"}],"description":"The amount in dollars, at least 1, with at most two decimals."},"external_id":{"type":"string","description":"Your own id for the payout, e.g. the id of the user you are paying, up to 255 characters. We store it and give it back."}},"required":["network","asset","address","amount"]},"example":{"network":"polygon","asset":"USDT","address":"0x52aE0F1c8D4b7A90e3B6c2D15f8A47e09B3C91F3","amount":"25.50","external_id":"user-5521"}}}},"responses":{"201":{"description":"The request succeeded.","content":{"application/json":{"schema":{"type":"object"},"example":{"id":"8a1f4c2e-6d3b-4f70-9c15-2e7b0a94d6c3","external_id":"user-5521","network":"polygon","asset":"USDT","address":"0x52ae0f1c8d4b7a90e3b6c2d15f8a47e09b3c91f3","amount":"25.50","fee":"0.1275","receive_amount":"25.50","pay_amount":"25.6275","status":"pending","tx_hash":null,"created_ms":1791506100412,"processed_ms":null}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/merchant/payout/payout":{"get":{"operationId":"get_payout","summary":"Get a payout","description":"One payout of the project, with its current status.","tags":["Payouts"],"parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string","format":"uuid","description":"The id of the payout."},"example":"8a1f4c2e-6d3b-4f70-9c15-2e7b0a94d6c3"}],"responses":{"200":{"description":"The request succeeded.","content":{"application/json":{"schema":{"type":"object"},"example":{"id":"8a1f4c2e-6d3b-4f70-9c15-2e7b0a94d6c3","external_id":"user-5521","network":"polygon","asset":"USDT","address":"0x52ae0f1c8d4b7a90e3b6c2d15f8a47e09b3c91f3","amount":"25.50","fee":"0.1275","receive_amount":"25.50","pay_amount":"25.6275","status":"pending","tx_hash":null,"created_ms":1791506100412,"processed_ms":null}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/merchant/payout/page":{"get":{"operationId":"list_payouts","summary":"List payouts","description":"The payouts of the project, newest first.","tags":["Payouts"],"parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"number","description":"The page to return, starting at 1. 50 items per page."},"example":1}],"responses":{"200":{"description":"The request succeeded.","content":{"application/json":{"schema":{"type":"object"},"example":{"items":[{"id":"8a1f4c2e-6d3b-4f70-9c15-2e7b0a94d6c3","external_id":"user-5521","network":"polygon","asset":"USDT","address":"0x52ae0f1c8d4b7a90e3b6c2d15f8a47e09b3c91f3","amount":"25.50","fee":"0.1275","receive_amount":"25.50","pay_amount":"25.6275","status":"pending","tx_hash":null,"created_ms":1791506100412,"processed_ms":null}],"page":1,"total_pages":1}}}},"default":{"$ref":"#/components/responses/Error"}}}}},"components":{"securitySchemes":{"api_key":{"type":"apiKey","in":"header","name":"x-api-key","description":"The API key of a project, made in the dashboard."}},"responses":{"Error":{"description":"The request failed. The status code says why.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"plan limit reached"}}}}}}}