openapi.yaml is here:
openapi.yaml
Copy
Ask AI
openapi: 3.1.0
info:
title: Halliday API V2
description: |
API V2 for Halliday's payment infrastructure, supporting onramps, swaps, and offramps.
This API provides a unified interface for cryptocurrency payments, allowing developers to:
- Quote payments across multiple providers
- Execute payments with onramps, swaps, and offramps
- Track payment status and history
## Authentication
API key authentication is required for all endpoints.
version: 2.0.0
contact:
name: Contact Halliday
url: https://halliday.xyz
email: [email protected]
security:
- ApiKeyAuth: []
servers:
- url: https://v2.prod.halliday.xyz
description: Base domain
paths:
/chains:
get:
summary: Get supported chains
description: |
Get a list of all supported blockchain networks with their configuration details.
operationId: getChains
tags:
- Chains
parameters:
- name: sandbox
in: query
required: false
description: Whether to return sandbox/testnet chains
schema:
type: boolean
responses:
"200":
description: List of supported chains
content:
application/json:
schema:
type: object
additionalProperties:
$ref: "#/components/schemas/ChainInfo"
example:
ethereum:
chain_id: 1
network: ethereum
native_currency:
name: Ether
symbol: ETH
decimals: 18
is_testnet: false
explorer: https://etherscan.io/
image: <IMAGE_URL>...
rpc: <RPC_URL>...
arbitrum:
chain_id: 42161
network: arbitrum
native_currency:
name: Ether
symbol: ETH
decimals: 18
is_testnet: false
explorer: https://arbiscan.io/
image: <IMAGE_URL>...
rpc: <RPC_URL>...
"400":
description: Bad request
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
example:
errors:
- kind: other
message: "Invalid sandbox parameter value. Expected boolean."
"401":
description: Unauthorized
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
example:
errors:
- kind: other
message: "Invalid API key"
"403":
description: Forbidden
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
example:
errors:
- kind: other
message: "Insufficient permissions to access this resource"
"500":
description: Internal server error
content:
application/json:
schema:
$ref: "#/components/schemas/ServerErrorResponse"
example:
errors:
- message: "A server error occurred. Please try again later."
/assets:
get:
summary: Get asset details
description: |
Get detailed information about specific assets including metadata, symbols, and chain information.
operationId: getAssets
tags:
- Assets
parameters:
- name: sandbox
in: query
required: false
description: Whether to use sandbox environment
schema:
type: boolean
- name: assets[]
in: query
required: false
description: List of assets to get details for
style: form
explode: true
schema:
type: array
items:
$ref: "#/components/schemas/Asset"
responses:
"200":
description: Asset details
content:
application/json:
schema:
type: object
additionalProperties:
$ref: "#/components/schemas/AssetDetails"
example:
usd:
issuer: USA
name: United States Dollar
symbol: USD
decimals: 2
eur:
issuer: ECB
name: Euro
symbol: EUR
decimals: 2
"ethereum:0x":
chain: ethereum
address: "0x"
name: Ether
symbol: ETH
decimals: 18
image_url: https://coin-images.coingecko.com/coins/images/279/large/ethereum.png?1696501628
"400":
description: Bad request
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
example:
errors:
- kind: other
message: "Invalid asset format. Expected format: 'chain:address' for tokens or currency code for fiats"
"401":
description: Unauthorized
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
example:
errors:
- kind: other
message: "Missing or invalid API key"
"403":
description: Forbidden
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
example:
errors:
- kind: other
message: "API key does not have permission to access asset information"
"500":
description: Internal server error
content:
application/json:
schema:
$ref: "#/components/schemas/ServerErrorResponse"
example:
errors:
- message: "A server error occurred. Please try again later."
/assets/available-inputs:
get:
summary: Get available input assets for a given output asset
description: |
Get a list of assets that can be used as inputs for the given output assets and providers.
operationId: getInputAssets
tags:
- Assets
parameters:
- name: sandbox
in: query
required: false
description: Whether to use sandbox environment
schema:
type: boolean
- name: inputs[]
in: query
required: false
description: Filter by specific input assets
style: form
explode: true
schema:
type: array
items:
$ref: "#/components/schemas/Asset"
- name: outputs[]
in: query
required: false
description: Output assets to find inputs for
style: form
explode: true
schema:
type: array
items:
$ref: "#/components/schemas/Asset"
- name: onramps[]
in: query
required: false
description: Filter by specific onramp providers
style: form
explode: true
schema:
type: array
items:
type: string
- name: offramps[]
in: query
required: false
description: Filter by specific offramp providers
style: form
explode: true
schema:
type: array
items:
type: string
responses:
"200":
description: Available input assets grouped by output
content:
application/json:
schema:
type: object
additionalProperties:
type: object
properties:
fiats:
type: array
items:
$ref: "#/components/schemas/Fiat"
tokens:
type: array
items:
$ref: "#/components/schemas/Token"
required:
- fiats
- tokens
example:
"ethereum:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48":
fiats:
- usd
tokens: []
"400":
description: Bad request
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
example:
errors:
- kind: other
message: "Invalid provider specified. Provider 'invalid_provider' is not supported"
"401":
description: Unauthorized
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
example:
errors:
- kind: other
message: "Authentication required. Please provide a valid API key."
"403":
description: Forbidden
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
example:
errors:
- kind: other
message: "Access denied. Your API key does not have permission to query available assets."
"500":
description: Internal server error
content:
application/json:
schema:
$ref: "#/components/schemas/ServerErrorResponse"
example:
errors:
- message: "A server error occurred. Please try again later."
/assets/available-outputs:
get:
summary: Get available output assets for a given input asset
description: |
Get a list of assets that can be received as outputs for the given input assets and providers.
operationId: getOutputAssets
tags:
- Assets
parameters:
- name: sandbox
in: query
required: false
description: Whether to use sandbox environment
schema:
type: boolean
- name: inputs[]
in: query
required: false
description: Input assets to find outputs for
style: form
explode: true
schema:
type: array
items:
$ref: "#/components/schemas/Asset"
- name: outputs[]
in: query
required: false
description: Filter by specific output assets
style: form
explode: true
schema:
type: array
items:
$ref: "#/components/schemas/Asset"
- name: onramps[]
in: query
required: false
description: Filter by specific onramp providers
style: form
explode: true
schema:
type: array
items:
type: string
- name: offramps[]
in: query
required: false
description: Filter by specific offramp providers
style: form
explode: true
schema:
type: array
items:
type: string
responses:
"200":
description: Available output assets grouped by input
content:
application/json:
schema:
type: object
additionalProperties:
type: object
properties:
fiats:
type: array
items:
$ref: "#/components/schemas/Fiat"
tokens:
type: array
items:
$ref: "#/components/schemas/Token"
required:
- fiats
- tokens
example:
"usd":
fiats: []
tokens:
- "arbitrum:0x"
- "ethereum:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
"400":
description: Bad request
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
example:
errors:
- kind: other
message: "Invalid input asset format. Asset 'invalid-format' does not match expected pattern."
"401":
description: Unauthorized
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
example:
errors:
- kind: other
message: "Invalid or expired API key"
"403":
description: Forbidden
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
example:
errors:
- kind: other
message: "Your account does not have access to this endpoint"
"500":
description: Internal server error
content:
application/json:
schema:
$ref: "#/components/schemas/ServerErrorResponse"
example:
errors:
- message: "A server error occurred. Please try again later."
/payments:
get:
summary: Get payment status
description: |
Get the current status of a payment, including progress through onramp/swap/offramp stages.
operationId: getPaymentStatus
tags:
- Payments
parameters:
- name: payment_id
in: query
required: true
description: Payment identifier to check
schema:
type: string
responses:
"200":
description: Payment status retrieved successfully!
content:
application/json:
schema:
$ref: "#/components/schemas/PaymentStatus"
"400":
description: Bad request
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
example:
errors:
- kind: other
message: "Missing required parameter: payment_id"
"401":
description: Unauthorized
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
example:
errors:
- kind: other
message: "Invalid API key"
"403":
description: Forbidden
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
example:
errors:
- kind: other
message: "You do not have permission to view this payment"
"404":
description: Payment not found
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
example:
errors:
- kind: other
message: "Payment with payment_id 'pay_abc123' not found"
"500":
description: Internal server error
content:
application/json:
schema:
$ref: "#/components/schemas/ServerErrorResponse"
example:
errors:
- message: "A server error occurred. Please try again later."
/payments/quotes:
post:
summary: Get payment quotes
description: |
Request quotes for payments, supporting both fixed input and fixed output scenarios.
Returns multiple quote options with pricing, fees, and routing information.
This endpoint can also be used to requote from an existing payment by providing a payment_id.
When requoting, input amounts are automatically derived from
the payment's current state, but you can optionally override the output asset.
operationId: getPaymentQuotes
tags:
- Payments
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/QuoteRequest"
responses:
"200":
description: Successful quote response
content:
application/json:
schema:
$ref: "#/components/schemas/QuoteResponse"
"400":
description: Bad request
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
example:
errors:
- kind: amount
given:
amount: "5"
limits:
min:
amount: "10"
max:
amount: "10000"
source: "moonpay"
message: "Amount too low. Minimum amount is $10 USD"
"401":
description: Unauthorized
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
example:
errors:
- kind: other
message: "API key missing or invalid"
"403":
description: Forbidden
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
example:
errors:
- kind: other
message: "Your API key does not have permission to create quotes"
"500":
description: Internal server error
content:
application/json:
schema:
$ref: "#/components/schemas/ServerErrorResponse"
example:
errors:
- message: "A server error occurred. Please try again later."
/payments/confirm:
post:
summary: Confirm a payment
description: |
Confirm a previously quoted payment and receive deposit instructions.
Returns information on how to fund the payment (widget URL, contract address, etc.).
operationId: confirmPayment
tags:
- Payments
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- payment_id
- state_token
- owner_address
- destination_address
properties:
payment_id:
type: string
description: ID of the payment from the quote to confirm
state_token:
type: string
format: byte
description: State token from the quote response
owner_address:
type: string
description: Owner address for the payment. This is the address that the payment will be sent from.
destination_address:
type: string
description: Destination address for the payment. This is the address that the payment will be sent to.
client_redirect_url:
type: string
format: uri
description: Optional URL to redirect users to after an onramp flow completes.
responses:
"200":
description: Payment confirmed successfully
content:
application/json:
schema:
$ref: "#/components/schemas/PaymentStatus"
"400":
description: Bad request
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
example:
errors:
- kind: other
message: "Invalid state_token. The quote may have expired."
"401":
description: Unauthorized
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
example:
errors:
- kind: other
message: "Authentication failed. Invalid API key."
"403":
description: Forbidden
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
example:
errors:
- kind: other
message: "Access denied. This payment belongs to a different account."
"404":
description: Payment not found
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
example:
errors:
- kind: other
message: "Payment 'pay_xyz789' not found or has expired"
"500":
description: Internal server error
content:
application/json:
schema:
$ref: "#/components/schemas/ServerErrorResponse"
example:
errors:
- message: "A server error occurred. Please try again later."
/payments/withdraw:
post:
summary: Return funds to owner or retry payment
description: |
Request a withdrawal to return funds back to the owner or to a requoted processing address.
This endpoint should be used when a payment cannot be completed and funds need to be returned.
operationId: withdrawPayment
tags:
- Payments
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/WithdrawPaymentAuthorizationRequest"
responses:
"200":
description: Withdrawal initiated successfully
content:
application/json:
schema:
$ref: "#/components/schemas/WithdrawPaymentAuthorizationResponse"
"404":
description: Payment not found
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
example:
errors:
- kind: other
message: "Payment 'pay_def456' not found"
"400":
description: Bad request
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
example:
errors:
- kind: other
message: "Missing field 'token_amounts'."
"401":
description: Unauthorized
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
example:
errors:
- kind: other
message: "Invalid or missing API key"
"403":
description: Forbidden
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
example:
errors:
- kind: other
message: "You are not authorized to withdraw funds from this payment"
"500":
description: Internal server error
content:
application/json:
schema:
$ref: "#/components/schemas/ServerErrorResponse"
example:
errors:
- message: "A server error occurred. Please try again later."
/payments/withdraw/confirm:
post:
summary: Confirm withdrawal request
description: |
Submit and execute the signed withdrawal request to return funds back to the owner or to a requoted processing address.
operationId: withdrawPaymentConfirm
tags:
- Payments
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/WithdrawPaymentRequest"
responses:
"200":
description: Withdrawal executed successfully
content:
application/json:
schema:
$ref: "#/components/schemas/WithdrawPaymentResponse"
"400":
description: Bad request
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
example:
errors:
- kind: other
message: "Invalid request body"
"401":
description: Unauthorized
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
example:
errors:
- kind: other
message: "Invalid API key"
"403":
description: Forbidden
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
example:
errors:
- kind: other
message: "You are not authorized to withdraw funds from this payment"
"500":
description: Internal server error
content:
application/json:
schema:
$ref: "#/components/schemas/ServerErrorResponse"
example:
errors:
- message: "A server error occurred. Please try again later."
/payments/balances:
post:
summary: Get wallet balances
description: |
Retrieve balances for the wallets associated with a payment. You can optionally supply additional
wallet and token pairs to check alongside the payment's primary wallet.
operationId: getPaymentBalances
tags:
- Payments
requestBody:
required: false
content:
application/json:
schema:
$ref: "#/components/schemas/RequestForPaymentBalances"
example:
payment_id: pay_abc123
custom_queries:
- address: "0xabc1234567890abcdef1234567890abcdef1234"
token: "ethereum:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
- address: "0xdef1234567890abcdef1234567890abcdef5678"
token: "arbitrum:0xfffFFFFFfFFfffFFfFffffFffFFfFFfFFfFFf"
responses:
"200":
description: Wallet balances retrieved successfully
content:
application/json:
schema:
$ref: "#/components/schemas/PaymentBalancesResponse"
"400":
description: Bad request
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
example:
errors:
- kind: other
message: "Invalid wallet address format"
"401":
description: Unauthorized
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
example:
errors:
- kind: other
message: "Invalid API key"
"403":
description: Forbidden
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
example:
errors:
- kind: other
message: "You do not have permission to query payment balances"
"404":
description: Payment not found
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
example:
errors:
- kind: other
message: "Payment 'pay_abc123' not found"
"500":
description: Internal server error
content:
application/json:
schema:
$ref: "#/components/schemas/ServerErrorResponse"
example:
errors:
- message: "A server error occurred. Please try again later."
components:
securitySchemes:
ApiKeyAuth:
type: http
scheme: bearer
bearerFormat: API_KEY
schemas:
# Core Data Types
ChainInfo:
type: object
required:
- chain_id
- network
- native_currency
- is_testnet
properties:
chain_id:
type: number
description: Chain ID for the network
example: 1
network:
type: string
description: Network name
example: ethereum
native_currency:
type: object
properties:
name:
type: string
example: Ether
symbol:
type: string
example: ETH
decimals:
type: number
example: 18
required:
- name
- symbol
- decimals
is_testnet:
type: boolean
description: Whether this is a testnet
example: false
explorer:
type: string
format: uri
description: Block explorer URL
example: https://etherscan.io
image:
type: string
format: uri
description: Chain logo URL
rpc:
type: string
format: uri
description: RPC endpoint URL
AssetDetails:
oneOf:
- $ref: "#/components/schemas/FiatDetails"
- $ref: "#/components/schemas/TokenDetails"
FiatDetails:
type: object
required:
- issuer
- name
- symbol
- decimals
properties:
issuer:
type: string
description: Issuer of the fiat
example: USA
name:
type: string
description: Full currency name
example: US Dollar
symbol:
type: string
description: Currency symbol
example: USD
decimals:
type: number
minimum: 0
maximum: 18
description: Number of decimal places
example: 2
alias:
type: string
description: Alternative symbol or alias
image_url:
type: string
format: uri
description: Currency icon URL
TokenDetails:
type: object
required:
- chain
- address
- name
- symbol
- decimals
properties:
chain:
type: string
description: Blockchain network
example: ethereum
address:
type: string
description: Token contract address
example: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
name:
type: string
description: Token name
example: USD Coin
symbol:
type: string
description: Token symbol
example: USDC
decimals:
type: number
minimum: 0
maximum: 18
description: Token decimals
example: 6
alias:
type: string
description: Alternative symbol or alias
image_url:
type: string
format: uri
description: Token icon URL
is_native:
type: boolean
description: Whether this is the native token
example: false
wrapper:
type: string
description: Wrapper token symbol
Asset:
type: string
description: Identifier in the token format ("chain:address") or fiat currency code ("USD")
example: ethereum:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48
Fiat:
type: string
description: Fiat currency code
example: USD
Token:
type: string
description: Token identifier in the format "chain:address"
pattern: "^[a-z]+:0x[a-fA-F0-9]+$"
example: "ethereum:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
AssetAmount:
type: object
required:
- asset
- amount
properties:
asset:
$ref: "#/components/schemas/Asset"
amount:
type: string
description: Amount as a string to preserve precision
example: "1"
TokenAmount:
type: object
required:
- token
- amount
properties:
token:
$ref: "#/components/schemas/Token"
amount:
type: string
description: Amount of the token to withdraw, represented as a string to preserve precision
# Quote Request Types
QuoteRequest:
type: object
required:
- request
- price_currency
properties:
request:
$ref: "#/components/schemas/FixedInputQuoteRequest"
price_currency:
type: string
description: Currency that all prices are denominated in
example: USD
onramps:
type: array
items:
type: string
description: Filter by specific onramp providers
example: ["moonpay", "coinbase"]
onramp_methods:
type: array
items:
type: string
description: Filter by onramp payment methods
example: ["credit_card", "ach", "apple_pay"]
customer_ip_address:
type: string
description: IP address of the customer
customer_id:
type: string
description: Customer ID for tracking
customer_geolocation:
type: object
description: Geolocation information
required:
- alpha3_country_code
properties:
alpha3_country_code:
type: string
description: Three-letter ISO country code
state_code:
type: string
description: State or region code when applicable. Use an empty string when not applicable.
parent_payment_id:
type: string
description: Optional parent payment identifier used when creating a quote from an existing payment.
FixedInputQuoteRequest:
type: object
required:
- kind
- fixed_input_amount
- output_asset
properties:
kind:
type: string
enum: [FIXED_INPUT]
fixed_input_amount:
$ref: "#/components/schemas/AssetAmount"
output_asset:
$ref: "#/components/schemas/Asset"
# Quote Response Types
QuoteResponse:
type: object
required:
- quote_request
- quotes
- current_prices
- price_currency
- state_token
- quoted_at
- accept_by
- failures
properties:
quote_request:
$ref: "#/components/schemas/QuoteRequest"
quotes:
type: array
items:
$ref: "#/components/schemas/Quote"
current_prices:
type: object
additionalProperties:
type: string
description: Mapping of asset symbols to their unit prices
example:
"USD": "1.00"
"ethereum:0x": "4200"
"ethereum:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48": "1.00"
price_currency:
type: string
description: Currency that all prices are denominated in
example: USD
state_token:
type: string
description: |
Signed state token containing routing and payment flow information.
This value must be passed unmodified in subsequent API calls.
Do not attempt to parse or modify this data as it is cryptographically signed.
quoted_at:
type: string
format: date-time
description: |
Timestamp of when the quote was created, in UTC ISO 8601 format
accept_by:
type: string
format: date-time
description: |
Timestamp of when the quote will expire, in UTC ISO 8601 format
failures:
type: array
description: Providers that failed to return a quote.
items:
$ref: "#/components/schemas/FailureContent"
QuotedEntry:
type: object
required:
- output_amount
- fees
- route
properties:
output_amount:
$ref: "#/components/schemas/AssetAmount"
fees:
$ref: "#/components/schemas/Fees"
onramp:
type: string
description: Onramp provider name
onramp_method:
type: string
description: Payment method
example: credit_card
route:
type: array
items:
$ref: "#/components/schemas/QuotedRouteItem"
description: Quoted workflow steps and their effects
Quote:
allOf:
- $ref: "#/components/schemas/QuotedEntry"
- type: object
properties:
payment_id:
type: string
description: Unique payment identifier
required:
- payment_id
FailureContent:
type: object
required:
- service_ids
- latency_seconds
properties:
service_ids:
type: array
description: Providers that failed to return quotes.
items:
type: string
latency_seconds:
type: number
format: float
description: Time taken for the failed quote attempt.
issues:
type: array
description: Optional list of structured issues describing the failure.
items:
$ref: "#/components/schemas/Issue"
FulfilledEntry:
type: object
required:
- route
properties:
output_amount:
$ref: "#/components/schemas/AssetAmount"
fees:
$ref: "#/components/schemas/Fees"
onramp:
type: string
description: Onramp provider name
onramp_method:
type: string
description: Payment method
example: credit_card
route:
type: array
items:
$ref: "#/components/schemas/FulfilledRouteItem"
description: In-progress workflow steps, statuses, and their effects
# Fees
Fees:
type: object
required:
- total_fees
- conversion_fees
- network_fees
- business_fees
- currency_symbol
properties:
total_fees:
type: string
description: Total fees amount
conversion_fees:
type: string
description: Ramps + bridge + DEX fees
network_fees:
type: string
description: Blockchain gas fees
business_fees:
type: string
description: Developer integration fees
currency_symbol:
type: string
description: Currency symbol that the fees are denominated in (e.g., "USD", "USDC")
example: "USD"
# Confirm Payment Response
ConfirmPaymentResponse:
type: object
required:
- quote_request
- quote
properties:
quote:
$ref: "#/components/schemas/Quote"
current_prices:
type: object
additionalProperties:
type: string
description: Mapping of asset symbols to their unit prices
example:
"USD": "1.00"
"ethereum:0x": "4200"
"ethereum:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48": "1.00"
price_currency:
type: string
description: Currency that all prices are denominated in
example: USD
Instruction:
oneOf:
- $ref: "#/components/schemas/OnrampWidgetInstruction"
- $ref: "#/components/schemas/SwapInstruction"
- $ref: "#/components/schemas/ErrorWithdrawOrRolloverInstruction"
discriminator:
propertyName: instruction_type
OnrampWidgetInstruction:
type: object
required:
- instruction_type
- payment_id
- onramp_url
- deposit_info
- onramp_currency
properties:
instruction_type:
type: string
enum: [ONRAMP_WIDGET]
onramp_url:
type: string
description: URL to query to get onramp details and redirect to onramp
example: "https://app.halliday.xyz/funding?payment_id=pay123&..."
payment_id:
type: string
description: ID of the payment to onramp
deposit_info:
type: object
required:
- deposit_token
- deposit_amount
- deposit_address
- deposit_chain
properties:
deposit_token:
$ref: "#/components/schemas/Token"
description: Token required for deposit
deposit_amount:
type: string
description: Amount of the token required for deposit
example: "100.50"
deposit_address:
type: string
description: Contract address for payment
deposit_chain:
type: string
description: Blockchain for payment contract
example: ethereum
onramp_currency:
$ref: "#/components/schemas/Fiat"
SwapInstruction:
type: object
required:
- instruction_type
- deposit_info
properties:
instruction_type:
type: string
enum: [SWAP]
deposit_info:
type: object
required:
- deposit_token
- deposit_amount
- deposit_address
- deposit_chain
properties:
deposit_token:
$ref: "#/components/schemas/Token"
description: Token required for deposit
deposit_amount:
type: string
description: Amount of the token required for deposit
example: "100.50"
deposit_address:
type: string
description: Contract address for payment
deposit_chain:
type: string
description: Blockchain for payment contract
example: ethereum
ErrorWithdrawOrRolloverInstruction:
type: object
required:
- instruction_type
- error_message
- asset_amounts
properties:
instruction_type:
type: string
enum: [ERROR_WITHDRAW_OR_ROLLOVER]
description: Instruction type for error handling with withdrawal or rollover option
error_message:
type: string
description: Brief explanation of the error.
asset_amounts:
type: array
items:
$ref: "#/components/schemas/AssetAmount"
parent_payment_id:
type: string
description: ID of the parent payment where the funds are being rolled over from.
description: |
When an error occurs during payment processing, this instruction provides:
1. Information about the error
2. The assets and amounts to withdraw or rollover
3. For rollovers, the parent payment ID of the payment that encountered the error
4. To retry the payment, call /payments/quotes with the payment_id to get new quote options.
BalanceQuery:
type: object
required:
- address
- token
properties:
address:
type: string
description: One-time wallet address associated with the payment.
example: "0xabc1234567890abcdef1234567890abcdef1234"
token:
$ref: "#/components/schemas/Token"
description: Token identifier to query in the wallet.
example: "ethereum:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
RequestForBalances:
type: object
properties:
workflow_id:
type: string
description: Payment identifier whose one-time wallet balances should be returned.
example: pay_abc123
custom_queries:
type: array
description: Additional wallet and token combinations to query.
items:
$ref: "#/components/schemas/BalanceQuery"
BalanceResult:
type: object
required:
- address
- token
- value
properties:
address:
type: string
description: One-time wallet address that was queried.
example: "0xabc1234567890abcdef1234567890abcdef1234"
token:
$ref: "#/components/schemas/Token"
description: Token identifier that was queried.
example: "ethereum:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
value:
oneOf:
- type: object
required:
- kind
- amount
properties:
kind:
type: string
enum: [amount]
amount:
$ref: "#/components/schemas/Amount"
- type: object
required:
- kind
properties:
kind:
type: string
enum: [error]
discriminator:
propertyName: kind
BalancesResponse:
type: object
required:
- balance_results
properties:
balance_results:
type: array
items:
$ref: "#/components/schemas/BalanceResult"
RequestForPaymentBalances:
type: object
properties:
payment_id:
type: string
description: Payment identifier whose associated wallets should be queried.
example: pay_abc123
custom_queries:
type: array
description: Additional wallet and token combinations to query.
items:
type: object
required:
- address
- token
properties:
address:
type: string
description: Wallet address to query.
example: "0xabc1234567890abcdef1234567890abcdef1234"
token:
$ref: "#/components/schemas/Token"
description: Token identifier to query at the wallet address.
example: "ethereum:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
PaymentBalancesResult:
type: object
required:
- address
- token
- value
properties:
address:
type: string
description: Wallet address that was queried.
example: "0xabc1234567890abcdef1234567890abcdef1234"
token:
$ref: "#/components/schemas/Token"
description: Token identifier that was queried.
example: "ethereum:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
value:
oneOf:
- type: object
required:
- kind
- amount
properties:
kind:
type: string
enum: [amount]
amount:
$ref: "#/components/schemas/Amount"
- type: object
required:
- kind
properties:
kind:
type: string
enum: [error]
discriminator:
propertyName: kind
PaymentBalancesResponse:
type: object
required:
- balance_results
properties:
balance_results:
type: array
items:
$ref: "#/components/schemas/PaymentBalancesResult"
# Withdrawal
WithdrawPaymentAuthorizationRequest:
type: object
required:
- payment_id
- token_amounts
- recipient_address
properties:
payment_id:
type: string
description: ID of the payment to withdraw
token_amounts:
type: array
items:
$ref: "#/components/schemas/TokenAmount"
description: List of token amounts to withdraw back to the owner or to a requoted processing address
recipient_address:
type: string
description: On-chain address to withdraw the funds to. The assets will go to the address on the same chain the assets are on.
WithdrawPaymentAuthorizationResponse:
type: object
required:
- payment_id
- withdraw_authorization
properties:
payment_id:
type: string
description: ID of the withdrawal transaction
withdraw_authorization:
type: string
description: An EIP-712 JSON string that the owner signs to perform a withdrawal on their one-time payment wallet
WithdrawPaymentRequest:
type: object
required:
- payment_id
- token_amounts
- recipient_address
- owner_signature
properties:
payment_id:
type: string
description: ID of the payment to withdraw
token_amounts:
type: array
items:
$ref: "#/components/schemas/TokenAmount"
description: List of token amounts to withdraw back to the owner or to a requoted processing address
recipient_address:
type: string
description: On-chain address to withdraw the funds to, on the same chain as the assets to withdraw.
owner_signature:
type: string
description: The payment owner's signature on the withdrawal_authorization, authorizing the withdrawal
WithdrawPaymentResponse:
type: object
required:
- payment_id
- transaction_hash
properties:
payment_id:
type: string
description: ID of the payment to withdraw
transaction_hash:
type: string
description: Blockchain transaction hash for the withdrawal
# Payment Status
PaymentStatus:
type: object
required:
- payment_id
- status
- funded
- created_at
- updated_at
- initiate_fund_by
- quoted
- fulfilled
- current_prices
- price_currency
- processing_addresses
- owner_address
- destination_address
properties:
payment_id:
type: string
status:
type: string
enum: [PENDING, COMPLETE, FAILED, EXPIRED, WITHDRAWN, TAINTED]
funded:
type: boolean
description: Whether the payment has been funded
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
initiate_fund_by:
type: string
format: date-time
description: Deadline for funding the payment.
completed_at:
type: string
format: date-time
quote_request:
$ref: "#/components/schemas/QuoteRequest"
description: Optional reference to the original quote request.
quoted:
$ref: "#/components/schemas/QuotedEntry"
fulfilled:
$ref: "#/components/schemas/FulfilledEntry"
current_prices:
type: object
additionalProperties:
type: string
description: Mapping of asset symbols to their unit prices
example:
"USD": "1.00"
"ethereum:0x": "4200"
"ethereum:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48": "1.00"
price_currency:
type: string
description: Currency that all prices are denominated in
example: USD
customer_id:
type: string
description: ID of the customer who created the payment
processing_addresses:
type: array
items:
type: object
required:
- chain
- address
properties:
chain:
type: string
description: Blockchain network
example: ethereum
address:
type: string
description: Payment processing contract address
owner_address:
type: string
description: Address of the owner of the payment
destination_address:
type: string
description: Address of the destination of the payment
next_instruction:
$ref: "#/components/schemas/NextInstruction"
nullable: true
PaymentStatusRequest:
type: object
required:
- payment_id
properties:
payment_id:
type: string
description: Unique payment identifier to fetch status for.
NextInstruction:
description: Instruction payload that returns the funding pages if the payment requires funding.
oneOf:
- $ref: "#/components/schemas/OnrampOrTransferInInstruction"
discriminator:
propertyName: type
mapping:
ONRAMP: "#/components/schemas/OnrampOrTransferInInstruction"
example:
type: ONRAMP
payment_id: <string>
funding_page_url: https://app.halliday.xyz/funding/${payment_id}
deposit_info:
- deposit_token: base:0x833589fcd6edb6e08f4c7c32d4f71b54bda02913
deposit_amount: "4.8"
deposit_address: 0xaddress
deposit_chain: base
OnrampOrTransferInInstruction:
type: object
required:
- type
- payment_id
- funding_page_url
- deposit_info
properties:
type:
type: string
enum: [ONRAMP, TRANSFER_IN]
description: Discriminator for this instruction type.
payment_id:
type: string
description: The payment this instruction is associated with.
funding_page_url:
type: string
format: uri
description: URL where the user can complete funding for this payment.
deposit_info:
type: array
description: One or more deposit routes to fund the payment.
items:
$ref: "#/components/schemas/DepositInfo"
DepositInfo:
type: object
required:
- deposit_token
- deposit_amount
- deposit_address
- deposit_chain
properties:
deposit_token:
# Use your existing Asset schema (identifier like "chain:address" or fiat code).
$ref: "#/components/schemas/Asset"
deposit_amount:
type: string
description: Amount to deposit, as a decimal string.
example: "4.8"
deposit_address:
type: string
description: Address to which funds will be deposited.
deposit_chain:
type: string
description: Network on which the deposit will be made (e.g., base, ethereum).
example: base
# Error Responses
Issue:
oneOf:
- $ref: "#/components/schemas/AmountIssue"
- $ref: "#/components/schemas/AmountDownstreamIssue"
- $ref: "#/components/schemas/GeolocationIssue"
- $ref: "#/components/schemas/ProviderIssue"
- $ref: "#/components/schemas/PayinMethodIssue"
- $ref: "#/components/schemas/OtherIssue"
- $ref: "#/components/schemas/UnknownIssue"
discriminator:
propertyName: kind
AmountIssue:
type: object
required:
- kind
- given
- limits
- source
- message
properties:
kind:
type: string
enum: [amount]
given:
$ref: "#/components/schemas/Amount"
limits:
$ref: "#/components/schemas/Limits"
source:
type: string
message:
type: string
AmountDownstreamIssue:
type: object
required:
- kind
- given
- limits
- source
- message
properties:
kind:
type: string
enum: [amount-downstream]
given:
$ref: "#/components/schemas/Amount"
limits:
$ref: "#/components/schemas/Limits"
source:
type: string
message:
type: string
GeolocationIssue:
type: object
required:
- kind
- message
properties:
kind:
type: string
enum: [geolocation]
message:
type: string
ProviderIssue:
type: object
required:
- kind
- message
properties:
kind:
type: string
enum: [provider]
message:
type: string
PayinMethodIssue:
type: object
required:
- kind
- message
properties:
kind:
type: string
enum: [payin_method]
message:
type: string
OtherIssue:
type: object
required:
- kind
- message
properties:
kind:
type: string
enum: [other]
message:
type: string
UnknownIssue:
type: object
required:
- kind
- message
properties:
kind:
type: string
enum: [unknown]
message:
type: string
Amount:
type: object
required:
- amount
properties:
amount:
type: string
Limits:
type: object
properties:
min:
$ref: "#/components/schemas/Amount"
max:
$ref: "#/components/schemas/Amount"
ErrorResponse:
type: object
required:
- errors
properties:
errors:
type: array
items:
$ref: "#/components/schemas/Issue"
description: Error response for known errors
ServerErrorResponse:
type: object
required:
- errors
properties:
errors:
type: array
items:
type: object
required:
- message
properties:
message:
type: string
minItems: 1
maxItems: 1
description: Error response for unkown server errors
# Workflow Details
QuotedRouteItem:
type: object
required:
- type
- net_effect
- pieces_info
properties:
type:
type: string
enum: [ONRAMP, ONCHAIN_STEP, USER_FUND]
net_effect:
$ref: "#/components/schemas/EffectAmount"
pieces_info:
type: array
items:
$ref: "#/components/schemas/PieceInfo"
step_index:
type: number
FulfilledRouteItem:
type: object
required:
- status
- type
- net_effect
- pieces_info
properties:
status:
type: string
enum: [PENDING, COMPLETE, UNREACHABLE, FAILED]
type:
type: string
enum: [ONRAMP, ONCHAIN_STEP, USER_FUND]
net_effect:
$ref: "#/components/schemas/EffectAmount"
pieces_info:
type: array
items:
$ref: "#/components/schemas/PieceInfo"
step_index:
type: number
transaction_hash:
type: string
description: Blockchain transaction hash for the step
PieceInfo:
type: object
required:
- type
properties:
type:
type: string
enum: [onramp, poll, bridge, transfer_out, rev_share, convert]
Effect:
type: object
required:
- consume
- produce
properties:
consume:
type: array
items:
$ref: "#/components/schemas/Change"
produce:
type: array
items:
$ref: "#/components/schemas/Change"
ChangeAmount:
type: object
required:
- account
- resource
- amount
properties:
account:
type: string
enum: [USER, DEST, HALLIDAY, PROCESSING_ADDRESS, REV_SHARE, BRIDGE]
resource:
$ref: "#/components/schemas/Resource"
amount:
$ref: "#/components/schemas/Amount"
EffectAmount:
type: object
required:
- consume
- produce
properties:
consume:
type: array
items:
$ref: "#/components/schemas/ChangeAmount"
produce:
type: array
items:
$ref: "#/components/schemas/ChangeAmount"
Change:
type: object
required:
- account
- resource
- amount
properties:
account:
type: string
enum: [USER, DEST, HALLIDAY, PROCESSING_ADDRESS, REV_SHARE, BRIDGE]
resource:
$ref: "#/components/schemas/Resource"
amount:
type: string
Resource:
type: object
required:
- asset
- property
properties:
asset:
type: string
property:
type: string
enum: [APPROVAL, BALANCE]
tags:
- name: Chains
description: Blockchain network information and configuration
- name: Assets
description: Asset information, discovery, and supported asset pairs
- name: Payments
description: Core payment operations including quotes, confirmation, and status tracking