{"templateId":"markdown","versions":[{"version":"v0-beta","label":"Beta (v0)","link":"/products/native-api/docs/how-it-works/flexible-amounts","default":true,"active":true,"folderId":"e4cb5a06"}],"sharedDataIds":{"sidebar":"sidebar-products/native-api/@v0-beta/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Flexible Amount Inputs","description":"Official Banxa API documentation – on-ramp and off-ramp transfers with identity verification and compliance.","llmstxt":{"title":"Banxa Developer Documentation","description":"Integrate crypto-fiat exchange with Banxa's licensed infrastructure: payments, KYC, compliance, and settlement handled. 150+ countries, 45 global licences.","details":{"content":"Two integration products: **Banxa Native API** for partners who manage their own KYC and want full UX control (headless, HMAC server-to-server, no Banxa-hosted screens); **Banxa Hosted Checkout** for partners who want Banxa to handle KYC and payments (three paths: Referral URL, API, or React Native SDK). Both use the same sandbox and production environments at `https://api.banxa-sandbox.com` and `https://api.banxa.com`.\n\n## Constraints\n\n- **Authentication**: HMAC credentials must be stored server-side only, never expose in frontend, mobile, or client-side code. HMAC is required for all Native API calls and for KYC sharing in Hosted Checkout; `x-api-key` is used for all other Hosted Checkout endpoints.\n- **`externalCustomerId`**: Required on every buy and sell order. Use a stable opaque identifier, never PII.\n- **`identityReference`**: Must remain constant for the same user across all requests. Must not contain PII. If you attempt to create an identity for an email that already exists, you will receive a 422 / code 81, so retrieve the existing record rather than retrying creation. Use `GET /eapi/v0/identities/{identityReference}?email=user@example.com` to look up the real `identityReference` linked to an email.\n- **`quoteId`**: Only supported by `POST /eapi/v0/ramps` (bank transfer). The React Native SDK and Embedded Payment Button do not accept a `quoteId`, so use indicative pricing (`GET /eapi/v0/price`) for SDK and Embedded Payment Button flows.\n- **Quotes**: Indicative prices are not rate-locked, so refresh close to order creation to minimise rate drift. Locked quotes (`GET /eapi/v0/quote`) expire after approximately 3 minutes and are only valid for bank transfer ramp creation.\n- **Eligibility gate**: Never create a ramp or invoke the SDK when `paymentReady` is `false`. Always check eligibility and satisfy all requirements before payment execution.\n- **Webhooks**: Verify all inbound webhook signatures with HMAC-SHA256 before processing. Return HTTP 200 immediately and process asynchronously.\n- **Product selection**: Banxa Native is for partners who manage their own KYC. Banxa Hosted Checkout is for partners who do not do KYC. These are separate products with separate flows: do not mix endpoints across products.\n- **SDK scope**: The React Native SDK has no `banxa.customerIdentity` module. Identity and KYC are handled through the Native API only. `primerCallbacks` and `primerSettings` are Native context only and must not be referenced in Hosted Checkout integrations.\n- **Payment method naming**: Never use \"eAPI\" or \"EAPI\" as a product name. The correct name is \"Banxa Native API\". The URL path prefix `/eapi/` is correct and should not be changed.\n"},"hide":false,"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"flexible-amount-inputs","__idx":0},"children":["Flexible Amount Inputs"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The Native API allows you to specify ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["either the fiat amount or the crypto amount"]}," when calculating a conversion. This choice determines how the quote is calculated and must be carried through to the ramp request."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You provide either ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fiatAmount"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cryptoAmount"]}," when requesting a price, and you include that same value again when creating the ramp."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This guide explains how these inputs work across both endpoints."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"overview","__idx":1},"children":["Overview"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When requesting a price, you can choose to fix one side of the trade:"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"fiat-fixed","__idx":2},"children":["Fiat-fixed"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The user enters or confirms a fiat value"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fiatAmount"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The API returns the corresponding crypto amount"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"crypto-fixed","__idx":3},"children":["Crypto-fixed"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The user wants to buy or sell an exact amount of crypto"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cryptoAmount"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The API returns the required fiat value"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Whichever parameter you use in the price request must also be used in the transfer request.",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"Only one parameter may be included per request."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"choosing-the-correct-input","__idx":4},"children":["Choosing the Correct Input"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fiatAmount"]}]}," when:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The user is spending a fixed amount of fiat (e.g. \"Buy with 100 AUD\")"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The user wants to receive a fixed fiat payout (e.g. \"Withdraw 100 EUR\")"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Your UI is fiat-led"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cryptoAmount"]}]}," when:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The user wants an exact crypto amount (e.g. \"I want 200 USDT\")"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Your UI is crypto-led"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"using-flexible-amount-inputs-with-get-eapiv0price","__idx":5},"children":["Using Flexible Amount Inputs with GET ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/eapi/v0/price"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Price requests support both input types."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"fiat-fixed-quote","__idx":6},"children":["Fiat-fixed quote"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use this when the user specifies how much fiat they want to spend."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"GET /eapi/v0/price?identityReference=c-13344\n&fiat=AUD\n&crypto=USDT\n&blockchain=TRON\n&method=payid-bank-transfer\n&transactionType=ONRAMP\n&fiatAmount=100\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"crypto-fixed-quote","__idx":7},"children":["Crypto-fixed quote"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use this when the user wants to buy or sell a specific amount of crypto."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"GET /eapi/v0/price?identityReference=c-13344\n&fiat=AUD\n&crypto=USDT\n&blockchain=TRON\n&method=payid-bank-transfer\n&transactionType=ONRAMP\n&cryptoAmount=200\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"using-flexible-amount-inputs-with-post-eapiv0ramps","__idx":8},"children":["Using Flexible Amount Inputs with POST ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/eapi/v0/ramps"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Ramps follow the same rules as price requests:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Include either ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fiatAmount"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cryptoAmount"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use the same value you displayed in the quote"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"fiat-fixed-on-ramps","__idx":9},"children":["Fiat-fixed On-ramps"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"subPartnerId\": \"2125\",\n  \"identityReference\": \"c-13344\",\n  \"source\": {\n    \"fiat\": { \"id\": \"AUD\", \"method\": \"payid-bank-transfer\" }\n  },\n  \"target\": {\n    \"crypto\": {\n      \"id\": \"USDT\",\n      \"blockchain\": \"TRON\",\n      \"walletAddress\": \"TXY8P6mV3z5d3oF5kZNhRZVz6d12KkL5K9\"\n    }\n  },\n  \"fiatAmount\": \"100\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"crypto-fixed-on-ramps","__idx":10},"children":["Crypto-fixed On-ramps"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"subPartnerId\": \"2125\",\n  \"identityReference\": \"c-13344\",\n  \"source\": {\n    \"fiat\": {\n      \"id\": \"AUD\",\n      \"method\": \"payid-bank-transfer\"\n    }\n  },\n  \"target\": {\n    \"crypto\": {\n      \"id\": \"USDT\",\n      \"blockchain\": \"TRON\",\n      \"walletAddress\": \"TXY8P6mV3z5d3oF5kZNhRZVz6d12KkL5K9\"\n    }\n  },\n  \"cryptoAmount\": \"200\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"fiat-fixed-off-ramps","__idx":11},"children":["Fiat-fixed Off-ramps"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"subPartnerId\": \"2125\",\n  \"identityReference\": \"c-13344\",\n  \"source\": {\n    \"crypto\": {\n      \"id\": \"USDT\",\n      \"blockchain\": \"TRON\",\n      \"walletAddress\": \"0xc292474673cf1a96a96e8c56ec4f45ecf2e0b448\"\n    }\n  },\n  \"target\": {\n    \"fiat\": {\n      \"id\": \"AUD\",\n      \"method\": \"payid-bank-transfer\",\n      \"instructions\": {\n        \"accountName\": \"John Citizen\",\n        \"accountNumber\": \"12345678\",\n        \"bsb\": \"26195\"\n      }\n    }\n  },\n  \"fiatAmount\": \"100\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"crypto-fixed-off-ramps","__idx":12},"children":["Crypto-fixed Off-ramps"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"subPartnerId\": \"2125\",\n  \"identityReference\": \"c-13344\",\n  \"source\": {\n    \"crypto\": {\n      \"id\": \"USDT\",\n      \"blockchain\": \"TRON\",\n      \"walletAddress\": \"0xc292474673cf1a96a96e8c56ec4f45ecf2e0b448\"\n    }\n  },\n  \"target\": {\n    \"fiat\": {\n      \"id\": \"AUD\",\n      \"method\": \"payid-bank-transfer\",\n      \"instructions\": {\n        \"accountName\": \"John Citizen\",\n        \"accountNumber\": \"12345678\",\n        \"bsb\": \"26195\"\n      }\n    }\n  },\n  \"cryptoAmount\": \"200\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"end-to-end-examples","__idx":13},"children":["End-to-End Examples"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"on-ramp-user-spends-a-fixed-fiat-amount","__idx":14},"children":["On-Ramp: User spends a fixed fiat amount"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Request a quote with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fiatAmount=100"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Create a ramp using the same ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fiatAmount=100"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["User pays 100 AUD"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["User receives the calculated crypto amount"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"off-ramp-user-receives-a-fixed-fiat-amount","__idx":15},"children":["Off-Ramp: User receives a fixed fiat amount"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Request a quote with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fiatAmount=100"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Create a ramp using ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fiatAmount=100"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["User sends the required crypto amount"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["User receives 100 AUD into their payout method"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"crypto-fixed-behaviour","__idx":16},"children":["Crypto-fixed behaviour"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The same logic applies when fixing the crypto amount.",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"If a user specifies a crypto value, the API calculates the equivalent fiat amount in both directions."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"summary-table","__idx":17},"children":["Summary Table"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Scenario"},"children":["Scenario"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Fixed Side"},"children":["Fixed Side"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Parameter"},"children":["Parameter"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Notes"},"children":["Notes"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["On-Ramp"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Fiat"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fiatAmount"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Spend a fixed fiat amount"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Off-Ramp"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Fiat"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fiatAmount"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Receive a fixed fiat amount"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["On-Ramp"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Crypto"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cryptoAmount"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["User receives a fixed crypto amount"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Off-Ramp"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Crypto"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cryptoAmount"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["User sells a fixed crypto amount"]}]}]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"best-practices","__idx":18},"children":["Best Practices"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Pass only one amount parameter per request"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use the same parameter and value for both the price and ramp"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Avoid caching price responses for long; prices are not binding"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Ensure your UI clearly shows which side of the trade is fixed"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"locking-the-rate-for-price-integrity","__idx":19},"children":["Locking the rate for price integrity"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fiatAmount"]},"/",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cryptoAmount"]}," approach re-calculates the rate at ramp creation time. If price integrity between display and execution matters for your UX, use the quote ID flow instead — see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/native-api/docs/how-it-works/quotes-and-pricing"},"children":["Pricing & Quote ID"]},"."]}]},"headings":[{"value":"Flexible Amount Inputs","id":"flexible-amount-inputs","depth":1},{"value":"Overview","id":"overview","depth":2},{"value":"Fiat-fixed","id":"fiat-fixed","depth":4},{"value":"Crypto-fixed","id":"crypto-fixed","depth":4},{"value":"Choosing the Correct Input","id":"choosing-the-correct-input","depth":2},{"value":"Using Flexible Amount Inputs with GET /eapi/v0/price","id":"using-flexible-amount-inputs-with-get-eapiv0price","depth":2},{"value":"Fiat-fixed quote","id":"fiat-fixed-quote","depth":4},{"value":"Crypto-fixed quote","id":"crypto-fixed-quote","depth":4},{"value":"Using Flexible Amount Inputs with POST /eapi/v0/ramps","id":"using-flexible-amount-inputs-with-post-eapiv0ramps","depth":2},{"value":"Fiat-fixed On-ramps","id":"fiat-fixed-on-ramps","depth":4},{"value":"Crypto-fixed On-ramps","id":"crypto-fixed-on-ramps","depth":4},{"value":"Fiat-fixed Off-ramps","id":"fiat-fixed-off-ramps","depth":4},{"value":"Crypto-fixed Off-ramps","id":"crypto-fixed-off-ramps","depth":4},{"value":"End-to-End Examples","id":"end-to-end-examples","depth":2},{"value":"On-Ramp: User spends a fixed fiat amount","id":"on-ramp-user-spends-a-fixed-fiat-amount","depth":4},{"value":"Off-Ramp: User receives a fixed fiat amount","id":"off-ramp-user-receives-a-fixed-fiat-amount","depth":4},{"value":"Crypto-fixed behaviour","id":"crypto-fixed-behaviour","depth":4},{"value":"Summary Table","id":"summary-table","depth":2},{"value":"Best Practices","id":"best-practices","depth":2},{"value":"Locking the rate for price integrity","id":"locking-the-rate-for-price-integrity","depth":2}],"frontmatter":{"title":"Pricing & Amount Inputs","description":"How to use fiatAmount and cryptoAmount in Banxa Native price and ramp requests.","seo":{"title":"Flexible Amount Inputs"}},"lastModified":"2026-05-19T23:30:38.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/products/native-api/docs/how-it-works/flexible-amounts","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}