# 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"]}}}}}}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.onside.io/onside-flow/onside-flow-api-1.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.