OpenAPI Specification
openapi: 3.1.0
info:
title: Fordefi Address Book Swaps API
version: 0.2.0
description: These endpoints allow you to list the contacts in your address book.<br><br>To add/remove contacts, visit the Fordefi web console. See the <a href='https://docs.fordefi.com/user-guide/address-book'>user guide</a> for more info.
servers:
- url: https://api.fordefi.com/
description: Production
security:
- bearerAuth: []
tags:
- name: Swaps
description: These endpoints allow you to manage swaps.
paths:
/api/v1/swaps/providers/{chain_type}:
get:
tags:
- Swaps
summary: Get Providers
description: Get providers for a chain type.
operationId: get_providers_api_v1_swaps_providers__chain_type__get
parameters:
- name: chain_type
in: path
required: true
schema:
$ref: '#/components/schemas/ChainType'
description: Chain type to get providers for.
description: Chain type to get providers for.
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/GetProvidersResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/PreconditionFailedError'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
'500':
description: Unexpected Error
content:
application/json:
schema:
$ref: '#/components/schemas/BaseError'
'401':
description: Unauthorized User
content:
application/json:
schema:
$ref: '#/components/schemas/BaseError'
'403':
description: Forbidden User
content:
application/json:
schema:
$ref: '#/components/schemas/BaseError'
'408':
description: Request Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/BaseError'
'429':
description: Rate Limit Exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/RateLimitError'
/api/v1/swaps/quotes:
post:
tags:
- Swaps
summary: Get Quotes
description: Get available quotes for a swap between two assets.
operationId: get_quotes_api_v1_swaps_quotes_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/GetQuotesRequest'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/GetQuotesResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/PreconditionFailedError'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
'500':
description: Unexpected Error
content:
application/json:
schema:
$ref: '#/components/schemas/BaseError'
'401':
description: Unauthorized User
content:
application/json:
schema:
$ref: '#/components/schemas/BaseError'
'403':
description: Forbidden User
content:
application/json:
schema:
$ref: '#/components/schemas/BaseError'
'408':
description: Request Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/BaseError'
'429':
description: Rate Limit Exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/RateLimitError'
/api/v1/swaps:
post:
tags:
- Swaps
summary: Create Transaction
description: Create a new spot swap.
operationId: create_transaction_api_v1_swaps_post
parameters:
- name: x-signature
in: header
required: false
schema:
description: Signature of the body. Base64 encoded string. If the request is made programatically by an API user, signing of the request is required and is intended to protect you from malicious backends. `x_signature` is valid for 120 seconds.
title: X-Signature
type: string
example: SGVsbG8=
description: Signature of the body. Base64 encoded string. If the request is made programatically by an API user, signing of the request is required and is intended to protect you from malicious backends. `x_signature` is valid for 120 seconds.
- name: x-timestamp
in: header
required: false
schema:
description: Timestamp of the signature. Integer. Specify an Epoch date. If the request is made programatically by an API user, the timestamp of the request is required and is intended to protect you from replay attacks.
title: X-Timestamp
type: integer
description: Timestamp of the signature. Integer. Specify an Epoch date. If the request is made programatically by an API user, the timestamp of the request is required and is intended to protect you from replay attacks.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateSpotSwapRequest'
responses:
'201':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/SpotSwap'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/DefinedPreconditionError_CreateSwapErrorType_'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
'500':
description: Unexpected Error
content:
application/json:
schema:
$ref: '#/components/schemas/BaseError'
'401':
description: Unauthorized User
content:
application/json:
schema:
$ref: '#/components/schemas/BaseError'
'403':
description: Forbidden User
content:
application/json:
schema:
$ref: '#/components/schemas/BaseError'
'408':
description: Request Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/BaseError'
'429':
description: Rate Limit Exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/RateLimitError'
/api/v1/swaps/predict:
post:
tags:
- Swaps
summary: Predict Transaction
description: 'Simulate the spot swap and changes in token
balances, in addition to the fee estimation.'
operationId: predict_transaction_api_v1_swaps_predict_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PredictSpotSwapRequest'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/PredictedSpotSwap'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/DefinedPreconditionError_PredictSwapErrorType_'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
'500':
description: Unexpected Error
content:
application/json:
schema:
$ref: '#/components/schemas/BaseError'
'401':
description: Unauthorized User
content:
application/json:
schema:
$ref: '#/components/schemas/BaseError'
'403':
description: Forbidden User
content:
application/json:
schema:
$ref: '#/components/schemas/BaseError'
'408':
description: Request Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/BaseError'
'429':
description: Rate Limit Exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/RateLimitError'
components:
schemas:
TonTransactionMessage:
properties:
address:
$ref: '#/components/schemas/TonAccountRepr'
description: The sender of the message in a user friendly format.
amount:
type: string
pattern: ^\d+$
title: Amount
description: The amount of nano tons to send.
example: '1000000000000000000'
payload:
title: Payload
description: The payload of the message.
type: string
state_init:
title: State Init
description: The state_init structure contains all the necessary information required to create the initial state of a smart contract.
type: string
comment:
title: Comment
description: A comment that is attached to the message.
type: string
type: object
required:
- address
- amount
title: TonTransactionMessage
StarknetTransactionResult:
properties:
reversion:
$ref: '#/components/schemas/StarknetReversion'
description: Details whether the transaction was reverted or not.
fees:
$ref: '#/components/schemas/StarknetFees'
description: The total fee of the first transaction on the trace.
effects:
$ref: '#/components/schemas/StarknetEffects'
description: The effects of the transaction.
type: object
required:
- reversion
- fees
- effects
title: StarknetTransactionResult
SuiCommandGasCoinArgument:
properties:
type:
type: string
const: gas_coin
title: Type
description: The type of the command argument.
type: object
required:
- type
title: SuiCommandGasCoinArgument
description: The object for the SUI coin used to pay for gas.
SuiObjectRef:
properties:
digest:
type: string
maxLength: 44
minLength: 32
pattern: ^[a-km-zA-HJ-NP-Z1-9]+$
title: Digest
description: The digest of the object.
example: 9K8mnqJdxf3B7vgFmRhj9JqKqsN5AxvSgWk5faGshEta
object_id:
type: string
maxLength: 66
minLength: 66
pattern: ^0[xX][a-fA-F0-9]+$
title: Object Id
description: The id of the object.
example: '0x3300c18e7b931bdfc73dccf3e2d043ad1c9d120c777fff5aeeb9956224e5247a'
version:
type: string
pattern: ^0*[1-9]\d*$
title: Version
description: The version of the object.
example: '1000000000000000000'
type: object
required:
- digest
- object_id
- version
title: SuiObjectRef
SolanaJitoFeeTypeRequest:
properties:
type:
type: string
const: jito
title: Type
description: Jito broadcast mode.
details:
oneOf:
- $ref: '#/components/schemas/JitoCustomFeeRequest'
- $ref: '#/components/schemas/JitoPriorityFeeRequest'
description: The details of the Jito fee.
discriminator:
propertyName: type
mapping:
custom: '#/components/schemas/JitoCustomFeeRequest'
priority: '#/components/schemas/JitoPriorityFeeRequest'
type: object
required:
- type
- details
title: SolanaJitoFeeTypeRequest
DynamicGasFields:
properties:
max_priority_fee_per_gas:
type: string
pattern: ^\d+$
title: Max Priority Fee Per Gas
description: The maximum tip amount for mining the transaction.
example: '1000000000000000000'
max_fee_per_gas:
type: string
pattern: ^\d+$
title: Max Fee Per Gas
description: The maximum amount paid for the fee.
example: '1000000000000000000'
type: object
required:
- max_priority_fee_per_gas
- max_fee_per_gas
title: DynamicGasFields
StacksAddressBookContactAddressRef:
properties:
chain_type:
type: string
const: stacks
title: Chain Type
description: The type of the chain.
address:
type: string
maxLength: 171
pattern: ^S[0-9A-Za-z._-]+$
title: Address
description: The address on the Stacks chain.
example: SP3J4NWQXC312DK0GXVRZKSRFBZG8S5FG1D2160E9
chains:
items:
$ref: '#/components/schemas/StacksChain'
type: array
title: Chains
description: The chains the contact belongs to.
memo:
title: Memo
description: Memo is an additional address feature used for identifying a recipient.
type: string
type: object
required:
- chain_type
- address
- chains
title: StacksAddressBookContactAddressRef
SuiFundsWithdrawalSource:
type: string
enum:
- sender
- sponsor
title: SuiFundsWithdrawalSource
SuiPureStringInput:
properties:
type:
type: string
const: string_pure_input
title: Type
description: The type of the pure input.
value:
type: string
title: Value
description: The string value of the pure input argument.
type: object
required:
- type
- value
title: SuiPureStringInput
ApprovalRequestState:
type: string
enum:
- created
- approved
- insufficient_approvers
- auto_approved
- failed
title: ApprovalRequestState
description: Represents the whole approval request state
SuiBalanceChangeEffect:
properties:
priced_asset:
$ref: '#/components/schemas/PricedAsset'
description: The asset information.
diff:
type: string
pattern: ^-?\d+$
title: Diff
description: The amount of that was added to or deducted from the owner's balance. If the amount was deducted, the value is negative; if the amount was added, the value is positive.
example: '1000000000000000000'
address:
$ref: '#/components/schemas/EnrichedSuiAddress'
description: The address affected by the balance change.
type: object
required:
- priced_asset
- diff
- address
title: SuiBalanceChangeEffect
PredictedSolanaTransaction:
properties:
policy_match:
description: The policy match.
$ref: '#/components/schemas/PolicyMatch'
matched_policies:
items:
$ref: '#/components/schemas/PolicyMatch'
type: array
title: Matched Policies
description: List of policies matched by the transactions in the batch.
approval_request:
description: The approval request.
$ref: '#/components/schemas/ApprovalRequest'
risks:
items:
$ref: '#/components/schemas/TransactionRisk'
type: array
title: Risks
description: The list of risks associated with this transaction.
note:
title: Note
description: An optional transaction note.
type: string
tx_policy_explanation_id:
title: Tx Policy Explanation Id
description: The id of the transaction policy explanation produced for this prediction, if any.
type: string
format: uuid
aml_policy_match:
description: The AML policy match.
$ref: '#/components/schemas/AmlPolicyMatchOutgoing'
aml_results:
description: The AML results.
$ref: '#/components/schemas/AmlResults'
simulation_status_result:
description: Whether simulation succeeded, reverted or failed.
$ref: '#/components/schemas/SimulationStatusResult'
expected_result:
$ref: '#/components/schemas/SolanaTransactionResult'
description: The expected result of the transaction in case it is mined.
chain:
$ref: '#/components/schemas/EnrichedSolanaChain'
description: The details of the chain that this message is on.
solana_transaction_type_details:
oneOf:
- $ref: '#/components/schemas/SolanaNativeTransferDetails'
- $ref: '#/components/schemas/SolanaTokenTransferDetails'
- $ref: '#/components/schemas/SolanaRawTransactionDetails'
- $ref: '#/components/schemas/PredictedSolanaSpotSwapDetails'
description: Details of the Solana transaction based on its type.
discriminator:
propertyName: type
mapping:
native_transfer: '#/components/schemas/SolanaNativeTransferDetails'
raw_transaction: '#/components/schemas/SolanaRawTransactionDetails'
spot_swap: '#/components/schemas/PredictedSolanaSpotSwapDetails'
token_transfer: '#/components/schemas/SolanaTokenTransferDetails'
sender:
$ref: '#/components/schemas/EnrichedSolanaAddress'
description: The sender of the transaction.
suggested_fees:
$ref: '#/components/schemas/PrioritySolanaSuggestedFees'
description: The suggested fees.
instructions:
items:
$ref: '#/components/schemas/SolanaCompiledInstruction'
type: array
title: Instructions
description: The instructions of the transaction.
raw_transaction:
title: Raw Transaction
description: The serialized transaction encoded as a base64 string
type: string
example: SGVsbG8=
was_fee_set_in_request:
type: boolean
title: Was Fee Set In Request
description: Whether the priority fee was already set in the request with a ComputeBudget instruction.
fee_payer:
description: The address that pays the fee for this transaction (first account in the transaction).
$ref: '#/components/schemas/EnrichedSolanaAddress'
type:
type: string
const: solana_transaction
title: Type
description: The type of the transaction.
type: object
required:
- matched_policies
- risks
- expected_result
- chain
- solana_transaction_type_details
- sender
- suggested_fees
- instructions
- was_fee_set_in_request
- type
title: PredictedSolanaTransaction
ArchAddressBookContactAddressRef:
properties:
chain_type:
type: string
const: arch
title: Chain Type
description: The type of the chain.
address:
type: string
maxLength: 44
minLength: 32
pattern: ^[a-km-zA-HJ-NP-Z1-9]+$
title: Address
description: The address on the Arch chain.
example: 4fYNw3dojWmQ4dXtSGE9epjRGy9pFSx62YypT7avPYvA
chains:
items:
$ref: '#/components/schemas/ArchChain'
type: array
title: Chains
description: The chains the contact belongs to.
type: object
required:
- chain_type
- address
- chains
title: ArchAddressBookContactAddressRef
StellarReversionState:
type: string
enum:
- not_reverted
- unknown_revert
- insufficient_funds_gas_and_value
title: StellarReversionState
SuiPublishCommand:
properties:
type:
type: string
const: publish
title: Type
description: The type of the command.
modules:
items:
type: string
example: SGVsbG8=
type: array
title: Modules
description: The modules to publish.
dependencies:
items:
type: string
type: array
title: Dependencies
description: The dependencies of the modules.
type: object
required:
- type
- modules
- dependencies
title: SuiPublishCommand
description: Publish a Move module.
UtxoEffects:
properties:
inputs:
items:
$ref: '#/components/schemas/UtxoInput'
type: array
title: Inputs
description: The inputs of the transaction.
outputs:
items:
$ref: '#/components/schemas/UtxoOutput'
type: array
title: Outputs
description: The outputs of the transaction.
balance_changes:
items:
$ref: '#/components/schemas/UtxoBalanceChangeEffect'
type: array
title: Balance Changes
description: The aggregated balance changes of vaults.
total_value:
type: string
pattern: ^\d+$
title: Total Value
description: The total value of the transaction.
example: '1000000000000000000'
priced_asset:
$ref: '#/components/schemas/PricedAsset'
description: The asset information.
type: object
required:
- inputs
- outputs
- balance_changes
- total_value
- priced_asset
title: UtxoEffects
AptosEffects:
properties:
balance_changes:
items:
$ref: '#/components/schemas/AptosBalanceChangeEffect'
type: array
title: Balance Changes
transfers:
items:
$ref: '#/components/schemas/AptosTransferEffect'
type: array
title: Transfers
type: object
required:
- balance_changes
- transfers
title: AptosEffects
TransactionPolicyMatchActionType:
type: string
enum:
- allow
- block
- require_approval
title: TransactionPolicyMatchActionType
ExchangeInternalTransferDetails:
properties:
is_internal:
type: boolean
title: Is Internal
description: Is this transfer an internal transfer between two vaults.
sender:
$ref: '#/components/schemas/EnrichedExchangeAddress'
description: The sender of the transaction.
type:
type: string
const: internal_transfer
title: Type
description: A transaction from one exchange vault to another.
recipient:
$ref: '#/components/schemas/EnrichedExchangeAddress'
description: The recipient of the transfer.
type: object
required:
- is_internal
- sender
- type
- recipient
title: ExchangeInternalTransferDetails
DirectMessagesList:
properties:
format:
type: string
const: direct
title: Format
messages:
items:
$ref: '#/components/schemas/DirectMessage'
type: array
title: Messages
description: List of messages in direct format.
type: object
required:
- format
- messages
title: DirectMessagesList
SolanaMessage:
properties:
id:
type: string
format: uuid
title: Id
description: The unique identifier of the object in the Fordefi platform.
created_at:
type: string
format: date-time
title: Created At
description: The date and time when the object was created.
modified_at:
type: string
format: date-time
title: Modified At
description: The date and time when the object was last modified. Any change to any field of the resource is considered a modification.
managed_transaction_data:
description: 'Managed transaction data. Presented if the transaction was initiated from the Fordefi system itself, in contrast to unmanaged transactions (which are, for example, transfers of funds into a vault visible to Fordefi). '
$ref: '#/components/schemas/ManagedTransactionData'
signatures:
items:
$ref: '#/components/schemas/Signature'
type: array
title: Signatures
description: The transaction signatures.
note:
title: Note
description: An optional transaction note.
type: string
spam_state:
$ref: '#/components/schemas/TransactionSpamState'
description: '`automatically_set` if the transaction was automatically set as spam by Fordefi, `manually_set` if the transaction was manually set as spam by a user, and `unset` if the transaction was not set as spam.'
default: unset
direction:
$ref: '#/components/schemas/TransactionDirection'
description: The direction of the transaction.
signed_externally:
type: boolean
title: Signed Externally
description: Whether the transaction was signed by an external user (for example in case of imported vault).
default: false
interacted_vaults:
items:
$ref: '#/components/schemas/VaultRef'
type: array
title: Interacted Vaults
description: The vaults that interacted with the transaction.
related_transactions:
title: Related Transactions
description: The related transactions.
items:
$ref: '#/components/schemas/RelatedTransaction'
type: array
organization_id:
type: string
format: uuid
title: Organization Id
description: The organization that the transaction belongs to.
state:
$ref: '#/components/schemas/NonPushableTransactionState'
description: The state of the message.
state_changes:
items:
$ref: '#/components/schemas/NonPushableTransactionStateChange'
type: array
title: State Changes
description: The state changes of the message.
type:
type: string
const: solana_message
title: Type
description: Solana message type.
solana_message_type:
$ref: '#/components/schemas/SolanaMessageType'
description: The type of the Solana message.
solana_message_type_details:
oneOf:
- $ref: '#/components/schemas/PersonalMessageDetails'
- $ref: '#/components/schemas/CreateSessionDetails'
description: The details of the Solana message.
discriminator:
propertyName: type
mapping:
create_session_message_type: '#/components/schemas/CreateSessionDetails'
personal_message_type: '#/components/schemas/PersonalMessageDetails'
expected_result:
description: Predicted result of the message execution. Only available for intents that Fordefi knows how to simulate, like ERC20 allowances and swaps created in the Fordefi app.
$ref: '#/components/schemas/SolanaMessageResult'
string_data:
type: string
title: String Data
description: The message as a string.
raw_data:
type: string
title: Raw Data
description: The raw data of the message, encoded in base64
example: SGVsbG8=
chain:
$ref: '#/components/schemas/EnrichedSolanaChain'
description: The details of the chain that this message is on.
sender:
$ref: '#/components/schemas/EnrichedSolanaAddress'
description: The sender of the message.
type: object
required:
- id
- created_at
- modified_at
- signatures
- direction
- interacted_vaults
- organization_id
- state
- state_changes
- type
- solana_message_type
- solana_message_type_details
- string_data
- raw_data
- chain
- sender
title: SolanaMessage
GetQuotesResponse:
properties:
providers_with_quote:
items:
$ref: '#/components/schemas/ProviderWithQuote'
type: array
title: Providers With Quote
description: The providers with quote.
type: object
required:
- providers_with_quote
title: GetQuotesResponse
PersonRef:
properties:
id:
type: string
format: uuid
title: Id
description: The unique identifier of the user in the Fordefi platform.
user_type:
type: string
const: person
title: User Type
description: The type of user. Can be a person, or (in programmatic scenarios) an API user or API Signer.
name:
title: Name
description: The name of the user.
example: John Doe
type: string
email:
type: string
title: Email
description: The email of the user.
state:
$ref: '#/components/schemas/UserState'
description: The state of the user in the organization.
role:
$ref: '#/components/schemas/UserRole'
description: The role of the user.
type: object
required:
- id
- user_type
- email
- state
- role
title: PersonRef
EvmChain:
properties:
chain_type:
type: string
const: evm
title: Chain Type
description: The type of the chain.
named_chain_id:
title: EvmChainName
description: The EVM chain name can be either one of those supported by the default chains below or a custom chain name if one was added to your organization. <ul><li>`arbitrum_mainnet`</li><li>`arbitrum_sepolia`</li><li>`aster_mainnet`</li><li>`avalanche_chain`</li><li>`avalanche_fuji`</li><li>`base_mainnet`</li><li>`berachain_mainnet`</li><li>`blast_mainnet`</li><li>`bsc_mainnet`</li><li>`canto_mainnet`</li><li>`clink_mainnet`</li><li>`clink_testnet`</li><li>`conflux_mainnet`</li><li>`dymension_mainnet`</li><li>`ethereum_goerli`</li><li>`ethereum_holesky`</li><li>`ethereum_mainnet`</li><li>`ethereum_sepolia`</li><li>`fantom_mainnet`</li><li>`flare_mainnet`</li><li>`flare_testnet`</li><li>`gnosis_mainnet`</li><li>`hypercore_mainnet`</li><li>`hyperevm_mainnet`</li><li>`ink_mainnet`</li><li>`kava_mainnet`</li><li>`katana_mainnet`</li><li>`linea_mainnet`</li><li>`optimism_mainnet`</li><li>`pharos_mainnet`</li><li>`plasma_mainnet`</li><li>`manta_pacific_mainnet`</li><li>`mantle_mainnet`</li><li>`merlin_mainnet`</li><li>`monad_mainnet`</li><li>`polygon_mainnet`</li><li>`polygon_mumbai`</li><li>`polygon_zkevm_mainnet`</li><li>`reya_mainnet`</li><li>`robinhood_mainnet`</li><li>`rootstock_mainnet`</li><li>`scroll_mainnet`</li><li>`sei_mainnet`</li><li>`sonic_mainnet`</li><li>`tempo_mainnet`</li><li>`unichain_mainnet`</li><li>`xai_mainnet`</li><li>`x_layer_mainnet`</li><li>`zero_gravity_mainnet`</li><li>`zeta_mainnet`</li><li>`zklink_nova_mainnet`</li><li>`zksync_era_mainnet`</li></ul>
# --- truncated at 32 KB (635 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/fordefi/refs/heads/main/openapi/fordefi-swaps-api-openapi.yml