# Onside Flow API

## list orders

> Retrieves a list of orders for the current API key. The response includes all orders created by the API key, with optional filters for user ID, status, and date range.

```json
{"openapi":"3.0.1","info":{"title":"Onside Flow API","version":"v1"},"servers":[{"url":"https://api.flow.onside.io"}],"paths":{"/v1/merchant/orders":{"get":{"summary":"list orders","description":"Retrieves a list of orders for the current API key. The response includes all orders created by the API key, with optional filters for user ID, status, and date range.","parameters":[{"name":"X-Api-Key","in":"header","required":true,"description":"API key for authentication. Must be included in the request header.","schema":{"type":"string"}},{"name":"X-Signature","in":"header","required":true,"description":"Signature for verifying the request. Must be included in the request header.","schema":{"type":"string"}},{"name":"start_date","in":"query","required":true,"description":"Start date for filtering orders (ISO 8601 format)","schema":{"type":"string"}},{"name":"end_date","in":"query","required":true,"description":"End date for filtering orders (ISO 8601 format)","schema":{"type":"string"}},{"name":"user_id","in":"query","description":"Filter orders by user ID","schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"string","enum":["creating","transfer_pending","cancelled","completed","deposit_received","kyc_required","refund_initiated","refund_completed","refund_failed","creation_blocked","creation_rate_limited","deposit_only"]},"description":"Filter orders by status"}],"responses":{"200":{"description":"successful","content":{"application/json":{"schema":{"type":"object","properties":{"total_count":{"type":"integer","description":"Total number of orders matching the criteria"},"orders":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The order ID"},"status":{"type":"string","enum":["creating","transfer_pending","cancelled","completed","deposit_received","kyc_required","refund_initiated","refund_completed","refund_failed","creation_blocked","creation_rate_limited","deposit_only"],"description":"Initial order status will be 'creating'"},"withdraw_address":{"type":"object","description":"Address where exchanged funds will be sent","properties":{"address":{"type":"string","description":"Address where funds will be sent"},"destination_tag":{"type":"string","description":"Optional destination tag if provided","nullable":true},"memo":{"type":"string","description":"Optional memo if provided","nullable":true}},"required":["address"]},"pair":{"type":"object","properties":{"id":{"type":"string","description":"Pair ID in format 'TOFROM'"},"from_token":{"type":"object","description":"The source token the user is sending as part of the swap","properties":{"id":{"type":"string","description":"Token ID"},"name":{"type":"string","description":"Token name"},"full_name":{"type":"string","description":"Full name of the token"},"decimals_before":{"type":"integer","description":"Number of decimal places before the decimal point"},"decimals_after":{"type":"integer","description":"Number of decimal places after the decimal point"},"icon":{"type":"string","format":"uri","description":"URL to the token icon"}},"required":["id","name","full_name","icon"]},"from_chain":{"type":"object","description":"The source chain the user is using as part of the swap","properties":{"id":{"type":"string","description":"Chain ID"},"name":{"type":"string","description":"Chain name"},"icon":{"type":"string","format":"uri","description":"URL to the chain icon"},"token_icon":{"type":"string","format":"uri","description":"URL of the token icon image for the exchange pair (size: 120×120 px)"}},"required":["id","name","icon"]},"to_token":{"type":"object","description":"The destination token the user is receiving as part of the swap","properties":{"id":{"type":"string","description":"Token ID"},"name":{"type":"string","description":"Token name"},"full_name":{"type":"string","description":"Full name of the token"},"decimals_before":{"type":"integer","description":"Number of decimal places before the decimal point"},"decimals_after":{"type":"integer","description":"Number of decimal places after the decimal point"},"icon":{"type":"string","format":"uri","description":"URL to the token icon"}},"required":["id","name","full_name","icon"]},"to_chain":{"type":"object","description":"The destination chain the user is using as part of the swap","properties":{"id":{"type":"string","description":"Chain ID"},"name":{"type":"string","description":"Chain name"},"icon":{"type":"string","format":"uri","description":"URL to the chain icon"},"token_icon":{"type":"string","format":"uri","description":"URL of the token icon image for the exchange pair (size: 120×120 px)"}},"required":["id","name","icon"]}},"required":["id","from_token","from_chain","to_token","to_chain"]},"created_at":{"type":"number","description":"Order creation time in seconds since epoch"},"user_confirmed_payment":{"type":"boolean","description":"Indicates if the user has confirmed the payment"},"rate":{"type":"string","description":"Exchange rate for the order"},"min_deposit_amount":{"type":"string","description":"Minimum amount for the token"},"max_deposit_amount":{"type":"string","description":"Maximum amount for the token"},"unique_reference":{"type":"string","description":"Unique reference for the order"},"withdrawal_fee":{"type":"string","description":"Withdrawal fee for the order"},"deposit_address":{"type":"object","description":"Address where the user should send the funds","properties":{"address":{"type":"string","description":"Address where funds will be sent"},"destination_tag":{"type":"string","description":"Optional destination tag if provided","nullable":true},"memo":{"type":"string","description":"Optional memo if provided","nullable":true}},"required":["address"]},"expires_at":{"type":"number","description":"Order expiration time in seconds since epoch"},"transactions":{"type":"array","items":{"type":"object","properties":{"tx_id":{"type":"string","description":"Transaction hash"},"tx_link":{"type":"string","format":"uri","description":"Link to view the transaction on a block explorer"},"type":{"type":"string","enum":["deposit","withdrawal","refund"],"description":"Type of transaction"},"time":{"type":"number","description":"Transaction time in seconds since epoch"},"amount":{"type":"string","description":"Amount involved in the transaction"},"from_token":{"type":"object","description":"The source token the user is sending as part of the swap. Available only for deposit transactions","properties":{"id":{"type":"string","description":"Token ID"},"name":{"type":"string","description":"Token name"},"full_name":{"type":"string","description":"Full name of the token"},"decimals_before":{"type":"integer","description":"Number of decimal places before the decimal point"},"decimals_after":{"type":"integer","description":"Number of decimal places after the decimal point"},"icon":{"type":"string","format":"uri","description":"URL to the token icon"}},"required":["id","name","full_name","icon"]},"from_chain":{"type":"object","description":"The source chain the user is using as part of the swap. Available only for deposit transactions","properties":{"id":{"type":"string","description":"Chain ID"},"name":{"type":"string","description":"Chain name"},"icon":{"type":"string","format":"uri","description":"URL to the chain icon"},"token_icon":{"type":"string","format":"uri","description":"URL of the token icon image for the exchange pair (size: 120×120 px)"}},"required":["id","name","icon"]},"to_token":{"type":"object","description":"The destination token the user is receiving as part of the swap. Available only for withdrawal transactions","properties":{"id":{"type":"string","description":"Token ID"},"name":{"type":"string","description":"Token name"},"full_name":{"type":"string","description":"Full name of the token"},"decimals_before":{"type":"integer","description":"Number of decimal places before the decimal point"},"decimals_after":{"type":"integer","description":"Number of decimal places after the decimal point"},"icon":{"type":"string","format":"uri","description":"URL to the token icon"}},"required":["id","name","full_name","icon"]},"to_chain":{"type":"object","description":"The destination chain the user is using as part of the swap. Available only for withdrawal transactions","properties":{"id":{"type":"string","description":"Chain ID"},"name":{"type":"string","description":"Chain name"},"icon":{"type":"string","format":"uri","description":"URL to the chain icon"},"token_icon":{"type":"string","format":"uri","description":"URL of the token icon image for the exchange pair (size: 120×120 px)"}},"required":["id","name","icon"]}},"required":["tx_id","type","time","amount"]}}},"required":["id","status","withdraw_address"]}}},"required":["total_count","orders"]}}}},"400":{"description":"bad request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message indicating what parameter is missing"}},"required":["error"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message indicating what parameter is missing"}},"required":["error"]}}}}}}}}}
```

## get merchant configuration

> This endpoint retrieves the configuration for a merchant to set up an on-ramp transaction. It requires an API key and various parameters to specify the token, chain, and withdrawal address. The response includes a signed URL for the on-ramp transaction.

```json
{"openapi":"3.0.1","info":{"title":"Onside Flow API","version":"v1"},"servers":[{"url":"https://api.flow.onside.io"}],"paths":{"/v1/merchants/configuration":{"get":{"summary":"get merchant configuration","description":"This endpoint retrieves the configuration for a merchant to set up an on-ramp transaction. It requires an API key and various parameters to specify the token, chain, and withdrawal address. The response includes a signed URL for the on-ramp transaction.","parameters":[{"name":"api_key","in":"query","required":true,"description":"API key for authentication","schema":{"type":"string"}},{"name":"token","in":"query","schema":{"type":"string","enum":["sol"]},"required":true,"description":"The destination token ID (currently only supporting 'sol')"},{"name":"chain","in":"query","schema":{"type":"string","enum":["sol"]},"required":false,"description":"The destination token blockchain. If not provided, it can be selected by available chains if there's only one supported. If multiple chains support this token, this parameter should be required."},{"name":"withdraw_address","in":"query","schema":{"type":"string"},"required":true,"description":"Address where exchanged funds will be sent"},{"name":"withdraw_address_tag","in":"query","schema":{"type":"string"},"required":false,"description":"Optional destination tag for certain cryptocurrencies"},{"name":"withdraw_address_memo","in":"query","schema":{"type":"string"},"required":false,"description":"Optional memo for certain cryptocurrencies"},{"name":"onramp_amount","in":"query","schema":{"type":"number"},"required":false,"description":"Optionally specify the amount for the on-ramp transaction in the fiat currency"},{"name":"onramp_fiat","in":"query","schema":{"type":"string"},"required":false,"description":"Optionally specify the fiat currency for the on-ramp transaction. The list of supported fiat currencies can be obtained from https://docs.onramper.com/docs/fiat-currency-support"},{"name":"user_id","in":"query","schema":{"type":"string"},"required":false,"description":"The user ID for tracking purposes. This is optional and can be used to associate the request with a specific user."}],"responses":{"200":{"description":"successful","content":{"application/json":{"schema":{"type":"object","properties":{"configuration":{"type":"object","properties":{"name":{"type":"string","description":"Merchant name"},"api_key":{"type":"string","description":"API key"},"onramp_url":{"type":"string","format":"uri","description":"Signed URL for on-ramp transactions"},"theme":{"type":"object","properties":{"light":{"type":"object","description":"Light theme configuration"},"dark":{"type":"object","description":"Dark theme configuration"}},"required":["light","dark"]}},"required":["api_key","onramp_url"]}},"required":["configuration"]}}}},"400":{"description":"bad request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message returned when no exchange pairs are available for the requested token"}},"required":["error"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message returned when api key is missing or invalid"}},"required":["error"]}}}}}}}}}
```

## create exchange order

> Creates a new exchange order for the specified trading pair and the withdraw address.

```json
{"openapi":"3.0.1","info":{"title":"Onside Flow API","version":"v1"},"servers":[{"url":"https://api.flow.onside.io"}],"paths":{"/v1/orders":{"post":{"summary":"create exchange order","description":"Creates a new exchange order for the specified trading pair and the withdraw address.","parameters":[{"name":"api_key","in":"query","required":true,"description":"API key for authentication","schema":{"type":"string"}},{"name":"signature","in":"query","required":false,"description":"Signature for authentication request if required by the API key. The signature is generated using the withdraw address and the secret key of the API key.","schema":{"type":"string"}},{"name":"pair_id","in":"query","schema":{"type":"string"},"required":true,"description":"The pair ID in format 'FROMTO' (e.g., 'BTCETH'). Available pair IDs can be obtained from the GET /v1/tokens endpoint."},{"name":"withdraw_address","in":"query","schema":{"type":"string"},"required":true,"description":"Address where exchanged funds will be sent"},{"name":"withdraw_address_tag","in":"query","schema":{"type":"string"},"required":false,"description":"Optional destination tag for certain cryptocurrencies"},{"name":"withdraw_address_memo","in":"query","schema":{"type":"string"},"required":false,"description":"Optional memo for certain cryptocurrencies"},{"name":"user_id","in":"query","schema":{"type":"string"},"required":false,"description":"Optional user ID for associating the order with a specific user. If not provided, the order will be associated with the user’s IP address."}],"responses":{"201":{"description":"order created","content":{"application/json":{"schema":{"type":"object","properties":{"order":{"type":"object","properties":{"id":{"type":"string","description":"The order ID"},"status":{"type":"string","enum":["creating","transfer_pending","cancelled","completed","deposit_received","kyc_required","refund_initiated","refund_completed","refund_failed","creation_blocked","creation_rate_limited","deposit_only"],"description":"Initial order status will be 'creating'"},"withdraw_address":{"type":"object","description":"Address where exchanged funds will be sent","properties":{"address":{"type":"string","description":"Address where funds will be sent"},"destination_tag":{"type":"string","description":"Optional destination tag if provided","nullable":true},"memo":{"type":"string","description":"Optional memo if provided","nullable":true}},"required":["address"]},"pair":{"type":"object","properties":{"id":{"type":"string","description":"Pair ID in format 'TOFROM'"},"from_token":{"type":"object","description":"The source token the user is sending as part of the swap","properties":{"id":{"type":"string","description":"Token ID"},"name":{"type":"string","description":"Token name"},"full_name":{"type":"string","description":"Full name of the token"},"decimals_before":{"type":"integer","description":"Number of decimal places before the decimal point"},"decimals_after":{"type":"integer","description":"Number of decimal places after the decimal point"},"icon":{"type":"string","format":"uri","description":"URL to the token icon"}},"required":["id","name","full_name","icon"]},"from_chain":{"type":"object","description":"The source chain the user is using as part of the swap","properties":{"id":{"type":"string","description":"Chain ID"},"name":{"type":"string","description":"Chain name"},"icon":{"type":"string","format":"uri","description":"URL to the chain icon"},"token_icon":{"type":"string","format":"uri","description":"URL of the token icon image for the exchange pair (size: 120×120 px)"}},"required":["id","name","icon"]},"to_token":{"type":"object","description":"The destination token the user is receiving as part of the swap","properties":{"id":{"type":"string","description":"Token ID"},"name":{"type":"string","description":"Token name"},"full_name":{"type":"string","description":"Full name of the token"},"decimals_before":{"type":"integer","description":"Number of decimal places before the decimal point"},"decimals_after":{"type":"integer","description":"Number of decimal places after the decimal point"},"icon":{"type":"string","format":"uri","description":"URL to the token icon"}},"required":["id","name","full_name","icon"]},"to_chain":{"type":"object","description":"The destination chain the user is using as part of the swap","properties":{"id":{"type":"string","description":"Chain ID"},"name":{"type":"string","description":"Chain name"},"icon":{"type":"string","format":"uri","description":"URL to the chain icon"},"token_icon":{"type":"string","format":"uri","description":"URL of the token icon image for the exchange pair (size: 120×120 px)"}},"required":["id","name","icon"]}},"required":["id","from_token","from_chain","to_token","to_chain"]},"created_at":{"type":"number","description":"Order creation time in seconds since epoch"},"user_confirmed_payment":{"type":"boolean","description":"Indicates if the user has confirmed the payment"},"rate":{"type":"string","description":"Exchange rate for the order"},"min_deposit_amount":{"type":"string","description":"Minimum amount for the token"},"max_deposit_amount":{"type":"string","description":"Maximum amount for the token"},"unique_reference":{"type":"string","description":"Unique reference for the order"},"withdrawal_fee":{"type":"string","description":"Withdrawal fee for the order"},"deposit_address":{"type":"object","description":"Address where the user should send the funds","properties":{"address":{"type":"string","description":"Address where funds will be sent"},"destination_tag":{"type":"string","description":"Optional destination tag if provided","nullable":true},"memo":{"type":"string","description":"Optional memo if provided","nullable":true}},"required":["address"]},"expires_at":{"type":"number","description":"Order expiration time in seconds since epoch"},"transactions":{"type":"array","items":{"type":"object","properties":{"tx_id":{"type":"string","description":"Transaction hash"},"tx_link":{"type":"string","format":"uri","description":"Link to view the transaction on a block explorer"},"type":{"type":"string","enum":["deposit","withdrawal","refund"],"description":"Type of transaction"},"time":{"type":"number","description":"Transaction time in seconds since epoch"},"amount":{"type":"string","description":"Amount involved in the transaction"},"from_token":{"type":"object","description":"The source token the user is sending as part of the swap. Available only for deposit transactions","properties":{"id":{"type":"string","description":"Token ID"},"name":{"type":"string","description":"Token name"},"full_name":{"type":"string","description":"Full name of the token"},"decimals_before":{"type":"integer","description":"Number of decimal places before the decimal point"},"decimals_after":{"type":"integer","description":"Number of decimal places after the decimal point"},"icon":{"type":"string","format":"uri","description":"URL to the token icon"}},"required":["id","name","full_name","icon"]},"from_chain":{"type":"object","description":"The source chain the user is using as part of the swap. Available only for deposit transactions","properties":{"id":{"type":"string","description":"Chain ID"},"name":{"type":"string","description":"Chain name"},"icon":{"type":"string","format":"uri","description":"URL to the chain icon"},"token_icon":{"type":"string","format":"uri","description":"URL of the token icon image for the exchange pair (size: 120×120 px)"}},"required":["id","name","icon"]},"to_token":{"type":"object","description":"The destination token the user is receiving as part of the swap. Available only for withdrawal transactions","properties":{"id":{"type":"string","description":"Token ID"},"name":{"type":"string","description":"Token name"},"full_name":{"type":"string","description":"Full name of the token"},"decimals_before":{"type":"integer","description":"Number of decimal places before the decimal point"},"decimals_after":{"type":"integer","description":"Number of decimal places after the decimal point"},"icon":{"type":"string","format":"uri","description":"URL to the token icon"}},"required":["id","name","full_name","icon"]},"to_chain":{"type":"object","description":"The destination chain the user is using as part of the swap. Available only for withdrawal transactions","properties":{"id":{"type":"string","description":"Chain ID"},"name":{"type":"string","description":"Chain name"},"icon":{"type":"string","format":"uri","description":"URL to the chain icon"},"token_icon":{"type":"string","format":"uri","description":"URL of the token icon image for the exchange pair (size: 120×120 px)"}},"required":["id","name","icon"]}},"required":["tx_id","type","time","amount"]}}},"required":["id","status","withdraw_address"]},"compliance_notice":{"type":"string","description":"Compliance notice for the user's country, if applicable","nullable":true}},"required":["order"]}}}},"400":{"description":"bad request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message indicating what parameter is missing"}},"required":["error"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message returned when api key is missing or invalid"}},"required":["error"]}}}},"403":{"description":"forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message returned when access is restricted from the user's country"}},"required":["error"]}}}},"404":{"description":"pair not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message when the requested pair doesn't exist"}},"required":["error"]}}}},"503":{"description":"service unavailable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message when there's an error creating the order"}},"required":["error"]}}}}}}}}}
```

## refresh order

> Refreshes the status of an existing order.

```json
{"openapi":"3.0.1","info":{"title":"Onside Flow API","version":"v1"},"servers":[{"url":"https://api.flow.onside.io"}],"paths":{"/v1/orders/{id}/refresh":{"patch":{"summary":"refresh order","description":"Refreshes the status of an existing order.","parameters":[{"name":"api_key","in":"query","required":true,"description":"API key for authentication","schema":{"type":"string"}},{"name":"signature","in":"query","required":false,"description":"Signature for authentication request if required by the API key. The signature is generated using the withdraw address and the secret key of the API key.","schema":{"type":"string"}},{"name":"id","in":"path","schema":{"type":"string"},"required":true,"description":"The ID of the order to refresh"}],"responses":{"200":{"description":"order refreshed","content":{"application/json":{"schema":{"type":"object","properties":{"order":{"type":"object","properties":{"id":{"type":"string","description":"The order ID"},"status":{"type":"string","enum":["creating","transfer_pending","cancelled","completed","deposit_received","kyc_required","refund_initiated","refund_completed","refund_failed","creation_blocked","creation_rate_limited","deposit_only"],"description":"Initial order status will be 'creating'"},"withdraw_address":{"type":"object","description":"Address where exchanged funds will be sent","properties":{"address":{"type":"string","description":"Address where funds will be sent"},"destination_tag":{"type":"string","description":"Optional destination tag if provided","nullable":true},"memo":{"type":"string","description":"Optional memo if provided","nullable":true}},"required":["address"]},"pair":{"type":"object","properties":{"id":{"type":"string","description":"Pair ID in format 'TOFROM'"},"from_token":{"type":"object","description":"The source token the user is sending as part of the swap","properties":{"id":{"type":"string","description":"Token ID"},"name":{"type":"string","description":"Token name"},"full_name":{"type":"string","description":"Full name of the token"},"decimals_before":{"type":"integer","description":"Number of decimal places before the decimal point"},"decimals_after":{"type":"integer","description":"Number of decimal places after the decimal point"},"icon":{"type":"string","format":"uri","description":"URL to the token icon"}},"required":["id","name","full_name","icon"]},"from_chain":{"type":"object","description":"The source chain the user is using as part of the swap","properties":{"id":{"type":"string","description":"Chain ID"},"name":{"type":"string","description":"Chain name"},"icon":{"type":"string","format":"uri","description":"URL to the chain icon"},"token_icon":{"type":"string","format":"uri","description":"URL of the token icon image for the exchange pair (size: 120×120 px)"}},"required":["id","name","icon"]},"to_token":{"type":"object","description":"The destination token the user is receiving as part of the swap","properties":{"id":{"type":"string","description":"Token ID"},"name":{"type":"string","description":"Token name"},"full_name":{"type":"string","description":"Full name of the token"},"decimals_before":{"type":"integer","description":"Number of decimal places before the decimal point"},"decimals_after":{"type":"integer","description":"Number of decimal places after the decimal point"},"icon":{"type":"string","format":"uri","description":"URL to the token icon"}},"required":["id","name","full_name","icon"]},"to_chain":{"type":"object","description":"The destination chain the user is using as part of the swap","properties":{"id":{"type":"string","description":"Chain ID"},"name":{"type":"string","description":"Chain name"},"icon":{"type":"string","format":"uri","description":"URL to the chain icon"},"token_icon":{"type":"string","format":"uri","description":"URL of the token icon image for the exchange pair (size: 120×120 px)"}},"required":["id","name","icon"]}},"required":["id","from_token","from_chain","to_token","to_chain"]},"created_at":{"type":"number","description":"Order creation time in seconds since epoch"},"user_confirmed_payment":{"type":"boolean","description":"Indicates if the user has confirmed the payment"},"rate":{"type":"string","description":"Exchange rate for the order"},"min_deposit_amount":{"type":"string","description":"Minimum amount for the token"},"max_deposit_amount":{"type":"string","description":"Maximum amount for the token"},"unique_reference":{"type":"string","description":"Unique reference for the order"},"withdrawal_fee":{"type":"string","description":"Withdrawal fee for the order"},"deposit_address":{"type":"object","description":"Address where the user should send the funds","properties":{"address":{"type":"string","description":"Address where funds will be sent"},"destination_tag":{"type":"string","description":"Optional destination tag if provided","nullable":true},"memo":{"type":"string","description":"Optional memo if provided","nullable":true}},"required":["address"]},"expires_at":{"type":"number","description":"Order expiration time in seconds since epoch"},"transactions":{"type":"array","items":{"type":"object","properties":{"tx_id":{"type":"string","description":"Transaction hash"},"tx_link":{"type":"string","format":"uri","description":"Link to view the transaction on a block explorer"},"type":{"type":"string","enum":["deposit","withdrawal","refund"],"description":"Type of transaction"},"time":{"type":"number","description":"Transaction time in seconds since epoch"},"amount":{"type":"string","description":"Amount involved in the transaction"},"from_token":{"type":"object","description":"The source token the user is sending as part of the swap. Available only for deposit transactions","properties":{"id":{"type":"string","description":"Token ID"},"name":{"type":"string","description":"Token name"},"full_name":{"type":"string","description":"Full name of the token"},"decimals_before":{"type":"integer","description":"Number of decimal places before the decimal point"},"decimals_after":{"type":"integer","description":"Number of decimal places after the decimal point"},"icon":{"type":"string","format":"uri","description":"URL to the token icon"}},"required":["id","name","full_name","icon"]},"from_chain":{"type":"object","description":"The source chain the user is using as part of the swap. Available only for deposit transactions","properties":{"id":{"type":"string","description":"Chain ID"},"name":{"type":"string","description":"Chain name"},"icon":{"type":"string","format":"uri","description":"URL to the chain icon"},"token_icon":{"type":"string","format":"uri","description":"URL of the token icon image for the exchange pair (size: 120×120 px)"}},"required":["id","name","icon"]},"to_token":{"type":"object","description":"The destination token the user is receiving as part of the swap. Available only for withdrawal transactions","properties":{"id":{"type":"string","description":"Token ID"},"name":{"type":"string","description":"Token name"},"full_name":{"type":"string","description":"Full name of the token"},"decimals_before":{"type":"integer","description":"Number of decimal places before the decimal point"},"decimals_after":{"type":"integer","description":"Number of decimal places after the decimal point"},"icon":{"type":"string","format":"uri","description":"URL to the token icon"}},"required":["id","name","full_name","icon"]},"to_chain":{"type":"object","description":"The destination chain the user is using as part of the swap. Available only for withdrawal transactions","properties":{"id":{"type":"string","description":"Chain ID"},"name":{"type":"string","description":"Chain name"},"icon":{"type":"string","format":"uri","description":"URL to the chain icon"},"token_icon":{"type":"string","format":"uri","description":"URL of the token icon image for the exchange pair (size: 120×120 px)"}},"required":["id","name","icon"]}},"required":["tx_id","type","time","amount"]}}},"required":["id","status","withdraw_address"]},"compliance_notice":{"type":"string","description":"Compliance notice for the user's country, if applicable","nullable":true}},"required":["order"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message returned when api key is missing or invalid"}},"required":["error"]}}}},"403":{"description":"forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message returned when access is restricted from the user's country"}},"required":["error"]}}}},"404":{"description":"order not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message when the requested order doesn't exist"}},"required":["error"]}}}}}}}}}
```

## cancel order

> Cancels an existing order.

```json
{"openapi":"3.0.1","info":{"title":"Onside Flow API","version":"v1"},"servers":[{"url":"https://api.flow.onside.io"}],"paths":{"/v1/orders/{id}/cancel":{"patch":{"summary":"cancel order","description":"Cancels an existing order.","parameters":[{"name":"api_key","in":"query","required":true,"description":"API key for authentication","schema":{"type":"string"}},{"name":"signature","in":"query","required":false,"description":"Signature for authentication request if required by the API key. The signature is generated using the withdraw address and the secret key of the API key.","schema":{"type":"string"}},{"name":"id","in":"path","schema":{"type":"string"},"required":true,"description":"The ID of the order to refresh"}],"responses":{"200":{"description":"order cancelled","content":{"application/json":{"schema":{"type":"object","properties":{"order":{"type":"object","properties":{"id":{"type":"string","description":"The order ID"},"status":{"type":"string","enum":["creating","transfer_pending","cancelled","completed","deposit_received","kyc_required","refund_initiated","refund_completed","refund_failed","creation_blocked","creation_rate_limited","deposit_only"],"description":"Initial order status will be 'creating'"},"withdraw_address":{"type":"object","description":"Address where exchanged funds will be sent","properties":{"address":{"type":"string","description":"Address where funds will be sent"},"destination_tag":{"type":"string","description":"Optional destination tag if provided","nullable":true},"memo":{"type":"string","description":"Optional memo if provided","nullable":true}},"required":["address"]},"pair":{"type":"object","properties":{"id":{"type":"string","description":"Pair ID in format 'TOFROM'"},"from_token":{"type":"object","description":"The source token the user is sending as part of the swap","properties":{"id":{"type":"string","description":"Token ID"},"name":{"type":"string","description":"Token name"},"full_name":{"type":"string","description":"Full name of the token"},"decimals_before":{"type":"integer","description":"Number of decimal places before the decimal point"},"decimals_after":{"type":"integer","description":"Number of decimal places after the decimal point"},"icon":{"type":"string","format":"uri","description":"URL to the token icon"}},"required":["id","name","full_name","icon"]},"from_chain":{"type":"object","description":"The source chain the user is using as part of the swap","properties":{"id":{"type":"string","description":"Chain ID"},"name":{"type":"string","description":"Chain name"},"icon":{"type":"string","format":"uri","description":"URL to the chain icon"},"token_icon":{"type":"string","format":"uri","description":"URL of the token icon image for the exchange pair (size: 120×120 px)"}},"required":["id","name","icon"]},"to_token":{"type":"object","description":"The destination token the user is receiving as part of the swap","properties":{"id":{"type":"string","description":"Token ID"},"name":{"type":"string","description":"Token name"},"full_name":{"type":"string","description":"Full name of the token"},"decimals_before":{"type":"integer","description":"Number of decimal places before the decimal point"},"decimals_after":{"type":"integer","description":"Number of decimal places after the decimal point"},"icon":{"type":"string","format":"uri","description":"URL to the token icon"}},"required":["id","name","full_name","icon"]},"to_chain":{"type":"object","description":"The destination chain the user is using as part of the swap","properties":{"id":{"type":"string","description":"Chain ID"},"name":{"type":"string","description":"Chain name"},"icon":{"type":"string","format":"uri","description":"URL to the chain icon"},"token_icon":{"type":"string","format":"uri","description":"URL of the token icon image for the exchange pair (size: 120×120 px)"}},"required":["id","name","icon"]}},"required":["id","from_token","from_chain","to_token","to_chain"]},"created_at":{"type":"number","description":"Order creation time in seconds since epoch"},"user_confirmed_payment":{"type":"boolean","description":"Indicates if the user has confirmed the payment"},"rate":{"type":"string","description":"Exchange rate for the order"},"min_deposit_amount":{"type":"string","description":"Minimum amount for the token"},"max_deposit_amount":{"type":"string","description":"Maximum amount for the token"},"unique_reference":{"type":"string","description":"Unique reference for the order"},"withdrawal_fee":{"type":"string","description":"Withdrawal fee for the order"},"deposit_address":{"type":"object","description":"Address where the user should send the funds","properties":{"address":{"type":"string","description":"Address where funds will be sent"},"destination_tag":{"type":"string","description":"Optional destination tag if provided","nullable":true},"memo":{"type":"string","description":"Optional memo if provided","nullable":true}},"required":["address"]},"expires_at":{"type":"number","description":"Order expiration time in seconds since epoch"},"transactions":{"type":"array","items":{"type":"object","properties":{"tx_id":{"type":"string","description":"Transaction hash"},"tx_link":{"type":"string","format":"uri","description":"Link to view the transaction on a block explorer"},"type":{"type":"string","enum":["deposit","withdrawal","refund"],"description":"Type of transaction"},"time":{"type":"number","description":"Transaction time in seconds since epoch"},"amount":{"type":"string","description":"Amount involved in the transaction"},"from_token":{"type":"object","description":"The source token the user is sending as part of the swap. Available only for deposit transactions","properties":{"id":{"type":"string","description":"Token ID"},"name":{"type":"string","description":"Token name"},"full_name":{"type":"string","description":"Full name of the token"},"decimals_before":{"type":"integer","description":"Number of decimal places before the decimal point"},"decimals_after":{"type":"integer","description":"Number of decimal places after the decimal point"},"icon":{"type":"string","format":"uri","description":"URL to the token icon"}},"required":["id","name","full_name","icon"]},"from_chain":{"type":"object","description":"The source chain the user is using as part of the swap. Available only for deposit transactions","properties":{"id":{"type":"string","description":"Chain ID"},"name":{"type":"string","description":"Chain name"},"icon":{"type":"string","format":"uri","description":"URL to the chain icon"},"token_icon":{"type":"string","format":"uri","description":"URL of the token icon image for the exchange pair (size: 120×120 px)"}},"required":["id","name","icon"]},"to_token":{"type":"object","description":"The destination token the user is receiving as part of the swap. Available only for withdrawal transactions","properties":{"id":{"type":"string","description":"Token ID"},"name":{"type":"string","description":"Token name"},"full_name":{"type":"string","description":"Full name of the token"},"decimals_before":{"type":"integer","description":"Number of decimal places before the decimal point"},"decimals_after":{"type":"integer","description":"Number of decimal places after the decimal point"},"icon":{"type":"string","format":"uri","description":"URL to the token icon"}},"required":["id","name","full_name","icon"]},"to_chain":{"type":"object","description":"The destination chain the user is using as part of the swap. Available only for withdrawal transactions","properties":{"id":{"type":"string","description":"Chain ID"},"name":{"type":"string","description":"Chain name"},"icon":{"type":"string","format":"uri","description":"URL to the chain icon"},"token_icon":{"type":"string","format":"uri","description":"URL of the token icon image for the exchange pair (size: 120×120 px)"}},"required":["id","name","icon"]}},"required":["tx_id","type","time","amount"]}}},"required":["id","status","withdraw_address"]},"compliance_notice":{"type":"string","description":"Compliance notice for the user's country, if applicable","nullable":true}},"required":["order"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message returned when api key is missing or invalid"}},"required":["error"]}}}},"403":{"description":"forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message returned when access is restricted from the user's country"}},"required":["error"]}}}},"404":{"description":"order not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message when the requested order doesn't exist"}},"required":["error"]}}}}}}}}}
```

## mark order as paid

> Marks an existing order as paid.

```json
{"openapi":"3.0.1","info":{"title":"Onside Flow API","version":"v1"},"servers":[{"url":"https://api.flow.onside.io"}],"paths":{"/v1/orders/{id}/mark_as_paid":{"patch":{"summary":"mark order as paid","description":"Marks an existing order as paid.","parameters":[{"name":"api_key","in":"query","required":true,"description":"API key for authentication","schema":{"type":"string"}},{"name":"signature","in":"query","required":false,"description":"Signature for authentication request if required by the API key. The signature is generated using the withdraw address and the secret key of the API key.","schema":{"type":"string"}},{"name":"id","in":"path","schema":{"type":"string"},"required":true,"description":"The ID of the order to refresh"}],"responses":{"200":{"description":"order marked as paid","content":{"application/json":{"schema":{"type":"object","properties":{"order":{"type":"object","properties":{"id":{"type":"string","description":"The order ID"},"status":{"type":"string","enum":["creating","transfer_pending","cancelled","completed","deposit_received","kyc_required","refund_initiated","refund_completed","refund_failed","creation_blocked","creation_rate_limited","deposit_only"],"description":"Initial order status will be 'creating'"},"withdraw_address":{"type":"object","description":"Address where exchanged funds will be sent","properties":{"address":{"type":"string","description":"Address where funds will be sent"},"destination_tag":{"type":"string","description":"Optional destination tag if provided","nullable":true},"memo":{"type":"string","description":"Optional memo if provided","nullable":true}},"required":["address"]},"pair":{"type":"object","properties":{"id":{"type":"string","description":"Pair ID in format 'TOFROM'"},"from_token":{"type":"object","description":"The source token the user is sending as part of the swap","properties":{"id":{"type":"string","description":"Token ID"},"name":{"type":"string","description":"Token name"},"full_name":{"type":"string","description":"Full name of the token"},"decimals_before":{"type":"integer","description":"Number of decimal places before the decimal point"},"decimals_after":{"type":"integer","description":"Number of decimal places after the decimal point"},"icon":{"type":"string","format":"uri","description":"URL to the token icon"}},"required":["id","name","full_name","icon"]},"from_chain":{"type":"object","description":"The source chain the user is using as part of the swap","properties":{"id":{"type":"string","description":"Chain ID"},"name":{"type":"string","description":"Chain name"},"icon":{"type":"string","format":"uri","description":"URL to the chain icon"},"token_icon":{"type":"string","format":"uri","description":"URL of the token icon image for the exchange pair (size: 120×120 px)"}},"required":["id","name","icon"]},"to_token":{"type":"object","description":"The destination token the user is receiving as part of the swap","properties":{"id":{"type":"string","description":"Token ID"},"name":{"type":"string","description":"Token name"},"full_name":{"type":"string","description":"Full name of the token"},"decimals_before":{"type":"integer","description":"Number of decimal places before the decimal point"},"decimals_after":{"type":"integer","description":"Number of decimal places after the decimal point"},"icon":{"type":"string","format":"uri","description":"URL to the token icon"}},"required":["id","name","full_name","icon"]},"to_chain":{"type":"object","description":"The destination chain the user is using as part of the swap","properties":{"id":{"type":"string","description":"Chain ID"},"name":{"type":"string","description":"Chain name"},"icon":{"type":"string","format":"uri","description":"URL to the chain icon"},"token_icon":{"type":"string","format":"uri","description":"URL of the token icon image for the exchange pair (size: 120×120 px)"}},"required":["id","name","icon"]}},"required":["id","from_token","from_chain","to_token","to_chain"]},"created_at":{"type":"number","description":"Order creation time in seconds since epoch"},"user_confirmed_payment":{"type":"boolean","description":"Indicates if the user has confirmed the payment"},"rate":{"type":"string","description":"Exchange rate for the order"},"min_deposit_amount":{"type":"string","description":"Minimum amount for the token"},"max_deposit_amount":{"type":"string","description":"Maximum amount for the token"},"unique_reference":{"type":"string","description":"Unique reference for the order"},"withdrawal_fee":{"type":"string","description":"Withdrawal fee for the order"},"deposit_address":{"type":"object","description":"Address where the user should send the funds","properties":{"address":{"type":"string","description":"Address where funds will be sent"},"destination_tag":{"type":"string","description":"Optional destination tag if provided","nullable":true},"memo":{"type":"string","description":"Optional memo if provided","nullable":true}},"required":["address"]},"expires_at":{"type":"number","description":"Order expiration time in seconds since epoch"},"transactions":{"type":"array","items":{"type":"object","properties":{"tx_id":{"type":"string","description":"Transaction hash"},"tx_link":{"type":"string","format":"uri","description":"Link to view the transaction on a block explorer"},"type":{"type":"string","enum":["deposit","withdrawal","refund"],"description":"Type of transaction"},"time":{"type":"number","description":"Transaction time in seconds since epoch"},"amount":{"type":"string","description":"Amount involved in the transaction"},"from_token":{"type":"object","description":"The source token the user is sending as part of the swap. Available only for deposit transactions","properties":{"id":{"type":"string","description":"Token ID"},"name":{"type":"string","description":"Token name"},"full_name":{"type":"string","description":"Full name of the token"},"decimals_before":{"type":"integer","description":"Number of decimal places before the decimal point"},"decimals_after":{"type":"integer","description":"Number of decimal places after the decimal point"},"icon":{"type":"string","format":"uri","description":"URL to the token icon"}},"required":["id","name","full_name","icon"]},"from_chain":{"type":"object","description":"The source chain the user is using as part of the swap. Available only for deposit transactions","properties":{"id":{"type":"string","description":"Chain ID"},"name":{"type":"string","description":"Chain name"},"icon":{"type":"string","format":"uri","description":"URL to the chain icon"},"token_icon":{"type":"string","format":"uri","description":"URL of the token icon image for the exchange pair (size: 120×120 px)"}},"required":["id","name","icon"]},"to_token":{"type":"object","description":"The destination token the user is receiving as part of the swap. Available only for withdrawal transactions","properties":{"id":{"type":"string","description":"Token ID"},"name":{"type":"string","description":"Token name"},"full_name":{"type":"string","description":"Full name of the token"},"decimals_before":{"type":"integer","description":"Number of decimal places before the decimal point"},"decimals_after":{"type":"integer","description":"Number of decimal places after the decimal point"},"icon":{"type":"string","format":"uri","description":"URL to the token icon"}},"required":["id","name","full_name","icon"]},"to_chain":{"type":"object","description":"The destination chain the user is using as part of the swap. Available only for withdrawal transactions","properties":{"id":{"type":"string","description":"Chain ID"},"name":{"type":"string","description":"Chain name"},"icon":{"type":"string","format":"uri","description":"URL to the chain icon"},"token_icon":{"type":"string","format":"uri","description":"URL of the token icon image for the exchange pair (size: 120×120 px)"}},"required":["id","name","icon"]}},"required":["tx_id","type","time","amount"]}}},"required":["id","status","withdraw_address"]},"compliance_notice":{"type":"string","description":"Compliance notice for the user's country, if applicable","nullable":true}},"required":["order"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message returned when api key is missing or invalid"}},"required":["error"]}}}},"403":{"description":"forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message returned when access is restricted from the user's country"}},"required":["error"]}}}},"404":{"description":"order not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message when the requested order doesn't exist"}},"required":["error"]}}}}}}}}}
```

## list tokens

> Get a list of available tokens and their supported blockchains for exchange. This endpoint returns a list of tokens that can be exchanged, along with their supported blockchains. The response includes the token ID, name, icon URL, and the chains on which the token is available.

```json
{"openapi":"3.0.1","info":{"title":"Onside Flow API","version":"v1"},"servers":[{"url":"https://api.flow.onside.io"}],"paths":{"/v1/tokens":{"get":{"summary":"list tokens","description":"Get a list of available tokens and their supported blockchains for exchange. This endpoint returns a list of tokens that can be exchanged, along with their supported blockchains. The response includes the token ID, name, icon URL, and the chains on which the token is available.","parameters":[{"name":"api_key","in":"query","required":true,"description":"API key for authentication","schema":{"type":"string"}},{"name":"to_token","in":"query","schema":{"type":"string","enum":["sol"]},"required":true,"description":"The destination token ID (currently only supporting 'sol')"},{"name":"to_chain","in":"query","schema":{"type":"string","enum":["sol"]},"required":false,"description":"The destination token blockchain. If not provided, it can be selected by available chains if there's only one supported. If multiple chains support this token, this parameter should be required."},{"name":"user_id","in":"query","schema":{"type":"string"},"required":false,"description":"The user ID for tracking purposes. This is optional and can be used to associate the request with a specific user."}],"responses":{"200":{"description":"successful","content":{"application/json":{"schema":{"type":"object","properties":{"tokens":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the token"},"name":{"type":"string","description":"Display name of the token"},"full_name":{"type":"string","description":"Full name of the token"},"icon":{"type":"string","format":"uri","description":"URL of the token icon image (size: 120×120 px)"},"decimals_before":{"type":"integer","description":"Number of decimal places before the decimal point"},"decimals_after":{"type":"integer","description":"Number of decimal places after the decimal point"},"chains":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the blockchain"},"name":{"type":"string","description":"Display name of the blockchain"},"icon":{"type":"string","format":"uri","description":"URL of the blockchain icon image (size: 120×120 px)"},"pair_id":{"type":"string","description":"Unique identifier of the exchange pair"},"token_icon":{"type":"string","format":"uri","description":"URL of the token icon image for the exchange pair (size: 120×120 px)"},"token_big_icon":{"type":"string","format":"uri","description":"URL of the token big icon image for the exchange pair (size: 384×384 px)"},"rate":{"type":"string","description":"Exchange rate for the order"},"min_deposit_amount":{"type":"string","description":"Minimum amount for the token"},"max_deposit_amount":{"type":"string","description":"Maximum amount for the token"},"withdrawal_fee":{"type":"string","description":"Withdrawal fee for the order"}},"required":["id","name","icon","token_icon","token_big_icon","rate","min_deposit_amount","max_deposit_amount","withdrawal_fee"]}}},"required":["id","name","full_name","icon","decimals_before","decimals_after","chains"]}},"to_token":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the destination token"},"name":{"type":"string","description":"Display name of the destination token"},"full_name":{"type":"string","description":"Full name of the destination token"},"icon":{"type":"string","format":"uri","description":"URL of the destination token icon image (size: 120×120 px)"},"decimals_before":{"type":"integer","description":"Number of decimal places before the decimal point for the destination token"},"decimals_after":{"type":"integer","description":"Number of decimal places after the decimal point for the destination token"}},"required":["id","name","full_name","icon","decimals_before","decimals_after"]},"compliance_notice":{"type":"string","description":"Compliance notice for the user's country, if applicable","nullable":true}},"required":["tokens"]}}}},"400":{"description":"bad request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message returned when no exchange pairs are available for the requested token"}},"required":["error"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message returned when api key is missing or invalid"}},"required":["error"]}}}},"403":{"description":"forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message returned when access is restricted from the user's country"}},"required":["error"]}}}}}}}}}
```