Documentation
Documentation
https://docs.sushi.com/api/examples/swap
Documentation
https://docs.sushi.com/api/examples/quote
OpenAPI Specification
openapi: 3.0.0
info:
title: Blade Deposit Quote API
description: Documentation for interacting with the Blade API
version: 2.0.0
contact:
email: aggregators@shipyardsoftware.org
name: Blade API Support
servers:
- url: https://blade-api.sushi.com
description: Blade API Production Server
security:
- ApiKeyAuth: []
tags:
- name: Quote
description: Quote generation and signing
paths:
/rfq/v2/quote/{chainId}:
get:
tags:
- Quote
summary: Generate a quote
description: This endpoint facilitates the creation of a potential quote for executing a swap between two assets. It allows users to obtain pricing information and other essential details necessary to initiate asset swaps within the system. Use this endpoint to explore the potential cost and feasibility of asset exchanges before finalizing transactions.
operationId: generateQuote
parameters:
- name: chainId
in: path
description: ID of the blockchain network
required: true
schema:
type: integer
example: 137
- name: pool_address
in: query
description: Address of the pool. If not present, the best pool will be calculated
required: false
schema:
type: string
example: '0x655eDCE464CC797526600a462A8154650EEe4B77'
- name: time_in_seconds
in: query
description: Amount of time between accepting a quote and receiving the quote on the blockchain. As this value increases, the quote will get worse for the user.
required: false
schema:
type: integer
example: 30
- name: output_amount
in: query
description: Desired quantity of assets to receive as part of the swap. This field is mutually exclusive with `input_amount`
required: false
schema:
type: string
example: '18000'
- name: input_amount
in: query
description: Desired quantity of assets you are willing to exchange. This field is mutually exclusive with `output_amount`
required: false
schema:
type: string
example: '18000'
- name: input_asset_symbol
in: query
description: Identifier of the asset you want to provide for the swap. Should correspond to the asset name returned from the pool call
required: true
schema:
type: string
example: ETH
- name: output_asset_symbol
in: query
description: Identifier of the asset you want to receive in the swap. Should correspond to the asset name returned from the pool call
required: true
schema:
type: string
example: DAI
responses:
'200':
description: Quote generated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/QuoteResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'409':
$ref: '#/components/responses/QuoteProblems'
'422':
$ref: '#/components/responses/InvalidInputData'
'500':
$ref: '#/components/responses/InternalServerError'
'503':
$ref: '#/components/responses/ExternalServiceError'
/rfq/sign:
post:
tags:
- Quote
summary: Sign a quote for swap execution
description: This endpoint plays a pivotal role in the preparation and execution of secure asset swaps on the blockchain. By providing a Quote ID and a destination address, users can initiate the signing process, resulting in the generation of the essential signature and transaction data. This signature and data package, in turn, is integral for ensuring the validity and security of asset transfers within the blockchain network.
operationId: signQuote
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SignRequest'
examples:
without-calldata:
summary: Sign without calldata
description: Sign a quote and manually use the values in the response to create the transaction
value:
destination_address: '0x960376b3F62f41E7e66809a05D1C5afdFD60A0E9'
quote_id: 4c707e45-7019-4b81-b875-c5eb6fe061d6
with-calldata:
summary: Sign with calldata
description: Sign a quote and get the bytes representation of the swap to be sent directly to the pool contract for execution
value:
destination_address: '0x960376b3F62f41E7e66809a05D1C5afdFD60A0E9'
quote_id: 4c707e45-7019-4b81-b875-c5eb6fe061d6
calldata: true
aux_data: '0x31494e4348000000000000000000000000000000000000000000000000000000'
with-native-input:
summary: Sign with native input token
description: Sign a quote using native input token (e.g. raw ETH) and get the bytes representation of the swap
value:
destination_address: '0x960376b3F62f41E7e66809a05D1C5afdFD60A0E9'
quote_id: 4c707e45-7019-4b81-b875-c5eb6fe061d6
calldata: true
aux_data: '0x31494e4348000000000000000000000000000000000000000000000000000000'
native_input: true
responses:
'200':
description: Quote signed successfully
content:
application/json:
schema:
$ref: '#/components/schemas/SignResponse'
examples:
without-calldata-response:
summary: Sign Response without calldata
description: Response when signing a quote without requesting calldata
value:
chain_id: 1
input_asset_address: '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2'
output_asset_address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48'
input_amount: '10000000000000000000'
output_amount: '5661947917'
good_until: '364238673390486983853316167090878487969884185392043445686993915855904'
destination_address: '0x960376b3F62f41E7e66809a05D1C5afdFD60A0E9'
signature:
v: 28
r: '0xfb8599e4ef2c89b03e1ebc3067f0ba38ecea64517bafa932e5c642318ec923d9'
s: '0x1d3c7e38951b23bc459ac91ad668dede2a681bc4c98b915116983f4ae1dcdaa7'
clipper_exchange_address: '0xE7b0CE0526fbE3969035a145C9e9691d4d9D216c'
with-calldata-response:
summary: Sign Response with calldata
description: Response when signing a quote with calldata for direct contract execution
value:
chain_id: 1
input_asset_address: '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2'
output_asset_address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48'
input_amount: '10000000000000000000'
output_amount: '5661947917'
good_until: '364266596581665814407146313234570973398742125152679878859837657433201'
destination_address: '0x960376b3F62f41E7e66809a05D1C5afdFD60A0E9'
signature:
v: 28
r: '0x762ad0475b3a7c42735686d7911f117a2ff6fca1bc3c5c75f4ee43df8da2a61b'
s: '0x1eceffea0a50d12566e9fa6b4d9ed826106143d321389654c3c327c648f6f3f6'
clipper_exchange_address: '0xE7b0CE0526fbE3969035a145C9e9691d4d9D216c'
calldata: '0x2b651a6c000000000000000000000000c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2000000000000000000000000a0b86991c6218b36c1d19d4a2e9eb0ce3606eb480000000000000000000000000000000000000000000000008ac7230489e8000000000000000000000000000000000000000000000000000000000001517a780d0000000d82eb0b930000000005f7906e00b1a2bc2ec50000006400bc6529c471000000000000000000000000960376b3f62f41e7e66809a05d1c5afdfd60a0e9000000000000000000000000000000000000000000000000000000000000001c762ad0475b3a7c42735686d7911f117a2ff6fca1bc3c5c75f4ee43df8da2a61b1eceffea0a50d12566e9fa6b4d9ed826106143d321389654c3c327c648f6f3f60000000000000000000000000000000000000000000000000000000000000140000000000000000000000000000000000000000000000000000000000000002031494e4348000000000000000000000000000000000000000000000000000000'
with-native-input-response:
summary: Sign Response with native input
description: Response when signing a quote with native input token (e.g. raw ETH)
value:
chain_id: 1
input_asset_address: '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2'
output_asset_address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48'
input_amount: '10000000000000000000'
output_amount: '5661947917'
good_until: '364126526759930684504042968316937832960196094624343681678885719229598'
destination_address: '0x960376b3F62f41E7e66809a05D1C5afdFD60A0E9'
signature:
v: 28
r: '0x1a8fc0856ff121e3ba5a244ee0837cef3d6c6ea96c593decc1b9d074c74c0139'
s: '0x60bd1d8700fca625b58cbc4fe84c61b29bf46c9855146eda18da557ab0e079d5'
clipper_exchange_address: '0xE7b0CE0526fbE3969035a145C9e9691d4d9D216c'
calldata: '0x27a9b424000000000000000000000000a0b86991c6218b36c1d19d4a2e9eb0ce3606eb480000000000000000000000000000000000000000000000008ac7230489e8000000000000000000000000000000000000000000000000000000000001517a780d0000000d81968de90000000005f7911f00b1a2bc2ec50000006400bc6529c49e000000000000000000000000960376b3f62f41e7e66809a05d1c5afdfd60a0e9000000000000000000000000000000000000000000000000000000000000001c1a8fc0856ff121e3ba5a244ee0837cef3d6c6ea96c593decc1b9d074c74c013960bd1d8700fca625b58cbc4fe84c61b29bf46c9855146eda18da557ab0e079d50000000000000000000000000000000000000000000000000000000000000120000000000000000000000000000000000000000000000000000000000000002031494e4348000000000000000000000000000000000000000000000000000000'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'422':
$ref: '#/components/responses/InvalidInputData'
'500':
$ref: '#/components/responses/InternalServerError'
'503':
$ref: '#/components/responses/ExternalServiceError'
/rfq/v2/quote-sign/{chainId}:
get:
tags:
- Quote
summary: Quote and sign in one request
description: This endpoint streamlines the swap process by combining the quote generation and signing steps into a single request. Users can obtain real-time pricing information for an asset swap and simultaneously receive the required signature and transaction data for execution on the blockchain. This unified flow reduces latency, simplifies integration, and ensures secure, ready-to-broadcast transactions without the need for multiple API calls.
operationId: quoteAndSign
parameters:
- name: chainId
in: path
description: ID of the blockchain network
required: true
schema:
type: integer
example: 137
- name: pool_address
in: query
description: Address of the pool. If not present, the best pool will be calculated
required: false
schema:
type: string
example: '0x655eDCE464CC797526600a462A8154650EEe4B77'
- name: time_in_seconds
in: query
description: Amount of time between accepting a quote and receiving the quote on the blockchain. As this value increases, the quote will get worse for the user.
required: false
schema:
type: integer
example: 30
- name: output_amount
in: query
description: Desired quantity of assets to receive as part of the swap. This field is mutually exclusive with `input_amount`
required: false
schema:
type: string
example: '18000'
- name: input_amount
in: query
description: Desired quantity of assets you are willing to exchange. This field is mutually exclusive with `output_amount`
required: false
schema:
type: string
example: '18000'
- name: input_asset_symbol
in: query
description: Identifier of the asset you want to provide for the swap. Should correspond to the asset name returned from the pool call
required: true
schema:
type: string
example: ETH
- name: output_asset_symbol
in: query
description: Identifier of the asset you want to receive in the swap. Should correspond to the asset name returned from the pool call
required: true
schema:
type: string
example: DAI
- name: destination_address
in: query
description: Address that will receive the output token
required: true
schema:
type: string
example: '0x960376b3F62f41E7e66809a05D1C5afdFD60A0E9'
- name: sender_address
in: query
description: For DEX aggregator partners that are using their own smart contract to mediate the interaction between users and Blade. Aggregators should use the address of the account that they will pull tokens from (i.e., the EOA user address) as opposed to the address of their deployed contract. By default, `destination_address` will be used.
required: false
schema:
type: string
example: '0x960376b3F62f41E7e66809a05D1C5afdFD60A0E9'
- name: aux_data
in: query
description: For use with the calldata swap feature, it can be set to any string and is used for identification purposes in the event logs. By default is `0x436c697070657200000000000000000000000000000000000000000000000000` that is the representation of `Clipper`
required: false
schema:
type: string
example: '0x31494e4348000000000000000000000000000000000000000000000000000000'
- name: calldata
in: query
description: Send this as true if we want to get the bytes representation of the swap in the response. Client can use this to be sent directly to the pool contract for execution.
required: false
schema:
type: boolean
default: false
example: true
responses:
'200':
description: Quote and signature generated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/QuoteSignResponse'
examples:
quote-sign-response:
summary: Quote Sign Response
description: Combined quote and signature response for immediate swap execution
value:
chain_id: 1
input_asset_address: '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2'
output_asset_address: '0x6B175474E89094C44Da98b954EedeAC495271d0F'
input_amount: '780000000000000'
output_amount: '3504443835292476928'
good_until: '451117153933605942738249439739673213871765011081718076541610938493960'
destination_address: '0x960376b3F62f41E7e66809a05D1C5afdFD60A0E9'
signature:
v: 28
r: '0xb996d67a0f80da5322e0fba14afd82e63e51cfc9ed09cc3377e84c7dfd05f9a1'
s: '0x378c0baaa171606042171fd8886ac007017854f98aa0a85b5ae0c9ce892f1aae'
clipper_exchange_address: '0x655eDCE464CC797526600a462A8154650EEe4B77'
id: 34ad40e0-b445-438a-94b7-3f82104d701e
input_value_in_usd: 3.54
output_value_in_usd: 3.5
created_at: 1755212736
rate: 4492.876711913433
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'409':
$ref: '#/components/responses/QuoteProblems'
'422':
$ref: '#/components/responses/InvalidInputData'
'500':
$ref: '#/components/responses/InternalServerError'
'503':
$ref: '#/components/responses/ExternalServiceError'
components:
schemas:
QuoteSignResponse:
type: object
properties:
chain_id:
type: integer
description: Represents the ID of the chain
input_asset_address:
type: string
description: Contract address of the asset you want to provide for the swap
output_asset_address:
type: string
description: Contract address of the asset you want to receive in the swap
input_amount:
type: string
description: Amount of assets to be exchanged
output_amount:
type: string
description: Amount of assets you will receive in the exchange
good_until:
type: string
description: Number of seconds that quotes live. It can also contained a packed representation of the state
destination_address:
type: string
description: Address will receive the output token
signature:
$ref: '#/components/schemas/EIP2098Signature'
clipper_exchange_address:
type: string
description: Blade contract address of the pool, is the address used when executing a transaction
calldata:
type: string
description: Bytes representation of the swap function and parameters to be sent directly to the `clipper_exchange_address` for execution. Only present when `calldata=true` in request.
id:
type: string
format: uuid
description: Internal identifier
input_value_in_usd:
type: number
format: float
description: Amount in dollars to be exchanged
output_value_in_usd:
type: number
format: float
description: Amount in dollars you will receive in the exchange
created_at:
type: integer
description: Unix Timestamp indicating the date and time when the quote was created
rate:
type: number
format: float
description: swap rate
required:
- chain_id
- input_asset_address
- output_asset_address
- input_amount
- output_amount
- good_until
- destination_address
- signature
- clipper_exchange_address
- id
- input_value_in_usd
- output_value_in_usd
- created_at
- rate
EIP2098Signature:
type: object
description: A EIP 2098 'short signature' representation for the signature from the Blade Exchange server
properties:
v:
type: integer
description: Recovery identifier
r:
type: string
description: ECDSA signature r
s:
type: string
description: ECDSA signature s
required:
- v
- r
- s
QuoteResponse:
type: object
properties:
id:
type: string
format: uuid
description: Id of the quote, use this value when signing a quote
must_accept_by:
type: string
description: Human-readable UTC timestamp by which you must accept the quote and should be expected to be a short duration. If this time has passed already, request a new quote - the server will not sign a quote after must_accept_by has passed
good_until:
type: integer
description: number of seconds that quotes live
chain_id:
type: integer
description: Represents the ID of the chain
input_asset_address:
type: string
description: Contract address of the asset you want to provide for the swap
input_amount:
type: string
description: Amount of assets to be exchanged
output_asset_address:
type: string
description: Contract address of the asset you want to receive in the swap
output_amount:
type: string
description: Amount of assets you will receive in the exchange
input_value_in_usd:
type: number
format: float
description: Amount in dollars to be exchanged
output_value_in_usd:
type: number
format: float
description: Amount in dollars you will receive in the exchange
created_at:
type: integer
description: Unix Timestamp indicating the date and time when the quote was created
rate:
type: number
format: float
description: swap rate
required:
- id
- must_accept_by
- good_until
- chain_id
- input_asset_address
- input_amount
- output_asset_address
- output_amount
- input_value_in_usd
- output_value_in_usd
- created_at
- rate
example:
id: 05a51aa6-41b5-4c61-a452-f1b95d0d43e4
must_accept_by: '2023-10-13 22:24:20.932560+00:00'
good_until: 1697235920
chain_id: 1
input_amount: '10000000000000000000'
output_amount: '5661947917'
input_value_in_usd: 15595.15
output_value_in_usd: 5668.12
created_at: 1697235848
rate: 566.1947917
input_asset_address: '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2'
output_asset_address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48'
SignResponse:
type: object
properties:
chain_id:
type: integer
description: Represents the ID of the chain
input_asset_address:
type: string
description: Contract address of the asset you want to provide for the swap
output_asset_address:
type: string
description: Contract address of the asset you want to receive in the swap
input_amount:
type: string
description: Amount of assets to be exchanged
output_amount:
type: string
description: Amount of assets you will receive in the exchange
good_until:
type: string
description: Number of seconds that quotes live. It can also contained a packed representation of the state
destination_address:
type: string
description: Address will receive the output token
signature:
$ref: '#/components/schemas/EIP2098Signature'
clipper_exchange_address:
type: string
description: Blade contract address of the pool, is the address used when executing a transaction
calldata:
type: string
description: Bytes representation of the swap function and parameters to be sent directly to the `clipper_exchange_address` for execution. Only present when `calldata=true` in request.
required:
- chain_id
- input_asset_address
- output_asset_address
- input_amount
- output_amount
- good_until
- destination_address
- signature
- clipper_exchange_address
ErrorResponse:
type: object
properties:
errorMessage:
type: string
description: Description of the error
errorType:
type: string
description: Type of the error
errorCode:
type: integer
description: Error code (returned only when we have a blade code for the error)
data:
type: array
items:
type: object
description: Additional error data (returned only when the input data is invalid)
required:
- errorMessage
- errorType
SignRequest:
type: object
properties:
quote_id:
type: string
format: uuid
description: The id of the quote returned in quote endpoint
example: 4c707e45-7019-4b81-b875-c5eb6fe061d6
destination_address:
type: string
description: Address that will receive the output token
example: '0x960376b3F62f41E7e66809a05D1C5afdFD60A0E9'
sender_address:
type: string
description: For DEX aggregator partners that are using their own smart contract to mediate the interaction between users and Blade. Aggregators should use the address of the account that they will pull tokens from (i.e., the EOA user address) as opposed to the address of their deployed contract. By default, `destination_address` will be used.
example: '0x960376b3F62f41E7e66809a05D1C5afdFD60A0E9'
aux_data:
type: string
description: For use with the calldata swap feature, it can be set to any string and is used for identification purposes in the event logs. By default is` 0x436c697070657200000000000000000000000000000000000000000000000000` that is the representation of `Clipper`
example: '0x31494e4348000000000000000000000000000000000000000000000000000000'
default: '0x436c697070657200000000000000000000000000000000000000000000000000'
calldata:
type: boolean
description: Send this as true if we want to get the bytes representation of the swap in the response. Client can use this to be sent directly to the pool contract for execution.
default: false
native_input:
type: boolean
description: If the input token is native (e.g. raw ETH), this value must be true. This will use the `sellEthForToken` contract function and will take the `msg.value` for the input. e.g `ETH -> USDC`. This field is mutually exclusive with `native_output`.
default: false
native_output:
type: boolean
description: If the output token is native (i.e. raw ETH), this value must be true. This will use the `sellTokenForEth` contract function. e.g `USDC -> ETH`. This field is mutually exclusive with `native_input`.
default: false
required:
- quote_id
- destination_address
responses:
QuoteProblems:
description: Quote problems
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
ExternalServiceError:
description: External Service Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
InternalServerError:
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
InvalidInputData:
description: Invalid input data
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
errorMessage: Invalid input data
errorType: BadData
errorCode: 422
data:
- type: missing
loc:
- chain_id
msg: Field required
input:
input_amount: '18000'
input_asset_symbol: ETH
output_asset_symbol: WBTC
time_in_seconds: 60
url: https://errors.pydantic.dev/2.1/v/missing
Unauthorized:
description: Unauthorized - Missing or invalid API key. Ensure you include a valid `x-api-key` header.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
errorMessage: 'Auth: Access is forbidden'
errorType: Forbidden
BadRequest:
description: Bad Request - Invalid data in the request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
Forbidden:
description: Forbidden Error - Access denied
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: x-api-key
description: API key required for all endpoints. In order to prevent abuse on the API we implement rate limits on the requests, to overcome these limits as an aggregator get in contact with the [support team](mailto:aggregators@shipyardsoftware.org) to get API credentials.