{"openapi":"3.1.0","info":{"title":"easyway merchant API","version":"1","description":"Create crypto invoices, receive signed webhooks, read balances and request payouts. Human-readable guide with code samples: https://easyway.cash/docs"},"externalDocs":{"description":"API documentation","url":"https://easyway.cash/docs"},"servers":[{"url":"https://api.easyway.cash"}],"security":[{"bearer":[]},{"apiKeyHeader":[]}],"tags":[{"name":"Invoices","description":"Ask a customer for a payment and follow it to paid."},{"name":"Payouts","description":"Withdraw from your balance to your own (whitelisted) wallets."},{"name":"Account","description":"Balances, indicative rates and the coins enabled today."}],"paths":{"/v1/invoices":{"post":{"tags":["Invoices"],"summary":"Create an invoice","operationId":"createInvoice","x-required-scope":"invoices:write","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Makes a retry safe: the same key with the same body replays the first response instead of creating a second object.","schema":{"type":"string","pattern":"^[A-Za-z0-9_\\-:.]{8,128}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceCreate"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invoice"}}}},"400":{"description":"Validation or business-rule error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing scope, IP not allowed, or address not whitelisted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"request_in_progress (same Idempotency-Key still running)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"idempotency_key_reused (same key, different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (300 requests per minute per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"tags":["Invoices"],"summary":"List invoices","operationId":"listInvoices","x-required-scope":"invoices:read","parameters":[{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"maximum":10000,"default":1},"description":"1-based; newest first."},{"name":"pageSize","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"from","in":"query","schema":{"type":"string","format":"date"},"description":"Created on or after this UTC day (YYYY-MM-DD)."},{"name":"to","in":"query","schema":{"type":"string","format":"date"},"description":"Created on or before this UTC day (YYYY-MM-DD, inclusive). Must not be before `from`."},{"name":"order_id","in":"query","schema":{"type":"string","maxLength":128}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data","total","page","page_size"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Invoice"}},"total":{"type":"integer"},"page":{"type":"integer"},"page_size":{"type":"integer"}}}}}},"400":{"description":"Validation or business-rule error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing scope, IP not allowed, or address not whitelisted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (300 requests per minute per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/invoices/{id}":{"get":{"tags":["Invoices"],"summary":"Retrieve an invoice","operationId":"getInvoice","x-required-scope":"invoices:read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^inv_[0-9A-Za-z]{22}$"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invoice"}}}},"400":{"description":"Validation or business-rule error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing scope, IP not allowed, or address not whitelisted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"invoice_not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (300 requests per minute per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/invoices/{id}/cancel":{"post":{"tags":["Invoices"],"summary":"Cancel a pending invoice","operationId":"cancelInvoice","x-required-scope":"invoices:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^inv_[0-9A-Za-z]{22}$"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invoice"}}}},"400":{"description":"Validation or business-rule error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing scope, IP not allowed, or address not whitelisted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"invoice_not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"invoice_not_pending","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (300 requests per minute per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/payouts":{"post":{"tags":["Payouts"],"summary":"Request a payout","operationId":"createPayout","x-required-scope":"payouts:write","description":"Live payouts only go to addresses whitelisted in the dashboard with 2FA. Amount + network fee are locked on the balance immediately.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Makes a retry safe: the same key with the same body replays the first response instead of creating a second object.","schema":{"type":"string","pattern":"^[A-Za-z0-9_\\-:.]{8,128}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayoutCreate"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Payout"}}}},"400":{"description":"Validation or business-rule error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing scope, IP not allowed, or address not whitelisted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"request_in_progress","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"insufficient_funds or idempotency_key_reused","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (300 requests per minute per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"tags":["Payouts"],"summary":"List payouts","operationId":"listPayouts","x-required-scope":"payouts:read","parameters":[{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"maximum":10000,"default":1},"description":"1-based; newest first."},{"name":"pageSize","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"from","in":"query","schema":{"type":"string","format":"date"},"description":"Created on or after this UTC day (YYYY-MM-DD)."},{"name":"to","in":"query","schema":{"type":"string","format":"date"},"description":"Created on or before this UTC day (YYYY-MM-DD, inclusive). Must not be before `from`."},{"name":"status","in":"query","schema":{"type":"string","enum":["pending","processing","sent","failed","cancelled"]}},{"name":"asset","in":"query","schema":{"type":"string"},"description":"A coin id; ids that are no longer enabled are accepted too."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data","total","page","page_size"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Payout"}},"total":{"type":"integer"},"page":{"type":"integer"},"page_size":{"type":"integer"}}}}}},"400":{"description":"Validation or business-rule error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing scope, IP not allowed, or address not whitelisted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (300 requests per minute per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/payouts/{id}":{"get":{"tags":["Payouts"],"summary":"Retrieve a payout","operationId":"getPayout","x-required-scope":"payouts:read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^po_[0-9A-Za-z]{22}$"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Payout"}}}},"400":{"description":"Validation or business-rule error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing scope, IP not allowed, or address not whitelisted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"payout_not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (300 requests per minute per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/balances":{"get":{"tags":["Account"],"summary":"Balances per coin and network","operationId":"getBalances","x-required-scope":"balances:read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","required":["asset","available","locked"],"properties":{"asset":{"$ref":"#/components/schemas/AssetId"},"available":{"type":"string","description":"Withdrawable now"},"locked":{"type":"string","description":"Reserved by payouts in flight"}}}}}}}}},"400":{"description":"Validation or business-rule error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing scope, IP not allowed, or address not whitelisted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (300 requests per minute per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/rates":{"get":{"tags":["Account"],"summary":"Indicative USD rates","operationId":"getRates","description":"Any key. USD per unit; stablecoins are pinned to 1. An invoice locks its own rate when the payer picks a coin.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","additionalProperties":{"type":"string"}}}}}}},"400":{"description":"Validation or business-rule error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing scope, IP not allowed, or address not whitelisted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (300 requests per minute per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/assets":{"get":{"tags":["Account"],"summary":"Coins and networks enabled today","operationId":"getAssets","description":"Any key. fee_bps is this merchant's processing fee in basis points.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["fee_bps","data"],"properties":{"fee_bps":{"type":"integer"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Asset"}}}}}}},"400":{"description":"Validation or business-rule error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing scope, IP not allowed, or address not whitelisted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (300 requests per minute per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"webhooks":{"event":{"post":{"summary":"Event delivered to your webhook URL","operationId":"webhookEvent","description":"Signed with X-Webhook-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256(secret, t + \".\" + raw_body)>. Answer 2xx within 10 seconds; failures are retried 8 times over about 45 hours.","parameters":[{"name":"X-Webhook-Signature","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"}}}},"responses":{"200":{"description":"Any 2xx acknowledges the event"}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"sk_live_… or sk_test_… — the key decides the mode."},"apiKeyHeader":{"type":"apiKey","in":"header","name":"X-Api-Key"}},"schemas":{"AssetId":{"type":"string","enum":["USDT_TRC20","USDT_BEP20","USDT_TON","USDT_ERC20","TRX","BNB","GRAM","ETH","BTC","LTC","DOGE","USDC_ERC20","USDC_BEP20","XRP","SOL","USDT_SOL","USDC_SOL","POL","USDT_POLYGON","USDC_POLYGON","AVAX","USDT_AVAX","USDC_AVAX","DAI_ERC20","FDUSD_BEP20","DASH","SHIB_ERC20","PEPE_ERC20","BONK_SOL","NOT_TON","PYUSD_ERC20","DOGS_TON","CATI_TON"],"description":"A (coin, network) pair."},"Decimal":{"type":"string","pattern":"^\\d+(\\.\\d+)?$","maxLength":40,"description":"Amounts are decimal strings, never numbers."},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Stable machine-readable code — match on this"},"message":{"type":"string"},"fields":{"type":"array","items":{"type":"string"},"description":"Names of the invalid fields (validation_error only)."}}},"InvoiceCreate":{"type":"object","required":["amount"],"additionalProperties":false,"properties":{"amount":{"$ref":"#/components/schemas/Decimal"},"currency":{"description":"\"USD\" (payer picks the coin) or a coin id (only that coin is accepted).","default":"USD","anyOf":[{"const":"USD"},{"$ref":"#/components/schemas/AssetId"}]},"order_id":{"type":"string","maxLength":128},"description":{"type":"string","maxLength":500},"customer_email":{"type":"string","format":"email","maxLength":190},"success_url":{"type":"string","format":"uri","maxLength":500},"cancel_url":{"type":"string","format":"uri","maxLength":500},"allowed_assets":{"type":"array","items":{"$ref":"#/components/schemas/AssetId"}},"metadata":{"type":"object","maxProperties":20,"additionalProperties":{"type":"string","maxLength":500}},"lifetime":{"type":"integer","minimum":5,"maximum":1440,"description":"Minutes until an unpaid invoice expires."}}},"Invoice":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["pending","confirming","paid","underpaid","expired","cancelled"]},"mode":{"type":"string","enum":["live","test"]},"order_id":{"type":["string","null"],"description":""},"description":{"type":["string","null"],"description":""},"amount":{"type":"string","description":"Price, in currency units"},"currency":{"type":"string"},"pay_asset":{"type":["string","null"],"description":"Set once the payer picks a coin"},"pay_amount":{"type":["string","null"],"description":""},"pay_address":{"type":["string","null"],"description":""},"pay_memo":{"type":["string","null"],"description":"Non-null: the payer must attach this memo / destination tag"},"pay_network":{"type":["string","null"],"description":""},"rate":{"type":["string","null"],"description":"USD per unit, locked at selection"},"received_amount":{"type":"string"},"remaining_amount":{"type":"string"},"fee_amount":{"type":"string"},"net_amount":{"type":"string"},"customer_email":{"type":["string","null"],"description":""},"metadata":{"type":["object","null"],"additionalProperties":{"type":"string"}},"payment_url":{"type":"string","format":"uri"},"expires_at":{"type":"string","format":"date-time"},"paid_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"}}},"PayoutCreate":{"type":"object","required":["asset","address","amount"],"additionalProperties":false,"properties":{"asset":{"$ref":"#/components/schemas/AssetId"},"address":{"type":"string","maxLength":128},"memo":{"type":"string","maxLength":120,"pattern":"^[\\x20-\\x7E]+$"},"amount":{"$ref":"#/components/schemas/Decimal"},"note":{"type":"string","maxLength":255}}},"Payout":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["pending","processing","sent","failed","cancelled"]},"mode":{"type":"string","enum":["live","test"]},"asset":{"type":"string"},"address":{"type":"string"},"memo":{"type":["string","null"],"description":""},"amount":{"type":"string"},"network_fee":{"type":"string"},"tx_hash":{"type":["string","null"],"description":""},"failure_reason":{"type":["string","null"],"description":""},"created_at":{"type":"string","format":"date-time"}}},"Asset":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/AssetId"},"symbol":{"type":"string"},"name":{"type":"string"},"network":{"type":"string"},"network_label":{"type":"string"},"memo_required":{"type":"boolean"},"decimals":{"type":"integer"},"confirmations":{"type":"integer"},"payout_fee":{"type":"string"},"min_payout":{"type":"string"}}},"WebhookEvent":{"type":"object","required":["id","type","mode","created","data"],"properties":{"id":{"type":"string","description":"evt_… — store it and skip repeats."},"type":{"type":"string","enum":["invoice.confirming","invoice.paid","invoice.underpaid","invoice.expired","invoice.cancelled","payout.sent","payout.failed","webhook.test"]},"mode":{"type":"string","enum":["live","test"]},"created":{"type":"integer","description":"Unix seconds"},"data":{"type":"object","properties":{"invoice":{"$ref":"#/components/schemas/Invoice"},"payout":{"$ref":"#/components/schemas/Payout"},"message":{"type":"string","description":"webhook.test only"}}}}}}}}