{ "openapi": "3.0.3", "info": { "title": "BRRR Developer Docs", "version": "1.0.0" }, "servers": [ { "url": "https://api.brrr.network", "description": "Production" } ], "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-Api-Key" } }, "schemas": { "StatusOk": { "type": "object", "required": ["status"], "properties": { "status": { "type": "string", "example": "ok", "description": "\"ok\" \u2014 indicates the request was processed successfully." } } }, "Error400": { "type": "object", "required": ["status", "error", "errorCode"], "properties": { "status": { "type": "string", "example": "error", "description": "\"error\" \u2014 indicates the request failed." }, "error": { "type": "string", "description": "Human-readable error message describing the failure." }, "errorCode": { "type": "string", "description": "Machine-readable error code identifying the failure type." } } }, "Error403": { "type": "object", "required": ["status", "error", "errorCode"], "properties": { "status": { "type": "string", "example": "error", "description": "\"error\" \u2014 indicates the request was rejected due to authentication or access failure." }, "error": { "type": "string", "example": "Access denied", "description": "Human-readable error message." }, "errorCode": { "type": "string", "example": "ACCESS_DENIED", "description": "Machine-readable error code. Typically `ACCESS_DENIED`." } } }, "Error404": { "type": "object", "required": ["status", "error", "errorCode"], "properties": { "status": { "type": "string", "example": "error", "description": "\"error\" \u2014 indicates the requested resource was not found." }, "error": { "type": "string", "description": "Human-readable error message." }, "errorCode": { "type": "string", "description": "Machine-readable error code. Typically `NOT_FOUND`." } } }, "Error429": { "type": "object", "required": ["status", "error", "errorCode"], "properties": { "status": { "type": "string", "example": "error", "description": "\"error\" \u2014 indicates the request was rejected because the rate limit was exceeded." }, "error": { "type": "string", "example": "Too many requests", "description": "Human-readable error message." }, "errorCode": { "type": "string", "example": "TOO_MANY_REQUESTS", "description": "Machine-readable error code for rate limiting." } } }, "Error500": { "type": "object", "required": ["status", "error", "errorCode"], "properties": { "status": { "type": "string", "example": "error", "description": "\"error\" \u2014 indicates an unexpected server-side failure." }, "error": { "type": "string", "example": "", "description": "Human-readable error message." }, "errorCode": { "type": "string", "example": "INTERNAL_SERVER_ERROR", "description": "Machine-readable error code." } } }, "RegisterCustomerRequest": { "type": "object", "required": ["customerId", "addressEVM"], "properties": { "customerId": { "type": "string", "description": "Your internal identifier for this customer. Must be unique within your integration. Allowed characters: alphanumeric, hyphens, underscores. Maximum length: 64 characters. Case-sensitive.", "maxLength": 64, "pattern": "^[a-zA-Z0-9_-]+$", "example": "customer_a1b2c3d4" }, "addressEVM": { "type": "string", "description": "The customer's EVM wallet address. Accepts EIP-55 checksummed or lowercase hex format. Must be a valid 20-byte Ethereum-compatible address.", "example": "0x1234....abcd" } } }, "RemoveCustomerRequest": { "type": "object", "required": ["customerId"], "properties": { "customerId": { "type": "string", "description": "The identifier of the customer to remove. Must match the `customerId` used when the customer was registered.", "example": "customer_a1b2c3d4" } } }, "RemoveAddressRequest": { "type": "object", "required": ["customerId", "addressEVM"], "properties": { "customerId": { "type": "string", "description": "The identifier of the customer whose address should be removed.", "example": "customer_a1b2c3d4" }, "addressEVM": { "type": "string", "description": "The EVM wallet address to remove. Must be one of the addresses currently registered for this customer. A customer's last remaining address cannot be removed.", "example": "0x1234....abcd" } } }, "RiskScore": { "type": "object", "required": ["risk", "reviewTimestamp", "reviewType"], "properties": { "risk": { "type": "string", "enum": ["LOW", "MEDIUM", "HIGH", "VERY HIGH"], "description": "The assessed risk level for this address. `LOW` \u2014 address is clear to settle. `MEDIUM` \u2014 address has minor risk signals; settlement proceeds but is flagged. `HIGH` / `VERY HIGH` \u2014 address is blocked from settlement until risk is resolved. Do not execute settlements for customers with HIGH or VERY HIGH risk.", "example": "LOW" }, "reviewTimestamp": { "type": "integer", "description": "Unix timestamp (seconds) when this risk review was completed.", "example": 1711097427 }, "reviewType": { "type": "string", "enum": ["INITIAL", "TOPUP"], "example": "INITIAL", "description": "`INITIAL` \u2014 risk assessment performed at the time of wallet address registration. `TOPUP` \u2014 re-assessment triggered by a top-up activity on the address." }, "reviewComment": { "type": "string", "description": "Optional human-readable note from the risk review. May be absent if no comment was recorded.", "example": "Review comment example" }, "reviewData": { "type": "object", "description": "Additional context captured at the time of the risk review. Present for `TOPUP` reviews; may be absent for `INITIAL` reviews.", "properties": { "fromAddress": { "type": "string", "description": "The source wallet address that triggered the top-up review.", "example": "0x2222222222222222222222222222222222222222" }, "amount": { "type": "string", "description": "The token amount of the specific transaction that triggered the review, in the token's native units.", "example": "10000" }, "totalAmount": { "type": "string", "description": "The cumulative total token amount processed by this address, in the token's native units.", "example": "99999" } } } } }, "RiskEntry": { "type": "object", "required": ["customerId", "addressEVM", "registerTimestamp", "riskScores"], "properties": { "customerId": { "type": "string", "example": "customer_a1b2c3d4", "description": "The customer identifier as registered by the partner." }, "addressEVM": { "type": "string", "example": "0x1111111111111111111111111111111111111111", "description": "The EVM wallet address being monitored." }, "registerTimestamp": { "type": "integer", "example": 1724247261, "description": "Unix timestamp (seconds) when this address was registered for monitoring." }, "riskScores": { "type": "array", "items": { "$ref": "#/components/schemas/RiskScore" }, "description": "Array of risk assessments for this address, ordered from most recent to oldest." } } }, "RiskByIdPayload": { "type": "object", "required": ["addresses"], "properties": { "addresses": { "type": "object", "x-additionalPropertiesName": "0x1111111111111111111111111111111111111111", "additionalProperties": { "$ref": "#/components/schemas/RiskEntry" }, "description": "Array of monitored addresses and their risk history for the requested customer." } } }, "RistByIdResponse": { "type": "object", "required": ["status", "payload"], "properties": { "status": { "type": "string", "example": "ok", "description": "\"ok\" \u2014 indicates the request was processed successfully." }, "payload": { "$ref": "#/components/schemas/RiskByIdPayload", "description": "Response payload containing the customer's address risk data." } } }, "RiskByAddressResponse": { "type": "object", "required": ["status", "payload"], "properties": { "status": { "type": "string", "example": "ok", "description": "\"ok\" \u2014 indicates the request was processed successfully." }, "payload": { "$ref": "#/components/schemas/RiskEntry", "description": "Response payload containing the risk assessment data for the requested address." } } }, "QuoteBeneficiary": { "type": "object", "required": [ "externalTransactionId", "customerId", "customerAddress", "quoteType", "amount" ], "properties": { "externalTransactionId": { "type": "string", "description": "Your own reference ID for this transaction line. Returned unchanged in the quote response and webhook notifications. Use this to correlate BRRR settlement results with your internal records." }, "customerId": { "type": "string", "description": "The identifier of the customer receiving this settlement. Must match a customer previously registered via Register a Customer.", "example": "customer_a1b2c3d4" }, "customerAddress": { "type": "string", "description": "The registered EVM wallet address for this customer. Must be an address already associated with the `customerId` via Register a Customer or Add Address.", "example": "0x1234....abcd" }, "quoteType": { "type": "string", "enum": ["fiat_to_token", "token_to_fiat"], "description": "`fiat_to_token` \u2014 the `amount` field is interpreted as a fiat amount and the quote calculates the equivalent token amount. `token_to_fiat` \u2014 the `amount` field is interpreted as a token amount and the quote calculates the equivalent fiat amount.", "example": "fiat_to_token" }, "amount": { "type": "string", "example": "99.99", "description": "For `fiat_to_token`, the beneficiary's fiat amount (2 decimals). For `token_to_fiat`, the beneficiary's token amount, using the token's native precision (for example, 6 decimals for USDC)." } } }, "SettlementQuoteRequest": { "type": "object", "required": ["currency", "network", "token", "beneficiaries"], "properties": { "currency": { "type": "string", "description": "Fiat settlement currency for all beneficiaries in this quote. Currently supported: EUR, GBP.", "enum": ["EUR", "GBP"], "example": "EUR" }, "network": { "type": "string", "description": "Blockchain network of the source token. All beneficiaries in a single quote must use the same network. Example values: ethereum, polygon, base, arbitrum.", "example": "ethereum" }, "token": { "type": "string", "description": "Contract address of the token to be settled. All beneficiaries share the same input token.", "example": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48" }, "beneficiaries": { "type": "array", "description": "One or more customers to include in this settlement. All beneficiaries must share the same `network` and `token`. Maximum of 100 beneficiaries per quote.", "items": { "$ref": "#/components/schemas/QuoteBeneficiary" } } } }, "SettlementQuoteBeneficiaryResult": { "type": "object", "required": [ "externalTransactionId", "customerId", "customerAddress", "amountIn", "amountSettled", "amountGBPReference" ], "properties": { "externalTransactionId": { "type": "string", "description": "Your reference ID for this transaction line, echoed back from the quote request." }, "customerId": { "type": "string", "description": "The customer identifier, echoed back from the quote request.", "example": "customer_a1b2c3d4" }, "customerAddress": { "type": "string", "description": "The customer's registered EVM address, echoed back from the quote request.", "example": "0x1234....abcd" }, "amountIn": { "type": "string", "example": "171.684232", "description": "Token amount allocated to this beneficiary, in the token's native precision (decimal string)." }, "amountSettled": { "type": "string", "example": "165.23", "description": "Fiat amount (in the requested `currency`) that will be credited to this beneficiary upon settlement completion." }, "amountGBPReference": { "type": "string", "example": "142.99", "description": "GBP-equivalent of this beneficiary\u2019s `amountIn`, calculated at quote time. Provided for cross-currency reference and reporting purposes only \u2014 does not affect settlement amounts." } } }, "SettlementQuotePayload": { "type": "object", "required": [ "quoteId", "timestamp", "confirmDeadline", "currency", "network", "token", "totalAmountIn", "totalAmountSettled", "totalAmountGBPReference", "beneficiaries" ], "properties": { "quoteId": { "type": "string", "format": "uuid", "description": "Unique identifier for this quote.", "example": "79a89717-3690-4db0-b434-39e25df01d55" }, "timestamp": { "type": "integer", "description": "Unix timestamp (seconds) when this quote was generated.", "example": 1724247261 }, "confirmDeadline": { "type": "integer", "description": "Unix timestamp (seconds) after which this quote expires. Quotes must be executed before this deadline \u2014 typically 15 minutes after creation. Attempting to execute an expired quote will return an error.", "example": 1724247261 }, "currency": { "type": "string", "description": "Fiat settlement currency code. Currently supported: EUR, GBP.", "enum": ["EUR", "GBP"], "example": "EUR" }, "network": { "type": "string", "description": "Blockchain network name for the source token. Must match the network used when the customer's address was registered. Example values: ethereum, polygon, base, arbitrum.", "example": "ethereum" }, "token": { "type": "string", "description": "Contract address of the token to be settled. Use the token's canonical contract address on the specified network.", "example": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48" }, "totalAmountIn": { "type": "string", "description": "Total token amount you must send to the `receiveAddress` to execute this settlement. Expressed as a decimal string using the token's native precision (e.g. 6 decimals for USDC). This is the sum of all beneficiary `amountIn` values.", "example": "2811.242231" }, "totalAmountSettled": { "type": "string", "description": "Total fiat amount (in the requested `currency`) that will be distributed across all beneficiaries. Expressed as a decimal string with 2 decimal places.", "example": "2623.34" }, "totalAmountGBPReference": { "type": "string", "description": "The GBP-equivalent of `totalAmountIn`, calculated at the time the quote was generated. Used for regulatory reference and reporting purposes. Not a settlement amount.", "example": "2270.40" }, "beneficiaries": { "type": "array", "description": "Per-beneficiary breakdown of the quote, including individual token and fiat amounts. Mirrors the input beneficiaries in order.", "items": { "$ref": "#/components/schemas/SettlementQuoteBeneficiaryResult" } } } }, "SettlementQuoteResponse": { "type": "object", "required": ["status", "payload"], "properties": { "status": { "type": "string", "example": "ok", "description": "\"ok\" \u2014 indicates the quote was successfully created." }, "payload": { "$ref": "#/components/schemas/SettlementQuotePayload", "description": "The generated settlement quote." } } }, "SettlementQuoteDeniedBeneficiary": { "type": "object", "required": ["customerId", "customerAddress", "reason"], "properties": { "customerId": { "type": "string", "example": "customer_a1b2c3d4", "description": "The customer identifier for the beneficiary that was denied." }, "customerAddress": { "type": "string", "example": "0x1234....abcd", "description": "The EVM wallet address of the denied beneficiary." }, "reason": { "type": "string", "enum": ["NOT_FOUND", "RISK_LEVEL", "RISK_UNAVAILABLE"], "example": "NOT_FOUND", "description": "NOT_FOUND - customer with such ID and address is not found; RISK_LEVEL - customer address risk is above threshold; RISK_UNAVAILABLE - customer address does not have risk assessment complete." } } }, "SettlementQuoteFulfillmentDeniedError": { "type": "object", "required": ["status", "error", "errorCode", "payload"], "properties": { "status": { "type": "string", "example": "error", "description": "\"error\" \u2014 indicates the quote was rejected because one or more beneficiaries could not be fulfilled." }, "error": { "type": "string", "example": "Fulfillment denied for some beneficiaries", "description": "Human-readable description of why the fulfillment was denied." }, "errorCode": { "type": "string", "enum": ["FULFILLMENT_DENIED"], "example": "FULFILLMENT_DENIED", "description": "`FULFILLMENT_DENIED` \u2014 one or more beneficiaries were rejected. See the `payload` array for per-beneficiary reasons." }, "payload": { "type": "array", "items": { "$ref": "#/components/schemas/SettlementQuoteDeniedBeneficiary" }, "description": "Array of denied beneficiary entries, each containing the `customerId`, `customerAddress`, and `reason` for rejection." } } }, "SettlementQuoteBadRequest": { "oneOf": [ { "$ref": "#/components/schemas/Error400" }, { "$ref": "#/components/schemas/SettlementQuoteFulfillmentDeniedError" } ] }, "SettlementExecuteRequest": { "allOf": [ { "$ref": "#/components/schemas/SettlementQuotePayload" }, { "type": "object", "properties": { "ibanId": { "type": "string", "description": "Optional IBAN identifier. When provided, the settlement will be sent to the specified registered IBAN for the beneficiary customer. The IBAN must have been previously registered via Add IBAN to a Customer. If omitted, the settlement uses the partner's default registered IBAN.", "example": "iban_01HXYZ123456" }, "reference": { "type": "string", "maxLength": 140, "description": "Optional payment reference that will appear on the beneficiary's bank statement alongside the SEPA transfer. Maximum 140 characters.", "example": "Invoice #2024-0042" } } } ] }, "SettlementExecutePayload": { "type": "object", "required": [ "quoteId", "timestamp", "receivedDeadline", "network", "token", "receiveAddress", "totalAmountIn", "currency", "totalAmountSettled", "status" ], "properties": { "quoteId": { "type": "string", "format": "uuid", "description": "The unique identifier for this settlement, matching the `quoteId` from the Create Settlement Quote response.", "example": "79a89717-3690-4db0-b434-39e25df01d55" }, "timestamp": { "type": "integer", "description": "Unix timestamp (seconds) when Execute Settlement was called.", "example": 1724247261 }, "receivedDeadline": { "type": "integer", "description": "Unix timestamp (seconds) by which Holyheld must receive the token transfer to the `receiveAddress`. If tokens are not received before this deadline, the settlement transitions to `EXPIRED`.", "example": 1724247561 }, "network": { "type": "string", "description": "The blockchain network on which the token transfer must be sent.", "example": "ethereum" }, "token": { "type": "string", "description": "The contract address of the token to transfer. Send exactly `totalAmountIn` of this token to `receiveAddress`.", "example": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48" }, "receiveAddress": { "type": "string", "description": "The Holyheld wallet address to which you must send the token transfer. This address is unique per settlement \u2014 always use the address returned in this response, not a cached value.", "example": "0x1234....2345" }, "totalAmountIn": { "type": "string", "description": "The exact token amount to send to `receiveAddress`, in the token's native precision. Sending a different amount may result in settlement failure.", "example": "2811.242231" }, "currency": { "type": "string", "description": "The fiat currency code in which beneficiaries will be settled. Currently supported: EUR, GBP.", "enum": ["EUR", "GBP"], "example": "EUR" }, "totalAmountSettled": { "type": "string", "description": "Total fiat amount (in `currency`) to be distributed across all beneficiaries upon successful completion.", "example": "2623.34" }, "status": { "type": "string", "enum": ["CREATED", "CONFIRMED", "EXPIRED", "PROCESSING", "SENT", "FINISHED", "ERROR"], "description": "Current status of the settlement. `CONFIRMED` \u2014 execute was accepted, awaiting your token transfer. `PROCESSING` \u2014 tokens received, fiat disbursement in progress. `SENT` \u2014 fiat sent to beneficiaries. `FINISHED` \u2014 settlement complete. `EXPIRED` \u2014 token transfer not received before `receivedDeadline`. `ERROR` \u2014 settlement failed; contact support.", "example": "CONFIRMED" } } }, "SettlementExecuteResponse": { "type": "object", "required": ["status", "payload"], "properties": { "status": { "type": "string", "example": "ok", "description": "\"ok\" \u2014 indicates the settlement execution was accepted." }, "payload": { "$ref": "#/components/schemas/SettlementExecutePayload", "description": "Details of the confirmed settlement, including the `receiveAddress` and `totalAmountIn` to transfer." } } }, "RatesPayload": { "type": "object", "required": ["rate"], "properties": { "rate": { "type": "string", "example": "0.9175", "description": "Token-to-fiat rate \u2014 How many units of the settlement currency are received per 1 token." } } }, "RatesResponse": { "type": "object", "required": ["status", "payload"], "properties": { "status": { "type": "string", "example": "ok", "description": "\"ok\" \u2014 indicates the request was processed successfully." }, "payload": { "$ref": "#/components/schemas/RatesPayload", "description": "Exchange rate data for the requested token." } } }, "AddIbanRequest": { "type": "object", "required": ["customerId", "iban", "beneficiaryName"], "properties": { "customerId": { "type": "string", "description": "The identifier of the customer this IBAN belongs to. Must match a customer previously registered via Register a Customer.", "example": "customer_a1b2c3d4" }, "iban": { "type": "string", "description": "The IBAN to register for the customer. Must be a valid IBAN in SEPA-reachable countries. Bank name and country are resolved automatically from the IBAN.", "example": "DE89370400440532013000" }, "beneficiaryName": { "type": "string", "maxLength": 140, "description": "The full legal name of the beneficiary as it should appear on bank statements. Must match the account holder name at the destination bank.", "example": "John Doe" }, "bic": { "type": "string", "description": "Optional BIC/SWIFT code. Usually auto-resolved from the IBAN; provide only when automatic resolution fails.", "example": "COBADEFFXXX" } } }, "RemoveIbanRequest": { "type": "object", "required": ["customerId", "ibanId"], "properties": { "customerId": { "type": "string", "description": "The identifier of the customer whose IBAN should be removed.", "example": "customer_a1b2c3d4" }, "ibanId": { "type": "string", "description": "The identifier of the IBAN record to remove, as returned by Add IBAN to a Customer or Get Customer Info.", "example": "iban_01HXYZ123456" } } }, "AddIbanPayload": { "type": "object", "required": ["ibanId", "iban", "beneficiaryName"], "properties": { "ibanId": { "type": "string", "description": "The identifier assigned to this IBAN record. Use this value when referencing the IBAN in Execute Settlement or Remove IBAN from a Customer.", "example": "iban_01HXYZ123456" }, "iban": { "type": "string", "description": "The registered IBAN, echoed back from the request.", "example": "DE89370400440532013000" }, "beneficiaryName": { "type": "string", "description": "The beneficiary name, echoed back from the request.", "example": "John Doe" }, "bankName": { "type": "string", "description": "Bank name resolved from the IBAN.", "example": "Commerzbank" }, "bankCountry": { "type": "string", "description": "ISO 3166-1 alpha-2 country code of the bank, resolved from the IBAN.", "example": "DE" }, "bic": { "type": "string", "description": "BIC/SWIFT code resolved from the IBAN or provided in the request.", "example": "COBADEFFXXX" } } }, "AddIbanResponse": { "type": "object", "required": ["status", "payload"], "properties": { "status": { "type": "string", "example": "ok", "description": "\"ok\" \u2014 indicates the IBAN was registered successfully." }, "payload": { "$ref": "#/components/schemas/AddIbanPayload" } } }, "IbanEntry": { "type": "object", "required": ["ibanId", "iban", "beneficiaryName"], "properties": { "ibanId": { "type": "string", "example": "iban_01HXYZ123456" }, "iban": { "type": "string", "example": "DE89370400440532013000" }, "beneficiaryName": { "type": "string", "example": "John Doe" }, "bankName": { "type": "string", "example": "Commerzbank" }, "bankCountry": { "type": "string", "example": "DE" }, "bic": { "type": "string", "example": "COBADEFFXXX" } } }, "AddressEntry": { "type": "object", "required": ["addressEVM", "registerTimestamp"], "properties": { "addressEVM": { "type": "string", "example": "0x1111111111111111111111111111111111111111" }, "registerTimestamp": { "type": "integer", "example": 1724247261, "description": "Unix timestamp (seconds) when this address was registered." } } }, "CustomerInfoPayload": { "type": "object", "required": ["customerId", "addresses", "ibans"], "properties": { "customerId": { "type": "string", "example": "customer_a1b2c3d4" }, "addresses": { "type": "array", "items": { "$ref": "#/components/schemas/AddressEntry" }, "description": "All EVM addresses currently registered for this customer." }, "ibans": { "type": "array", "items": { "$ref": "#/components/schemas/IbanEntry" }, "description": "All IBANs currently registered for this customer." } } }, "CustomerInfoResponse": { "type": "object", "required": ["status", "payload"], "properties": { "status": { "type": "string", "example": "ok" }, "payload": { "$ref": "#/components/schemas/CustomerInfoPayload" } } }, "OtcQuoteRequest": { "type": "object", "required": ["network", "token", "amount", "amountType"], "properties": { "network": { "type": "string", "description": "Blockchain network of the crypto side of the trade. Example values: ethereum, polygon, base, arbitrum, solana.", "example": "ethereum" }, "token": { "type": "string", "description": "Contract address of the token being sold (for sell-crypto quotes) or received (for buy-eur quotes).", "example": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48" }, "amount": { "type": "string", "description": "Amount to quote. Interpretation depends on `amountType`.", "example": "10000" }, "amountType": { "type": "string", "enum": ["token", "fiat"], "description": "`token` \u2014 `amount` is in the token's native precision. `fiat` \u2014 `amount` is in EUR with 2 decimals.", "example": "fiat" } } }, "OtcQuotePayload": { "type": "object", "required": [ "quoteId", "timestamp", "confirmDeadline", "network", "token", "tokenAmount", "fiatAmount", "rate", "feeAmount" ], "properties": { "quoteId": { "type": "string", "format": "uuid", "description": "Unique identifier for this OTC quote. Pass this to the corresponding Execute endpoint before the confirm deadline.", "example": "79a89717-3690-4db0-b434-39e25df01d55" }, "timestamp": { "type": "integer", "description": "Unix timestamp (seconds) when the quote was generated.", "example": 1724247261 }, "confirmDeadline": { "type": "integer", "description": "Unix timestamp (seconds) after which this quote expires. Typically 10\u201315 minutes after creation.", "example": 1724247861 }, "network": { "type": "string", "example": "ethereum" }, "token": { "type": "string", "example": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48" }, "tokenAmount": { "type": "string", "description": "Token amount in the token's native precision.", "example": "10245.182341" }, "fiatAmount": { "type": "string", "description": "EUR amount with 2 decimals.", "example": "9500.00" }, "rate": { "type": "string", "description": "Applied rate (EUR per 1 token), inclusive of spread.", "example": "0.9272" }, "feeAmount": { "type": "string", "description": "OTC fee in EUR, already reflected in `fiatAmount`.", "example": "47.50" } } }, "OtcQuoteResponse": { "type": "object", "required": ["status", "payload"], "properties": { "status": { "type": "string", "example": "ok" }, "payload": { "$ref": "#/components/schemas/OtcQuotePayload" } } }, "OtcSellCryptoExecuteRequest": { "type": "object", "required": ["quoteId", "ibanId"], "properties": { "quoteId": { "type": "string", "format": "uuid", "description": "The `quoteId` returned by Get Sell Crypto Quote. Must be executed before the quote's `confirmDeadline`.", "example": "79a89717-3690-4db0-b434-39e25df01d55" }, "ibanId": { "type": "string", "description": "The identifier of the IBAN that should receive the EUR proceeds. Must be a registered IBAN on the OTC account.", "example": "iban_01HXYZ123456" }, "reference": { "type": "string", "maxLength": 140, "description": "Optional SEPA payment reference shown on the beneficiary's statement.", "example": "OTC sell 2024-04" } } }, "OtcBuyEurExecuteRequest": { "type": "object", "required": ["quoteId", "ibanId"], "properties": { "quoteId": { "type": "string", "format": "uuid", "description": "The `quoteId` returned by Get Buy EUR Quote. Must be executed before the quote's `confirmDeadline`.", "example": "79a89717-3690-4db0-b434-39e25df01d55" }, "ibanId": { "type": "string", "description": "The identifier of the IBAN that will send the EUR amount to Holyheld's collection account.", "example": "iban_01HXYZ123456" }, "reference": { "type": "string", "maxLength": 140, "description": "Optional reference you will include on the outgoing SEPA transfer.", "example": "OTC buy 2024-04" } } }, "OtcExecutePayload": { "type": "object", "required": ["orderId", "quoteId", "status"], "properties": { "orderId": { "type": "string", "format": "uuid", "description": "Unique identifier for the OTC order. Use this to poll Get OTC Order Status.", "example": "f0e2d8b3-1a4c-4f6e-9d5b-8c7f3e2a1b0d" }, "quoteId": { "type": "string", "format": "uuid", "example": "79a89717-3690-4db0-b434-39e25df01d55" }, "receiveAddress": { "type": "string", "description": "For sell-crypto orders: the wallet address to which the OTC customer must send the token amount. For buy-eur orders: the Holyheld collection IBAN to which the OTC customer must send the EUR amount.", "example": "0x1234....2345" }, "status": { "type": "string", "enum": ["CREATED", "CONFIRMED", "PROCESSING", "SETTLED", "EXPIRED", "ERROR"], "example": "CONFIRMED" } } }, "OtcExecuteResponse": { "type": "object", "required": ["status", "payload"], "properties": { "status": { "type": "string", "example": "ok" }, "payload": { "$ref": "#/components/schemas/OtcExecutePayload" } } }, "OtcOrderStatusPayload": { "type": "object", "required": ["orderId", "status", "network", "token", "tokenAmount", "fiatAmount"], "properties": { "orderId": { "type": "string", "format": "uuid", "example": "f0e2d8b3-1a4c-4f6e-9d5b-8c7f3e2a1b0d" }, "orderType": { "type": "string", "enum": ["SELL_CRYPTO", "BUY_EUR"], "example": "SELL_CRYPTO" }, "status": { "type": "string", "enum": ["CREATED", "CONFIRMED", "PROCESSING", "SETTLED", "EXPIRED", "ERROR"], "example": "PROCESSING" }, "network": { "type": "string", "example": "ethereum" }, "token": { "type": "string", "example": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48" }, "tokenAmount": { "type": "string", "example": "10245.182341" }, "fiatAmount": { "type": "string", "example": "9500.00" }, "ibanId": { "type": "string", "example": "iban_01HXYZ123456" }, "chainTxHash": { "type": "string", "description": "On-chain transaction hash once the crypto leg is broadcast.", "example": "0xabcd..." } } }, "OtcOrderStatusResponse": { "type": "object", "required": ["status", "payload"], "properties": { "status": { "type": "string", "example": "ok" }, "payload": { "$ref": "#/components/schemas/OtcOrderStatusPayload" } } }, "Web3TagInfoRequest": { "type": "object", "required": ["tag"], "properties": { "tag": { "type": "string", "description": "Tag to fetch info for", "example": "SDKTEST" } } }, "Web3TagInfoPayload": { "type": "object", "required": ["tagName"], "properties": { "avatarSrc": { "type": "string", "format": "uri", "nullable": true, "description": "URL of the avatar image (optional)", "example": "https://cdn.example.com/avatar.png" }, "tagName": { "type": "string", "description": "Tag name", "example": "SDKTEST" } } }, "Web3TagInfoResponse": { "type": "object", "required": ["status", "payload"], "properties": { "status": { "type": "string", "example": "ok" }, "payload": { "$ref": "#/components/schemas/Web3TagInfoPayload" } } }, "Web3TokenLookupRequest": { "type": "object", "required": ["address", "network"], "properties": { "address": { "type": "string", "description": "Token contract address (EVM or Solana)", "example": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48" }, "network": { "type": "string", "description": "Blockchain network identifier (e.g. ethereum)", "example": "ethereum" } } }, "Web3ChartRange": { "type": "string", "enum": ["DAY", "WEEK", "MONTH", "YEAR", "ALL"], "description": "Requested history range for chart data.", "example": "DAY" }, "Web3TokenChartRequest": { "allOf": [ { "$ref": "#/components/schemas/Web3TokenLookupRequest" }, { "type": "object", "required": ["type"], "properties": { "type": { "$ref": "#/components/schemas/Web3ChartRange", "description": "Chart range (`DAY`, `WEEK`, `MONTH`, `YEAR`, `ALL`)" } } } ] }, "Web3ChartPoint": { "type": "object", "required": ["ts", "val"], "properties": { "ts": { "type": "integer", "format": "int64", "description": "Timestamp (Unix time, milliseconds)", "example": 1776355249498 }, "val": { "type": "number", "description": "Token price at given timestamp (USD)", "example": 0.999903962763929 } } }, "Web3TokenChartPayload": { "type": "object", "required": ["prices"], "properties": { "prices": { "type": "array", "items": { "$ref": "#/components/schemas/Web3ChartPoint" }, "description": "List of price points over time" } } }, "Web3TokenChartResponse": { "type": "object", "required": ["status", "payload"], "properties": { "status": { "type": "string", "example": "ok" }, "payload": { "$ref": "#/components/schemas/Web3TokenChartPayload" } } }, "Web3PermitData": { "type": "object", "properties": { "hasPermit": { "type": "boolean", "example": true }, "permitVersion": { "type": "string", "nullable": true, "example": "2" }, "permitType": { "type": "string", "nullable": true, "example": "erc2612" } }, "additionalProperties": true }, "Web3TokenMeta": { "type": "object", "properties": { "permitData": { "$ref": "#/components/schemas/Web3PermitData" } }, "additionalProperties": true, "description": "Network-specific token metadata. Additional fields may be present." }, "Web3TokenInfo": { "type": "object", "required": ["address", "name", "symbol", "decimals", "logoUrl", "network", "networkKind"], "properties": { "address": { "type": "string", "example": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", "description": "Token contract or mint address" }, "name": { "type": "string", "example": "USD Coin", "description": "Token name" }, "symbol": { "type": "string", "example": "USDC", "description": "Token symbol" }, "decimals": { "type": "integer", "example": 6, "description": "Token decimals" }, "logoUrl": { "type": "string", "format": "uri", "nullable": true, "description": "URL of token logo" }, "network": { "type": "string", "example": "ethereum", "description": "Network identifier" }, "networkKind": { "type": "string", "example": "evm", "description": "Network type (e.g. `evm`, `solana`)" }, "meta": { "$ref": "#/components/schemas/Web3TokenMeta", "description": "Additional token metadata" }, "price": { "type": "string", "nullable": true, "description": "Current token price in USD", "example": "1" }, "priceChange": { "type": "number", "nullable": true, "description": "Price change percentage", "example": 0.0044225362257688024 } } }, "Web3TokenInfoPayload": { "type": "object", "required": ["token"], "properties": { "token": { "$ref": "#/components/schemas/Web3TokenInfo", "description": "Token data with pricing" } } }, "Web3TokenInfoResponse": { "type": "object", "required": ["status", "payload"], "properties": { "status": { "type": "string", "example": "ok" }, "payload": { "$ref": "#/components/schemas/Web3TokenInfoPayload" } } }, "Web3TokenMarketData": { "type": "object", "required": ["id", "symbol", "name", "logoURL"], "properties": { "id": { "type": "string", "example": "usd-coin", "description": "Internal or external token identifier" }, "symbol": { "type": "string", "example": "USDC", "description": "Token symbol" }, "name": { "type": "string", "example": "USD Coin", "description": "Token name" }, "description": { "type": "string", "nullable": true, "description": "Token description (nullable)" }, "logoURL": { "type": "string", "format": "uri", "nullable": true, "description": "URL of token logo" }, "range24hLow": { "type": "number", "nullable": true, "description": "24h lowest price (nullable)" }, "range24hHigh": { "type": "number", "nullable": true, "description": "24h highest price (nullable)" }, "allTimeLow": { "type": "number", "nullable": true, "description": "All-time lowest price (nullable)" }, "allTimeHigh": { "type": "number", "nullable": true, "description": "All-time highest price (nullable)" }, "allTimeLowChangePercentage": { "type": "number", "nullable": true, "description": "Change from ATL (percentage, nullable)" }, "allTimeHighChangePercentage": { "type": "number", "nullable": true, "description": "Change from ATH (percentage, nullable)" }, "currentPrice": { "type": "number", "nullable": true, "description": "Current token price (nullable)" }, "marketCap": { "type": "number", "nullable": true, "description": "Market capitalization (nullable)" }, "fullyDilutedValuation": { "type": "number", "nullable": true, "description": "Fully diluted valuation (nullable)" }, "totalVolume": { "type": "number", "nullable": true, "description": "Total trading volume (nullable)" }, "priceChangePercentage24H": { "type": "number", "nullable": true, "description": "Price change over last 24h (%) (nullable)" }, "totalSupply": { "type": "number", "nullable": true, "description": "Total token supply (nullable)" }, "maxSupply": { "type": "number", "nullable": true, "description": "Maximum supply (nullable)" }, "circulatingSupply": { "type": "number", "nullable": true, "description": "Circulating supply (nullable)" } } }, "Web3AdditionalTokenData": { "type": "object", "properties": { "dominantColor": { "type": "string", "description": "Dominant color of the token (HEX) or empty string", "example": "#2674C9" } }, "additionalProperties": true }, "Web3TokenMetadataPayload": { "type": "object", "required": ["tokenData", "additionalTokenData"], "properties": { "tokenData": { "$ref": "#/components/schemas/Web3TokenMarketData", "description": "Core token metadata and market data" }, "additionalTokenData": { "$ref": "#/components/schemas/Web3AdditionalTokenData", "description": "Additional token metadata" } } }, "Web3TokenMetadataResponse": { "type": "object", "required": ["status", "payload"], "properties": { "status": { "type": "string", "example": "ok" }, "payload": { "$ref": "#/components/schemas/Web3TokenMetadataPayload" } } }, "Web3BalancesRequest": { "type": "object", "required": ["address"], "properties": { "address": { "type": "string", "description": "EVM wallet address to fetch balances for", "example": "0xD6aEA0120d585E8B4e71C3615B5F34094cA2e6C7" } } }, "Web3BalanceTokenBase": { "type": "object", "required": ["address", "name", "symbol", "decimals", "network"], "properties": { "address": { "type": "string", "description": "Token contract address or identifier" }, "name": { "type": "string", "description": "Token name" }, "symbol": { "type": "string", "description": "Token symbol" }, "decimals": { "type": "integer", "description": "Token decimals" }, "logoUrl": { "type": "string", "format": "uri", "nullable": true, "description": "URL of token logo" }, "network": { "type": "string", "description": "Blockchain network identifier" }, "networkKind": { "type": "string", "nullable": true, "description": "Network family, such as `evm` or `solana`." }, "hasPermit": { "type": "boolean", "nullable": true, "description": "Indicates permit support" }, "meta": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Additional network-specific metadata for the token." }, "groupId": { "type": "string", "nullable": true, "description": "Optional asset grouping key used to cluster related balances." } } }, "Web3EvmBalanceEntry": { "type": "object", "required": ["token", "balance", "price", "priceChange", "priceInEURForTopUp"], "properties": { "token": { "$ref": "#/components/schemas/Web3BalanceTokenBase", "description": "Token metadata" }, "balance": { "type": "string", "description": "Token balance (raw in WEI, not formatted)", "example": "1.701556222222222336" }, "price": { "type": "string", "description": "Current token price in USD", "example": "0.458263" }, "priceChange": { "type": "number", "description": "Price change percentage", "example": 4.818769408395569 }, "priceInEURForTopUp": { "type": "string", "description": "Token price in EUR for top-up calculations", "example": "0.3824052731302210537689" }, "groupId": { "type": "string", "nullable": true, "description": "Optional token grouping identifier" } } }, "Web3EvmBalancesPayload": { "type": "object", "required": ["tokens", "totalBalance", "totalPriceChange"], "properties": { "tokens": { "type": "array", "items": { "$ref": "#/components/schemas/Web3EvmBalanceEntry" }, "description": "List of token balances" }, "totalBalance": { "type": "string", "description": "Total portfolio value (in EUR)", "example": "87.80" }, "totalPriceChange": { "type": "number", "description": "Overall price change", "example": -0.117798787209793 } } }, "Web3EvmBalancesResponse": { "type": "object", "required": ["status", "payload"], "properties": { "status": { "type": "string", "example": "ok" }, "payload": { "$ref": "#/components/schemas/Web3EvmBalancesPayload" } } }, "Web3SolanaMeta": { "type": "object", "properties": { "tokenProgramId": { "type": "string", "description": "Solana token program identifier", "example": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA" } }, "additionalProperties": true }, "Web3SolanaBalanceEntry": { "type": "object", "required": [ "address", "name", "symbol", "decimals", "network", "networkKind", "balance", "price", "priceInEURForTopUp", "priceChange" ], "properties": { "address": { "type": "string", "example": "So11111111111111111111111111111111111111112", "description": "Token mint address" }, "name": { "type": "string", "example": "Solana", "description": "Token name" }, "symbol": { "type": "string", "example": "SOL", "description": "Token symbol" }, "decimals": { "type": "integer", "example": 9, "description": "Token decimals" }, "logoUrl": { "type": "string", "format": "uri", "nullable": true, "description": "URL of token logo" }, "network": { "type": "string", "example": "solana-mainnet", "description": "Network identifier (e.g. solana-mainnet)" }, "networkKind": { "type": "string", "example": "solana", "description": "Blockchain type" }, "meta": { "$ref": "#/components/schemas/Web3SolanaMeta", "description": "Additional token metadata (structure may vary)" }, "balance": { "type": "string", "description": "Token balance (raw, in base units)", "example": "1000000000" }, "price": { "type": "string", "description": "Current token price in USD", "example": "150.25" }, "priceInEURForTopUp": { "type": "string", "description": "Token price in EUR for offramp calculations", "example": "130.10" }, "priceChange": { "type": "number", "description": "Price change percentage", "example": 2.15 } } }, "Web3SolanaBalancesPayload": { "type": "object", "required": ["tokens", "totalBalance", "totalPriceChange"], "properties": { "tokens": { "type": "array", "items": { "$ref": "#/components/schemas/Web3SolanaBalanceEntry" }, "description": "List of token balances" }, "totalBalance": { "type": "string", "description": "Total wallet value (in EUR)", "example": "130.10" }, "totalPriceChange": { "type": "number", "description": "Overall price change", "example": 1.25 } } }, "Web3SolanaBalancesResponse": { "type": "object", "required": ["status", "payload"], "properties": { "status": { "type": "string", "example": "ok" }, "payload": { "$ref": "#/components/schemas/Web3SolanaBalancesPayload" } } }, "Web3SolanaPriorityFeePayload": { "type": "object", "required": ["priorityFee"], "properties": { "priorityFee": { "type": "integer", "description": "Recommended priority fee (in lamports) for Solana transactions", "example": 5000 } } }, "Web3SolanaPriorityFeeResponse": { "type": "object", "required": ["status", "payload"], "properties": { "status": { "type": "string", "example": "ok" }, "payload": { "$ref": "#/components/schemas/Web3SolanaPriorityFeePayload" } } }, "CardTokenRef": { "type": "object", "required": ["address", "decimals"], "properties": { "address": { "type": "string", "example": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", "description": "Token contract address" }, "decimals": { "type": "integer", "example": 6, "description": "Number of decimals the token uses" } } }, "CardPermitData": { "type": "object", "required": ["signature", "deadline", "nonce"], "properties": { "signature": { "type": "string", "example": "0xabc123" }, "deadline": { "type": "integer", "format": "int64", "example": 1724250000 }, "nonce": { "type": "integer", "example": 0 } } }, "CardEvmTransferData": { "type": "object", "properties": { "data": { "type": "string", "description": "Calldata for the swap" }, "allowanceTarget": { "type": "string", "description": "Address to approve allowance to" }, "to": { "type": "string", "description": "Recipient address for the swap" }, "value": { "type": "string", "description": "Value to send with the transaction (in wei)" }, "buyAmount": { "type": "string", "description": "Amount of tokens in base units" }, "sellAmount": { "type": "string", "description": "Amount of tokens in base units" }, "slippage": { "type": "string", "description": "Allowed slippage percentage" }, "swapperName": { "type": "string", "description": "Name of the swapper (e.g., \"1inch\")" } }, "additionalProperties": true }, "CardSolanaTransferData": { "type": "object", "properties": { "buyAmount": { "type": "string", "description": "Expected amount of destination token (in base units)" }, "sellAmount": { "type": "string", "description": "Amount of source token used (in base units)" }, "guaranteedBuyAmount": { "type": "string", "description": "Guaranteed minimum amount of destination token (in base units)" }, "transaction": { "type": "string", "description": "Data for offramp trasaction" }, "swapType": { "type": "string", "enum": ["in", "out"], "description": "Swap direction: `\"in\"` or `\"out\"`" } }, "additionalProperties": true }, "CardAmountQuotePayload": { "type": "object", "required": ["tokenAmount", "EURAmount"], "properties": { "tokenAmount": { "type": "string", "example": "10", "description": "Estimated token amount in formatted units." }, "EURAmount": { "type": "string", "example": "18032.06", "description": "Estimated or echoed EUR amount in formatted units." } } }, "CardAmountQuoteResponse": { "type": "object", "required": ["status", "payload"], "properties": { "status": { "type": "string", "example": "ok" }, "payload": { "$ref": "#/components/schemas/CardAmountQuotePayload" } } }, "CardEvmEstimatePayload": { "type": "object", "required": ["transferData", "tokenAmount", "EURAmount"], "properties": { "transferData": { "$ref": "#/components/schemas/CardEvmTransferData", "description": "Data for offramp transaction" }, "tokenAmount": { "type": "string", "description": "Amount of tokens spent in the conversion" }, "EURAmount": { "type": "string", "description": "Estimated EUR amount to be received" } } }, "CardEvmEstimateResponse": { "type": "object", "required": ["status", "payload"], "properties": { "status": { "type": "string", "example": "ok" }, "payload": { "$ref": "#/components/schemas/CardEvmEstimatePayload" } } }, "CardSolanaEstimatePayload": { "type": "object", "required": ["transferData", "tokenAmount", "EURAmount"], "properties": { "transferData": { "$ref": "#/components/schemas/CardSolanaTransferData", "description": "Data for offramp transaction" }, "tokenAmount": { "type": "string", "description": "Amount of source token provided" }, "EURAmount": { "type": "string", "description": "Estimated EUR amount (formatted, e.g. \"12.34\")" } } }, "CardSolanaEstimateResponse": { "type": "object", "required": ["status", "payload"], "properties": { "status": { "type": "string", "example": "ok" }, "payload": { "$ref": "#/components/schemas/CardSolanaEstimatePayload" } } }, "CardConfigResponse": { "type": "object", "required": ["status", "payload"], "properties": { "status": { "type": "string", "example": "ok" }, "payload": { "type": "object", "required": ["references"], "properties": { "references": { "type": "object", "additionalProperties": true, "description": "Reference configuration data" } } } } }, "CardAddressCheckRequest": { "type": "object", "required": ["address"], "properties": { "address": { "type": "string", "example": "0x45FB5699C0BFFC5e7D7F0c4947417833cc0623aa", "description": "Wallet address (EVM or Solana format)" } } }, "CardAddressCheckResponse": { "type": "object", "required": ["status", "payload"], "properties": { "status": { "type": "string", "example": "ok" }, "payload": { "type": "object", "required": ["isTopupAllowed", "isOnRampAllowed"], "properties": { "isTopupAllowed": { "type": "boolean", "example": true, "description": "Indicates if the address can be used for top-up (offramp)" }, "isOnRampAllowed": { "type": "boolean", "example": true, "description": "Indicates if the address can be used for on-ramp" } } } } }, "CardBuyingRateResponse": { "type": "object", "required": ["status", "payload"], "properties": { "status": { "type": "string", "example": "ok" }, "payload": { "type": "object", "required": ["code", "direction", "rate", "quote", "timestamp"], "properties": { "code": { "type": "string", "example": "EUR", "description": "Fiat currency code, echoed from the request." }, "direction": { "type": "string", "enum": ["buy", "sell"], "example": "buy", "description": "`buy` or `sell`, echoed from the request." }, "rate": { "type": "string", "example": "0.9210", "description": "EUR per 1 USD (decimal string)." }, "quote": { "type": "object", "properties": { "base": { "type": "string", "example": "USD" }, "counter": { "type": "string", "example": "EUR" } }, "description": "`{ base, counter }` naming the currency pair for clarity." }, "timestamp": { "type": "integer", "format": "int64", "example": 1724247261, "description": "Unix timestamp (seconds) when this rate was generated." } } } } }, "CardTagHashRequest": { "type": "object", "required": ["tag"], "properties": { "tag": { "type": "string", "example": "SDKTEST", "description": "Tag to generate identifier for" } } }, "CardTagHashResponse": { "type": "object", "required": ["status", "payload"], "properties": { "status": { "type": "string", "example": "ok" }, "payload": { "type": "object", "required": ["topupHash"], "properties": { "topupHash": { "type": "string", "example": "0xabc123def456", "description": "Special tag identifier used in offramp processing" } } } } }, "CardEvmConvertRequest": { "type": "object", "required": ["toToken", "fromToken", "fromAddress", "destReceived", "network"], "properties": { "toToken": { "$ref": "#/components/schemas/CardTokenRef", "description": "Information about the token to receive (buy token)" }, "fromToken": { "$ref": "#/components/schemas/CardTokenRef", "description": "Information about the token to spend (sell token)" }, "tokenAmount": { "type": "string", "description": "Amount of tokens to sell" }, "eurAmount": { "type": "string", "description": "Amount of EUR to sell" }, "fromAddress": { "type": "string", "description": "User's wallet address initiating the conversion" }, "destReceived": { "type": "string", "description": "Destination address" }, "network": { "type": "string", "example": "ethereum", "description": "EVM-compatible network (e.g., `ethereum`, `polygon`, etc.)" } }, "additionalProperties": true }, "CardSolanaConvertRequest": { "type": "object", "required": ["toToken", "fromToken", "fromAddress", "network"], "properties": { "toToken": { "$ref": "#/components/schemas/CardTokenRef", "description": "Target token details for conversion" }, "fromToken": { "$ref": "#/components/schemas/CardTokenRef", "description": "Source token details for conversion" }, "tokenAmount": { "type": "string", "description": "Amount of source token to convert" }, "eurAmount": { "type": "string", "description": "EUR amount as decimal string (e.g., `\"100.00\"`)" }, "fromAddress": { "type": "string", "description": "Sender's Solana wallet address" }, "network": { "type": "string", "example": "solana-mainnet", "description": "Solana network identifier (e.g. `solana-mainnet`)" } }, "additionalProperties": true }, "CardTransactionDataRequest": { "type": "object", "required": ["amountType", "fromToken", "fromAddress", "network"], "properties": { "amountType": { "type": "string", "enum": ["eur", "token"], "description": "`eur` \u2014 use `eurAmount`. `token` \u2014 use `tokenAmount`." }, "eurAmount": { "type": "string", "description": "EUR amount with 2 decimals. Required when `amountType = eur`." }, "tokenAmount": { "type": "string", "description": "Token amount in the token's native precision. Required when `amountType = token`." }, "fromToken": { "$ref": "#/components/schemas/CardTokenRef", "description": "`{ address, decimals }` of the token being spent." }, "fromAddress": { "type": "string", "description": "Customer's wallet address initiating the transaction." }, "network": { "type": "string", "example": "ethereum", "description": "EVM network identifier (e.g. `ethereum`, `polygon`, `base`)." }, "tagHash": { "type": "string", "description": "One-time Tag Hash from Get Tag Hash. Required when sending to a third party's Holyheld Tag (rather than the sender's own card)." } } }, "CardTransactionDataResponse": { "type": "object", "required": ["status", "payload"], "properties": { "status": { "type": "string", "example": "ok" }, "payload": { "type": "object", "required": ["transactionData", "tokenAmount", "EURAmount"], "properties": { "transactionData": { "type": "object", "required": ["to", "data", "value"], "properties": { "to": { "type": "string", "description": "Contract address to which the transaction must be sent" }, "data": { "type": "string", "description": "Hex-encoded calldata" }, "value": { "type": "string", "description": "Native value to send with the transaction (in wei)" }, "allowanceTarget": { "type": "string", "description": "Address the customer must approve allowance for" } }, "description": "Calldata bundle ready for wallet submission." }, "tokenAmount": { "type": "string", "description": "Token amount that will be spent (echoed/derived)." }, "EURAmount": { "type": "string", "description": "EUR amount that will be credited (echoed/derived)." } } } } }, "CardGaslessRequest": { "type": "object", "required": ["amountType", "fromToken", "fromAddress", "network", "permit"], "properties": { "amountType": { "type": "string", "enum": ["eur", "token"], "description": "`eur` or `token`." }, "eurAmount": { "type": "string", "description": "EUR amount with 2 decimals. Required when `amountType = eur`." }, "tokenAmount": { "type": "string", "description": "Token amount in native precision. Required when `amountType = token`." }, "fromToken": { "$ref": "#/components/schemas/CardTokenRef", "description": "`{ address, decimals }` of the token being spent. Token must support EIP-2612 permit or Permit2 on the network." }, "fromAddress": { "type": "string", "description": "Customer's wallet address the gasless transaction will be executed on behalf of." }, "network": { "type": "string", "description": "EVM network identifier." }, "permit": { "$ref": "#/components/schemas/CardPermitData", "description": "Customer-signed permit/Permit2 data authorising Holyheld to move the token amount. `{ signature, deadline, nonce }`." }, "tagHash": { "type": "string", "description": "One-time Tag Hash from Get Tag Hash. Required when sending to a third party's Holyheld Tag." } } }, "CardGaslessResponse": { "type": "object", "required": ["status", "payload"], "properties": { "status": { "type": "string", "example": "ok" }, "payload": { "type": "object", "required": ["HHTXID", "tokenAmount", "EURAmount"], "properties": { "HHTXID": { "type": "string", "example": "F0E2D8B3-1A4C-4F6E-9D5B-8C7F3E2A1B0D", "description": "Holyheld transaction identifier. Use this with Get Offramp Status." }, "tokenAmount": { "type": "string", "description": "Token amount that will be spent (echoed/derived)." }, "EURAmount": { "type": "string", "description": "EUR amount that will be credited." } } } } }, "CardSepaFeeRequest": { "type": "object", "required": ["iban", "eurAmount"], "properties": { "iban": { "type": "string", "example": "DE89370400440532013000", "description": "Destination IBAN. Must be SEPA-reachable." }, "eurAmount": { "type": "string", "example": "500.00", "description": "EUR amount to transfer, with 2 decimals." } } }, "CardSepaFeeResponse": { "type": "object", "required": ["status", "payload"], "properties": { "status": { "type": "string", "example": "ok" }, "payload": { "type": "object", "required": ["feeAmount", "netAmount", "currency", "bankName", "bankCountry"], "properties": { "feeAmount": { "type": "string", "example": "0.35", "description": "Estimated SEPA fee in EUR." }, "netAmount": { "type": "string", "example": "499.65", "description": "EUR amount that will arrive at the destination IBAN." }, "currency": { "type": "string", "example": "EUR", "description": "Always `EUR` for SEPA transfers." }, "bankName": { "type": "string", "example": "Commerzbank", "description": "Bank name resolved from the IBAN." }, "bankCountry": { "type": "string", "example": "DE", "description": "ISO 3166-1 alpha-2 country code resolved from the IBAN." } } } } }, "CardCreateSepaTransferRequest": { "type": "object", "required": ["iban", "beneficiaryName", "eurAmount", "feeAmount"], "properties": { "iban": { "type": "string", "example": "DE89370400440532013000", "description": "Destination IBAN. Must be SEPA-reachable. Bank name/country auto-resolved." }, "beneficiaryName": { "type": "string", "example": "John Doe", "description": "Full legal name of the recipient as it appears on the bank account. Max 140." }, "eurAmount": { "type": "string", "example": "500.00", "description": "Exact EUR amount (gross \u2014 fee-inclusive) being transferred. 2 decimals." }, "feeAmount": { "type": "string", "example": "0.35", "description": "SEPA fee in EUR, as returned by [Estimate SEPA Fee](/api/card-api/offramp-sepa-transfers/card-estimate-sepa-fee). Call that method first and pass its result here." }, "reference": { "type": "string", "example": "Invoice #2024-0042", "description": "Payment reference shown on the recipient's statement. Max 140 characters." } } }, "CardCreateSepaTransferResponse": { "type": "object", "required": ["status", "payload"], "properties": { "status": { "type": "string", "example": "ok" }, "payload": { "type": "object", "required": ["tagHash", "expiresAt", "bankName", "bankCountry"], "properties": { "tagHash": { "type": "string", "example": "0xabc123def456", "description": "One-time Tag Hash. Pass this as the `tagHash` field to Get Transaction Data or Execute Gasless Transaction." }, "expiresAt": { "type": "integer", "format": "int64", "example": 1724250000, "description": "Unix timestamp (seconds) after which the tagHash is no longer usable." }, "bankName": { "type": "string", "example": "Commerzbank", "description": "Resolved bank name." }, "bankCountry": { "type": "string", "example": "DE", "description": "Resolved ISO 3166-1 alpha-2 country code." } } } } }, "CardOfframpStatusRequest": { "type": "object", "properties": { "tagHash": { "type": "string", "description": "Tag Hash returned by Get Tag Hash or Create SEPA Transfer." }, "chainId": { "type": "integer", "example": 1, "description": "EVM chain ID of the broadcast transaction." }, "txHash": { "type": "string", "description": "Transaction hash on the specified chain." }, "HHTXID": { "type": "string", "description": "Holyheld transaction ID returned by Execute Gasless Transaction." } }, "additionalProperties": false }, "CardOfframpStatusResponse": { "type": "object", "required": ["status", "payload"], "properties": { "status": { "type": "string", "example": "ok" }, "payload": { "type": "object", "required": ["state", "updatedAt"], "properties": { "state": { "type": "string", "enum": [ "WAITFORTX", "QUEUED", "PENDING", "EXECUTING", "SUCCESS", "CANCELLED", "FAILED" ], "example": "PENDING", "description": "`WAITFORTX` \u2014 on-chain transaction not yet observed. `QUEUED` \u2014 gasless execution waiting to be broadcast. `PENDING` \u2014 waiting for bank execution. `EXECUTING` \u2014 bank execution in progress. `SUCCESS`, `CANCELLED`, `FAILED`." }, "HHTXID": { "type": "string", "description": "Holyheld transaction ID (always populated once known)." }, "chainTxHash": { "type": "string", "description": "On-chain transaction hash once observed." }, "chainId": { "type": "integer", "description": "EVM chain ID of the transaction." }, "tokenAmount": { "type": "string", "description": "Token amount sent." }, "EURAmount": { "type": "string", "description": "EUR amount credited." }, "destination": { "type": "object", "additionalProperties": true, "description": "`{ type: \"CARD\" | \"SEPA\" | \"TAG\", ...details }` indicating where the EUR landed." }, "updatedAt": { "type": "integer", "format": "int64", "description": "Unix timestamp (seconds) of the last state update." } } } } }, "CardOnrampTokensRequest": { "type": "object", "required": ["network"], "properties": { "filter": { "type": "string", "example": "usd", "description": "Search query (part of token name, symbol, or address)" }, "network": { "type": "string", "example": "ethereum", "description": "EVM network identifier (e.g. ethereum, arbitrum)" } } }, "CardOnrampAsset": { "type": "object", "required": ["address", "name", "symbol", "decimals", "network", "priceUSD", "priceChange"], "properties": { "address": { "type": "string", "description": "Token contract address" }, "name": { "type": "string", "description": "Token name" }, "symbol": { "type": "string", "description": "Token symbol" }, "decimals": { "type": "integer", "description": "Token decimals" }, "logoUrl": { "type": "string", "nullable": true, "description": "URL of token logo" }, "hasPermit": { "type": "boolean", "nullable": true, "description": "Indicates permit support (ERC-20)" }, "permitVersion": { "type": "string", "nullable": true, "description": "Permit version (optional)" }, "permitType": { "type": "string", "nullable": true, "description": "Permit type (optional)" }, "network": { "type": "string", "description": "Network identifier" }, "priceUSD": { "type": "string", "description": "Current token price in USD" }, "priceChange": { "type": "number", "description": "Price change percentage" } } }, "CardOnrampTokensResponse": { "type": "object", "required": ["status", "payload"], "properties": { "status": { "type": "string", "example": "ok" }, "payload": { "type": "object", "required": ["assets", "popular"], "properties": { "assets": { "type": "array", "items": { "$ref": "#/components/schemas/CardOnrampAsset" }, "description": "List of tokens matching the filter" }, "popular": { "type": "array", "items": { "$ref": "#/components/schemas/CardOnrampAsset" }, "description": "List of popular tokens for the network" } } } } }, "CardOnrampTokenAmountRequest": { "type": "object", "required": ["fromToken", "EURAmount", "network"], "properties": { "fromToken": { "type": "string", "description": "Token contract address" }, "EURAmount": { "type": "string", "description": "Amount in EUR to convert" }, "network": { "type": "string", "description": "Blockchain network identifier (e.g. ethereum, optimism)" } } }, "CardOnrampEurAmountRequest": { "type": "object", "required": ["fromToken", "tokenAmount", "network"], "properties": { "fromToken": { "type": "string", "description": "Token contract address" }, "tokenAmount": { "type": "string", "description": "Amount of tokens (formatted with decimals)" }, "network": { "type": "string", "description": "Blockchain network identifier (e.g. ethereum, optimism)" } } }, "CardOnrampEstimateRequest": { "type": "object", "required": ["network", "token", "amountEUR", "beneficiaryAddress"], "properties": { "network": { "type": "string", "description": "Blockchain network identifier (e.g. ethereum, optimism)" }, "token": { "type": "string", "description": "Token contract address" }, "amountEUR": { "type": "string", "description": "Amount in EUR to spend" }, "beneficiaryAddress": { "type": "string", "description": "Recipient wallet address" } } }, "CardOnrampEstimateResponse": { "type": "object", "required": ["status", "payload"], "properties": { "status": { "type": "string", "example": "ok" }, "payload": { "type": "object", "required": ["feeEUR", "expectedAmount"], "properties": { "feeEUR": { "type": "string", "description": "Estimated fee in EUR" }, "expectedAmount": { "type": "string", "description": "Expected token amount (raw in WEI, not formatted)" } } } } }, "CardOnrampExecuteRequest": { "type": "object", "required": ["chainId", "token", "amountEUR", "beneficiaryAddress"], "properties": { "chainId": { "type": "integer", "example": 1, "description": "Blockchain network ID (EVM-compatible)" }, "token": { "type": "string", "description": "Token contract address" }, "amountEUR": { "type": "string", "description": "Amount in EUR to spend" }, "beneficiaryAddress": { "type": "string", "description": "Recipient wallet address" } } }, "CardOnrampExecuteResponse": { "type": "object", "required": ["status", "payload"], "properties": { "status": { "type": "string", "example": "ok" }, "payload": { "type": "object", "required": ["HHTXID", "feeEUR", "expectedAmount"], "properties": { "HHTXID": { "type": "string", "description": "Holyheld transaction identifier. GUID-format, uppercase. Use with Get Onramp Status to poll status." }, "feeEUR": { "type": "string", "description": "Fee amount in EUR" }, "expectedAmount": { "type": "string", "description": "Expected token amount (raw in WEI, not formatted)" } } } } }, "CardOnrampStatusRequest": { "type": "object", "required": ["HHTXID"], "properties": { "HHTXID": { "type": "string", "example": "5721128E-DDB3-4132-9791-39D91D022D61", "description": "Holyheld transaction identifier returned by Execute Onramp. GUID-format." } } }, "CardOnrampStatusResponse": { "type": "object", "required": ["status", "payload"], "properties": { "status": { "type": "string", "example": "ok" }, "payload": { "type": "object", "required": ["status"], "properties": { "status": { "type": "string", "enum": ["not_approved", "approved", "success", "failed", "declined"], "description": "Current request status" }, "reason": { "type": "string", "nullable": true, "description": "Failure reason (present only if status = `failed`)" }, "txHash": { "type": "string", "nullable": true, "description": "Blockchain transaction hash (present if successful)" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ], "paths": { "/api/v4/partner/customer/register": { "post": { "summary": "Register a customer", "description": "Register a customer and associate their EVM wallet address. Only customers with a completed KYC (`GREEN`) status can be registered.", "operationId": "register-customer", "tags": ["Partner Onboarding"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterCustomerRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusOk" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" }, "examples": { "customerExists": { "value": { "status": "error", "error": "Customer ID is already registered", "errorCode": "CUSTOMER_EXISTS" } }, "addressExists": { "value": { "status": "error", "error": "Customer address is already registered", "errorCode": "ADDRESS_EXISTS" } }, "kycNotCompleted": { "value": { "status": "error", "error": "Customer KYC was not completed successfully", "errorCode": "KYC_NOT_COMPLETED" } } } } } }, "403": { "description": "Forbidden (missing/invalid API key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403" }, "examples": { "accessDenied": { "value": { "status": "error", "error": "Access denied", "errorCode": "ACCESS_DENIED" } } } } } }, "429": { "description": "Too Many Requests", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying the request.", "schema": { "type": "integer", "example": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" }, "examples": { "rateLimitExceeded": { "value": { "status": "error", "error": "Too many requests", "errorCode": "TOO_MANY_REQUESTS" } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" }, "examples": { "internalError": { "value": { "status": "error", "error": "Internal server error", "errorCode": "INTERNAL_ERROR" } } } } } } } } }, "/api/v4/partner/customer/add-address": { "post": { "summary": "Add address to a customer", "description": "Add an additional EVM wallet address to an existing customer.", "operationId": "add-address-to-customer", "tags": ["Partner Onboarding"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterCustomerRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusOk" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" }, "examples": { "addressExists": { "value": { "status": "error", "error": "Customer address is already registered", "errorCode": "ADDRESS_EXISTS" } }, "kycNotCompleted": { "value": { "status": "error", "error": "Customer KYC was not completed successfully", "errorCode": "KYC_NOT_COMPLETED" } } } } } }, "403": { "description": "Forbidden (missing/invalid API key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403" }, "examples": { "accessDenied": { "value": { "status": "error", "error": "Access denied", "errorCode": "ACCESS_DENIED" } } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error404" }, "examples": { "customerNotFound": { "value": { "status": "error", "error": "Customer ID {id} not found", "errorCode": "CUSTOMER_NOT_FOUND" } } } } } }, "429": { "description": "Too Many Requests", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying the request.", "schema": { "type": "integer", "example": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" }, "examples": { "rateLimitExceeded": { "value": { "status": "error", "error": "Too many requests", "errorCode": "TOO_MANY_REQUESTS" } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" }, "examples": { "internalError": { "value": { "status": "error", "error": "Internal server error", "errorCode": "INTERNAL_ERROR" } } } } } } } } }, "/api/v4/partner/customer/remove": { "post": { "summary": "Remove a customer", "description": "Remove a customer and all associated wallet addresses from monitoring.", "operationId": "remove-customer", "tags": ["Partner Offboarding"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveCustomerRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusOk" } } } }, "403": { "description": "Forbidden (missing/invalid API key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403" }, "examples": { "accessDenied": { "value": { "status": "error", "error": "Access denied", "errorCode": "ACCESS_DENIED" } } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error404" }, "examples": { "customerNotFound": { "value": { "status": "error", "error": "Customer ID {id} not found", "errorCode": "CUSTOMER_NOT_FOUND" } } } } } }, "429": { "description": "Too Many Requests", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying the request.", "schema": { "type": "integer", "example": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" }, "examples": { "rateLimitExceeded": { "value": { "status": "error", "error": "Too many requests", "errorCode": "TOO_MANY_REQUESTS" } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" }, "examples": { "internalError": { "value": { "status": "error", "error": "Internal server error", "errorCode": "INTERNAL_ERROR" } } } } } } } } }, "/api/v4/partner/customer/add-iban": { "post": { "summary": "Add IBAN to a customer", "description": "Register a SEPA IBAN for an existing customer. Bank name and country are auto-resolved from the IBAN. Multiple IBANs can be attached to a single customer; when executing a settlement you can route funds to a specific IBAN by its `ibanId`.", "operationId": "add-iban-to-customer", "tags": ["Partner IBAN"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddIbanRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddIbanResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" }, "examples": { "invalidIban": { "value": { "status": "error", "error": "IBAN is not valid or not SEPA-reachable", "errorCode": "INVALID_IBAN" } }, "ibanExists": { "value": { "status": "error", "error": "IBAN already registered for this customer", "errorCode": "IBAN_EXISTS" } } } } } }, "403": { "description": "Forbidden (missing/invalid API key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error404" }, "examples": { "customerNotFound": { "value": { "status": "error", "error": "Customer ID {id} not found", "errorCode": "CUSTOMER_NOT_FOUND" } } } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } } } } }, "/api/v4/partner/customer/remove-iban": { "post": { "summary": "Remove IBAN from a customer", "description": "Remove a previously registered IBAN from a customer. Any in-flight settlements targeting this IBAN continue; new settlements can no longer reference the removed `ibanId`.", "operationId": "remove-iban-from-customer", "tags": ["Partner IBAN"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveIbanRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusOk" } } } }, "403": { "description": "Forbidden (missing/invalid API key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error404" }, "examples": { "ibanNotFound": { "value": { "status": "error", "error": "IBAN not found for this customer", "errorCode": "IBAN_NOT_FOUND" } } } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } } } } }, "/api/v4/partner/customer/info/{customerId}": { "get": { "summary": "Get customer info", "description": "Retrieve a customer's registered EVM addresses and IBANs in a single call. Useful for reconciling local state with what Holyheld currently has on file.", "operationId": "get-customer-info", "tags": ["Partner Customer Info"], "parameters": [ { "name": "customerId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerInfoResponse" } } } }, "403": { "description": "Forbidden (missing/invalid API key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error404" }, "examples": { "customerNotFound": { "value": { "status": "error", "error": "Customer ID {id} not found", "errorCode": "CUSTOMER_NOT_FOUND" } } } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } } } } }, "/api/v4/partner/customer/remove-address": { "post": { "summary": "Remove an address", "description": "Remove a specific wallet address from monitoring.", "operationId": "remove-address", "tags": ["Partner Offboarding"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveAddressRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusOk" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" }, "example": { "status": "error", "errorCode": "CUSTOMER_LAST_ADDRESS_REMOVAL_FORBIDDEN", "error": "Can't remove last address of customer (remove entire customer instead)" }, "examples": { "addressNotFound": { "value": { "status": "error", "error": "Address not found for this customer", "errorCode": "ADDRESS_NOT_FOUND" } } } } } }, "403": { "description": "Forbidden (missing/invalid API key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403" }, "examples": { "accessDenied": { "value": { "status": "error", "error": "Access denied", "errorCode": "ACCESS_DENIED" } } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error404" }, "examples": { "customerNotFound": { "value": { "status": "error", "error": "Customer ID {id} not found", "errorCode": "CUSTOMER_NOT_FOUND" } }, "addressNotFound": { "value": { "status": "error", "error": "Address {address} not found", "errorCode": "ADDRESS_NOT_FOUND" } } } } } }, "429": { "description": "Too Many Requests", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying the request.", "schema": { "type": "integer", "example": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" }, "examples": { "rateLimitExceeded": { "value": { "status": "error", "error": "Too many requests", "errorCode": "TOO_MANY_REQUESTS" } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" }, "examples": { "internalError": { "value": { "status": "error", "error": "Internal server error", "errorCode": "INTERNAL_ERROR" } } } } } } } } }, "/api/v4/partner/risk/by-customer/{customerId}": { "get": { "summary": "Get risk by customer ID", "description": "Retrieve risk history for all wallet addresses associated with a customer.", "operationId": "get-risk-by-customer-id", "tags": ["Partner Risk"], "parameters": [ { "name": "customerId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RistByIdResponse" } } } }, "403": { "description": "Forbidden (missing/invalid API key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403" }, "examples": { "accessDenied": { "value": { "status": "error", "error": "Access denied", "errorCode": "ACCESS_DENIED" } } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error404" }, "examples": { "customerNotFound": { "value": { "status": "error", "error": "Customer ID {id} not found", "errorCode": "CUSTOMER_NOT_FOUND" } } } } } }, "429": { "description": "Too Many Requests", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying the request.", "schema": { "type": "integer", "example": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" }, "examples": { "rateLimitExceeded": { "value": { "status": "error", "error": "Too many requests", "errorCode": "TOO_MANY_REQUESTS" } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" }, "examples": { "kycNotCompleted": { "value": { "status": "error", "error": "Customer KYC was not completed successfully", "errorCode": "KYC_NOT_COMPLETED" } } } } } } } } }, "/api/v4/partner/risk/by-address/{addressEVM}": { "get": { "summary": "Get risk by address", "description": "Retrieve risk status for a specific wallet address.", "operationId": "get-risk-by-address", "tags": ["Partner Risk"], "parameters": [ { "name": "addressEVM", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RiskByAddressResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" }, "examples": { "addressNotFound": { "value": { "status": "error", "error": "Address not registered", "errorCode": "ADDRESS_NOT_FOUND" } } } } } }, "403": { "description": "Forbidden (missing/invalid API key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403" }, "examples": { "accessDenied": { "value": { "status": "error", "error": "Access denied", "errorCode": "ACCESS_DENIED" } } } } } }, "429": { "description": "Too Many Requests", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying the request.", "schema": { "type": "integer", "example": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" }, "examples": { "rateLimitExceeded": { "value": { "status": "error", "error": "Too many requests", "errorCode": "TOO_MANY_REQUESTS" } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" }, "examples": { "internalError": { "value": { "status": "error", "error": "Internal server error", "errorCode": "INTERNAL_ERROR" } } } } } } } } }, "/api/v4/partner/settlement/quote": { "post": { "summary": "Create a settlement quote", "description": "Generate a settlement quote for one or more beneficiaries. The returned quote must be used in the settlement execution step before the confirm deadline.", "operationId": "create-settlement-quote", "tags": ["Partner Quote"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettlementQuoteRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettlementQuoteResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettlementQuoteBadRequest" }, "examples": { "fulfillmentDenied": { "value": { "status": "error", "error": "Fulfillment denied for some beneficiaries", "errorCode": "FULFILLMENT_DENIED", "payload": [ { "customerId": "customer_a1b2c3d4", "customerAddress": "0x1234....abcd", "reason": "NOT_FOUND" } ] } }, "wrongRequest": { "value": { "status": "error", "error": "", "errorCode": "WRONG_REQUEST" } } } } } }, "403": { "description": "Forbidden (missing/invalid API key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403" }, "examples": { "accessDenied": { "value": { "status": "error", "error": "Access denied", "errorCode": "ACCESS_DENIED" } } } } } }, "429": { "description": "Too Many Requests", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying the request.", "schema": { "type": "integer", "example": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" }, "examples": { "rateLimitExceeded": { "value": { "status": "error", "error": "Too many requests", "errorCode": "TOO_MANY_REQUESTS" } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" }, "examples": { "internalError": { "value": { "status": "error", "error": "Internal server error", "errorCode": "INTERNAL_ERROR" } } } } } } } } }, "/api/v4/partner/settlement/execute": { "post": { "summary": "Execute settlement", "description": "Confirm a previously generated settlement quote and initiate settlement execution.", "operationId": "execute-settlement", "tags": ["Partner Execution"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettlementExecuteRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettlementExecuteResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" }, "examples": { "wrongRequest": { "value": { "status": "error", "error": "", "errorCode": "WRONG_REQUEST" } } } } } }, "403": { "description": "Forbidden (missing/invalid API key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403" }, "examples": { "accessDenied": { "value": { "status": "error", "error": "Access denied", "errorCode": "ACCESS_DENIED" } } } } } }, "429": { "description": "Too Many Requests", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying the request.", "schema": { "type": "integer", "example": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" }, "examples": { "rateLimitExceeded": { "value": { "status": "error", "error": "Too many requests", "errorCode": "TOO_MANY_REQUESTS" } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" }, "examples": { "internalError": { "value": { "status": "error", "error": "Internal server error", "errorCode": "INTERNAL_ERROR" } } } } } } } } }, "/api/v4/partner/settlement/status/{quoteId}": { "get": { "summary": "Get settlement status", "description": "Retrieve the current status and settlement details using the quote ID.", "operationId": "get-settlement-status", "tags": ["Partner Execution"], "parameters": [ { "name": "quoteId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettlementExecuteResponse" } } } }, "403": { "description": "Forbidden (missing/invalid API key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403" }, "examples": { "accessDenied": { "value": { "status": "error", "error": "Access denied", "errorCode": "ACCESS_DENIED" } } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error404" }, "examples": { "customerNotFound": { "value": { "status": "error", "error": "No settlement with ID: {id}", "errorCode": "NOT_FOUND" } } } } } }, "429": { "description": "Too Many Requests", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying the request.", "schema": { "type": "integer", "example": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" }, "examples": { "rateLimitExceeded": { "value": { "status": "error", "error": "Too many requests", "errorCode": "TOO_MANY_REQUESTS" } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" }, "examples": { "internalError": { "value": { "status": "error", "error": "Internal server error", "errorCode": "INTERNAL_ERROR" } } } } } } } } }, "/api/v4/partner/rates/{currency}/{network}/{token}": { "get": { "summary": "Get exchange rate", "description": "Retrieve the current crypto-to-fiat and fiat-to-crypto exchange rate for a specific token, network, and settlement currency.", "operationId": "get-exchange-rate", "tags": ["Partner Rates"], "parameters": [ { "name": "currency", "in": "path", "required": true, "schema": { "type": "string" }, "description": "settlement currency (EUR constant for EUR, GBP constant for GBP)" }, { "name": "network", "in": "path", "required": true, "schema": { "type": "string" }, "description": "network of token (ethereum)" }, { "name": "token", "in": "path", "required": true, "schema": { "type": "string" }, "description": "address of token" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RatesResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" }, "examples": { "wrongRequest": { "value": { "status": "error", "error": "", "errorCode": "WRONG_REQUEST" } } } } } }, "403": { "description": "Forbidden (missing/invalid API key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403" }, "examples": { "accessDenied": { "value": { "status": "error", "error": "Access denied", "errorCode": "ACCESS_DENIED" } } } } } }, "429": { "description": "Too Many Requests", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying the request.", "schema": { "type": "integer", "example": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" }, "examples": { "rateLimitExceeded": { "value": { "status": "error", "error": "Too many requests", "errorCode": "TOO_MANY_REQUESTS" } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" }, "examples": { "internalError": { "value": { "status": "error", "error": "Internal server error", "errorCode": "INTERNAL_ERROR" } } } } } } } } }, "/api/v4/otc/sell-crypto/quote": { "post": { "summary": "Get Sell Crypto Quote", "description": "Get a quote for selling crypto into EUR on a registered IBAN. Available to OTC customers onboarded directly with Holyheld. The returned `quoteId` must be executed via Execute Sell Crypto before the `confirmDeadline`.", "operationId": "otc-sell-crypto-quote", "tags": ["OTC API"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OtcQuoteRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OtcQuoteResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } } } } }, "/api/v4/otc/buy-eur/quote": { "post": { "summary": "Get Buy EUR Quote", "description": "Get a quote for converting EUR (sent via SEPA from a registered IBAN) into crypto delivered to a specified wallet address. Available to OTC customers.", "operationId": "otc-buy-eur-quote", "tags": ["OTC API"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OtcQuoteRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OtcQuoteResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } } } } }, "/api/v4/otc/sell-crypto/execute": { "post": { "summary": "Execute Sell Crypto", "description": "Confirm a sell-crypto quote and begin the OTC flow. The response includes an `orderId` for polling and a `receiveAddress` to which the OTC customer must send the quoted token amount.", "operationId": "otc-sell-crypto-execute", "tags": ["OTC API"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OtcSellCryptoExecuteRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OtcExecuteResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } } } } }, "/api/v4/otc/buy-eur/execute": { "post": { "summary": "Execute Buy EUR", "description": "Confirm a buy-EUR quote and begin the OTC flow. The response includes an `orderId` for polling and the Holyheld collection IBAN to which the OTC customer must send the quoted EUR amount.", "operationId": "otc-buy-eur-execute", "tags": ["OTC API"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OtcBuyEurExecuteRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OtcExecuteResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } } } } }, "/api/v4/otc/order/status/{orderId}": { "get": { "summary": "Get OTC Order Status", "description": "Retrieve current status and details for an OTC order.", "operationId": "otc-get-order-status", "tags": ["OTC API"], "parameters": [ { "name": "orderId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OtcOrderStatusResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error404" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } } } } }, "/v4/web3/tag-info": { "servers": [ { "url": "https://api.brrr.network", "description": "Production" } ], "post": { "summary": "Get Tag Info", "description": "Resolve a Holyheld tag to its public display information before initiating an on-chain flow.", "operationId": "get-tag-info", "tags": ["Web3 API"], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Web3TagInfoRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Web3TagInfoResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error404" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } } } } }, "/v4/web3/token-info/{network}/{address}": { "servers": [ { "url": "https://api.brrr.network", "description": "Production" } ], "get": { "summary": "Get Token Information", "description": "Retrieve token metadata with current price and price change for a token on a given network.", "operationId": "get-token-info", "tags": ["Web3 API"], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "network", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Blockchain network identifier." }, { "name": "address", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Token contract or mint address." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Web3TokenInfoResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error404" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } } } } }, "/v4/web3/token-metadata": { "servers": [ { "url": "https://api.brrr.network", "description": "Production" } ], "post": { "summary": "Get Token Metadata", "description": "Retrieve extended token market data and additional visual metadata.", "operationId": "get-token-metadata", "tags": ["Web3 API"], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Web3TokenLookupRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Web3TokenMetadataResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error404" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } } } } }, "/v4/web3/token-chart": { "servers": [ { "url": "https://api.brrr.network", "description": "Production" } ], "post": { "summary": "Get Token Chart", "description": "Retrieve historical token price chart data for a requested time range.", "operationId": "get-token-chart", "tags": ["Web3 API"], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Web3TokenChartRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Web3TokenChartResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } } } } }, "/v4/web3/evm-balances": { "servers": [ { "url": "https://api.brrr.network", "description": "Production" } ], "post": { "summary": "Get EVM Balances", "description": "Retrieve token balances for an EVM wallet across supported networks.", "operationId": "get-evm-balances", "tags": ["Web3 API"], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Web3BalancesRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Web3EvmBalancesResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } } } } }, "/v4/web3/solana-balances": { "servers": [ { "url": "https://api.brrr.network", "description": "Production" } ], "post": { "summary": "Get Solana Balances", "description": "Retrieve token balances for a Solana wallet, including price and metadata.", "operationId": "get-solana-balances", "tags": ["Web3 API"], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Web3BalancesRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Web3SolanaBalancesResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } } } } }, "/v4/web3/solana-priority-fee": { "servers": [ { "url": "https://api.brrr.network", "description": "Production" } ], "get": { "summary": "Get Solana Priority Fee", "description": "Retrieve the recommended priority fee for Solana transactions.", "operationId": "get-solana-priority-fee", "tags": ["Web3 API"], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Web3SolanaPriorityFeeResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } } } } }, "/v5/config/address-check": { "servers": [ { "url": "https://api.brrr.network", "description": "Production" } ], "post": { "summary": "Address Check", "description": "Check whether an address is eligible for Card API onramp and offramp flows.", "operationId": "card-address-check", "tags": ["Config & Info"], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardAddressCheckRequest" } } } }, "responses": { "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } }, "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardAddressCheckResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error404" } } } } } } }, "/v5/config/buying-rate": { "servers": [ { "url": "https://api.brrr.network", "description": "Production" } ], "get": { "summary": "Get Buying Rate", "description": "Retrieve the informational USD/EUR FX rate used in Card API UX.", "operationId": "card-get-buying-rate", "tags": ["Config & Info"], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "code", "in": "query", "required": true, "schema": { "type": "string", "example": "EUR" } }, { "name": "direction", "in": "query", "required": false, "schema": { "type": "string", "enum": ["buy", "sell"], "default": "buy" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardBuyingRateResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error404" } } } } } } }, "/v5/config/settings": { "servers": [ { "url": "https://api.brrr.network", "description": "Production" } ], "get": { "summary": "Get Configuration", "description": "Retrieve Card API network, token, and contract configuration.", "operationId": "card-get-configuration", "tags": ["Config & Info"], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardConfigResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } } } } }, "/v5/offramp/crypto-to-card/tag-hash": { "servers": [ { "url": "https://api.brrr.network", "description": "Production" } ], "post": { "summary": "Get Tag Hash", "description": "Generate a one-time tag hash for crypto-to-card offramp flows.", "operationId": "card-get-tag-hash", "tags": ["Offramp - Crypto to Card"], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardTagHashRequest" } } } }, "responses": { "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } }, "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardTagHashResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error404" } } } } } } }, "/v5/offramp/crypto-to-card/evm-token-to-eur": { "servers": [ { "url": "https://api.brrr.network", "description": "Production" } ], "post": { "summary": "EVM Convert Token to EUR", "description": "Estimate an EVM offramp using a token-denominated amount.", "operationId": "card-evm-convert-token-to-eur", "tags": ["Offramp - Crypto to Card"], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardEvmConvertRequest" } } } }, "responses": { "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } }, "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardEvmEstimateResponse" } } } } } } }, "/v5/offramp/crypto-to-card/evm-eur-to-token": { "servers": [ { "url": "https://api.brrr.network", "description": "Production" } ], "post": { "summary": "EVM Convert EUR to Token", "description": "Estimate an EVM offramp using an EUR-denominated amount.", "operationId": "card-evm-convert-eur-to-token", "tags": ["Offramp - Crypto to Card"], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardEvmConvertRequest" } } } }, "responses": { "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } }, "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardEvmEstimateResponse" } } } } } } }, "/v5/offramp/crypto-to-card/solana-token-to-eur": { "servers": [ { "url": "https://api.brrr.network", "description": "Production" } ], "post": { "summary": "Solana Convert Token to EUR", "description": "Estimate a Solana offramp using a token-denominated amount.", "operationId": "card-solana-convert-token-to-eur", "tags": ["Offramp - Crypto to Card"], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardSolanaConvertRequest" } } } }, "responses": { "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } }, "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardSolanaEstimateResponse" } } } } } } }, "/v5/offramp/crypto-to-card/solana-eur-to-token": { "servers": [ { "url": "https://api.brrr.network", "description": "Production" } ], "post": { "summary": "Solana Convert EUR to Token", "description": "Estimate a Solana offramp using an EUR-denominated amount.", "operationId": "card-solana-convert-eur-to-token", "tags": ["Offramp - Crypto to Card"], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardSolanaConvertRequest" } } } }, "responses": { "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } }, "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardSolanaEstimateResponse" } } } } } } }, "/v5/offramp/crypto-to-card/transaction-data": { "servers": [ { "url": "https://api.brrr.network", "description": "Production" } ], "post": { "summary": "Get Transaction Data", "description": "Build ready-to-broadcast transaction data for a crypto-to-card offramp.", "operationId": "card-get-transaction-data", "tags": ["Offramp - Crypto to Card"], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardTransactionDataRequest" } } } }, "responses": { "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } }, "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardTransactionDataResponse" } } } } } } }, "/v5/offramp/crypto-to-card/execute-gasless": { "servers": [ { "url": "https://api.brrr.network", "description": "Production" } ], "post": { "summary": "Execute Gasless Transaction", "description": "Execute a gasless crypto-to-card offramp on behalf of the customer.", "operationId": "card-execute-gasless-transaction", "tags": ["Offramp - Crypto to Card"], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardGaslessRequest" } } } }, "responses": { "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } }, "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardGaslessResponse" } } } } } } }, "/v5/offramp/sepa/estimate-fee": { "servers": [ { "url": "https://api.brrr.network", "description": "Production" } ], "post": { "summary": "Estimate SEPA Fee", "description": "Estimate the fee for a Card API SEPA transfer.", "operationId": "card-estimate-sepa-fee", "tags": ["Offramp - SEPA Transfers"], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardSepaFeeRequest" } } } }, "responses": { "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } }, "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardSepaFeeResponse" } } } } } } }, "/v5/offramp/sepa/create-transfer": { "servers": [ { "url": "https://api.brrr.network", "description": "Production" } ], "post": { "summary": "Create SEPA Transfer", "description": "Create a one-time SEPA transfer destination for an offramp.", "operationId": "card-create-sepa-transfer", "tags": ["Offramp - SEPA Transfers"], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardCreateSepaTransferRequest" } } } }, "responses": { "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } }, "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardCreateSepaTransferResponse" } } } } } } }, "/v5/offramp/status": { "servers": [ { "url": "https://api.brrr.network", "description": "Production" } ], "post": { "summary": "Get Offramp Status", "description": "Poll the status of a Card API offramp using tag hash, tx hash, or HHTXID.", "operationId": "card-get-offramp-status", "tags": ["Get Offramp Status"], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardOfframpStatusRequest" } } } }, "responses": { "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } }, "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardOfframpStatusResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error404" } } } } } } }, "/v5/onramp/tokens": { "servers": [ { "url": "https://api.brrr.network", "description": "Production" } ], "post": { "summary": "Get Tokens List", "description": "List available Card API onramp tokens for a network.", "operationId": "card-get-tokens-list", "tags": ["Buy Crypto (Onramp)"], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardOnrampTokensRequest" } } } }, "responses": { "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } }, "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardOnrampTokensResponse" } } } } } } }, "/v5/onramp/token-amount": { "servers": [ { "url": "https://api.brrr.network", "description": "Production" } ], "post": { "summary": "Get Token Amount", "description": "Estimate token output for a given EUR amount in Card API onramp.", "operationId": "card-get-token-amount", "tags": ["Buy Crypto (Onramp)"], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardOnrampTokenAmountRequest" } } } }, "responses": { "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } }, "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardAmountQuoteResponse" } } } } } } }, "/v5/onramp/eur-amount": { "servers": [ { "url": "https://api.brrr.network", "description": "Production" } ], "post": { "summary": "Get EUR Amount", "description": "Estimate EUR cost for a given token amount in Card API onramp.", "operationId": "card-get-eur-amount", "tags": ["Buy Crypto (Onramp)"], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardOnrampEurAmountRequest" } } } }, "responses": { "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } }, "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardAmountQuoteResponse" } } } } } } }, "/v5/onramp/estimate": { "servers": [ { "url": "https://api.brrr.network", "description": "Production" } ], "post": { "summary": "Estimate Onramp Transaction", "description": "Estimate fees and output for a Card API onramp transaction.", "operationId": "card-estimate-onramp-transaction", "tags": ["Buy Crypto (Onramp)"], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardOnrampEstimateRequest" } } } }, "responses": { "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } }, "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardOnrampEstimateResponse" } } } } } } }, "/v5/onramp/execute": { "servers": [ { "url": "https://api.brrr.network", "description": "Production" } ], "post": { "summary": "Execute Onramp", "description": "Create a Card API onramp transaction and return its HHTXID.", "operationId": "card-execute-onramp", "tags": ["Buy Crypto (Onramp)"], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardOnrampExecuteRequest" } } } }, "responses": { "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } }, "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardOnrampExecuteResponse" } } } } } } }, "/v5/onramp/status": { "servers": [ { "url": "https://api.brrr.network", "description": "Production" } ], "post": { "summary": "Get Onramp Status", "description": "Poll the status of a Card API onramp transaction.", "operationId": "card-get-onramp-status", "tags": ["Buy Crypto (Onramp)"], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardOnrampStatusRequest" } } } }, "responses": { "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } }, "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardOnrampStatusResponse" } } } } } } } } }