Skip to main content
Documentation Powered by Redocly

Safello API (2.0.17)

Download OpenAPI specification:Download

License: Private

Powering your app with crypto

Authentication

OAuth2

Security Scheme Type OAuth2
urn:safello:params:oauth:grant-type:bankid OAuth Flow
Scopes:
  • asset -

    List symbols and prices of assets.

  • account.base -

    View and modify base information of accounts.

  • account.base:read -

    View base information of accounts.

  • account.bank-account -

    View and modify users bank accounts.

  • account.bank-account:read -

    View users bank accounts.

  • order -

    View and create orders.

  • order:read -

    View orders.

  • wallet -

    View and modify wallet.

clientCredentials OAuth Flow
Token URL: /oauth2/token
Scopes:
  • asset -

    List symbols and prices of assets.

authorizationCode OAuth Flow
Authorization URL:
Token URL: /oauth2/token
Scopes:
  • asset -

    List symbols and prices of assets.

  • account.base -

    View and modify base information of accounts.

  • account.base:read -

    View base information of accounts.

  • account.bank-account -

    View and modify users bank accounts.

  • account.bank-account:read -

    View users bank accounts.

  • order -

    View and create orders.

  • order:read -

    View orders.

  • wallet -

    View and modify wallet.

BasicAuth

Security Scheme Type HTTP
HTTP Authorization Scheme basic

Symbols

Crypto currency symbols

List Cryptocurrency symbols

Lists the crypto currency symbols supported by Safello

Authorizations:
OAuth2 (
  • asset
)

Responses

Response Schema: application/json
Array
currency
string

Crypto currency code

minorAmountDecimals
integer

Number of decimal places to represent the smallest unit for this crypto currency

displayName
string

Crypto currency name

status
string

Availability of our services related to this crypto currency. It can be:

  • active: All services are working and available
  • inactive: Some or all services associated with this crypto currency are temporarily unavailable.
  • deprecated: We don't support trading with this cryptocurrency anymore.
availableActions
Array of strings

Lists the type of operations you can make using this cryptocurrency.

Response samples

Content type
application/json
[
  • {
    }
]

List Fiat currency symbols

Lists the fiat currency symbols supported by Safello

Authorizations:
OAuth2 (
  • asset
)

Responses

Response Schema: application/json
Array
currency
string

Currency code ISO 4217

minorAmountDecimals
integer

Number of decimal places to represent the smallest unit for this currency

displayName
string

Currency name

status
string

Availability of our services related to this currency. It can be:

  • active: All services are working and available
  • inactive: Some or all services associated with this currency are temporarily unavailable.
  • deprecated: We don't support trading with this currency anymore.

Response samples

Content type
application/json
[
  • {
    }
]

List trading pairs

Lists the trading pairs supported by Safello

Authorizations:
OAuth2 (
  • asset
)

Responses

Response Schema: application/json
Array
pair
string

Trading pair symbol.

status
string

Availability of our services related to this trading pair. It can be:

  • active: All services are working and available
  • inactive: Some or all services associated with this trading pair are temporarily unavailable.
  • deprecated: We don't support trading with this cryptocurrency anymore.
availableActions
Array of strings

Lists the type of operations you can make using this trading pair.

Response samples

Content type
application/json
[
  • {
    }
]

Prices

Price endpoints

Price history

Gets historical price data for a cryptocurrency in a given interval.

Authorizations:
OAuth2 (
  • asset
)
query Parameters
crypto
string
Default: "BTC"

Cryptocurrency code - one of BTC, ETH, LINK, MATIC, or DOT

interval
string
Default: "MAX"
Enum: "DAILY" "WEEKLY" "MONTHLY" "QUARTERLY" "HALF_YEARLY" "YEARLY" "YTD" "MAX"

Time interval for the result

Responses

Response Schema: application/json
Array
timestamp
integer <int64>

Timestamp representing the number of milliseconds since UNIX Epoch Time

price
string

Unitary price for the cryptocurrency in SEK

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    },
  • "..."
]

Get price

Gets the current price for a single crypto currency

Authorizations:
OAuth2 (
  • asset
)
path Parameters
crypto
required
string

Cryptocurrency code - one of BTC, ETH, LINK, MATIC, or DOT

query Parameters
fiat
string
Default: "SEK"
Value: "SEK"

Fiat currency

Responses

Response Schema: application/json
ask
string

Ask price

baseAsk
string

Base ask price

baseBid
string

Base bid price

bid
string

Bid price

cryptoCurrency
string

Crypto currency code

currency
string

Fiat currency

Response samples

Content type
application/json
{
  • "ask": "343110.6053375",
  • "baseAsk": "328335.5075",
  • "baseBid": "330303.5525",
  • "bid": "313788.374875",
  • "cryptoCurrency": "BTC",
  • "currency": "SEK"
}

Authentication

Authentication flow

BankID Auth Grant

Starts an authorization request

Authorizations:
BasicAuth
    header Parameters
    Source-IP-Address
    required
    string
    Example: 192.168.0.1

    IP Address of the originator of the request

    Source-User-Agent
    required
    string
    Example: curl/7.37.0

    User-Agent of the originator of the request

    Request Body schema: application/x-www-form-urlencoded
    pnr
    required
    string

    Personal Identity Number (12 digits)

    Responses

    Response Headers
    Cache-Control
    string
    Example: "no-store"
    Pragma
    string
    Example: "no-cache"
    Response Schema: application/json
    request_id
    string <uuid>

    Request ID to provide when requesting access token

    auto_start_token
    string
    interval
    integer

    time to wait between polling requests

    expires_in
    integer

    how long the request will last before timing out

    Response samples

    Content type
    application/json
    {
    • "request_id": "123e4567-e89b-12d3-a456-426614174000",
    • "auto_start_token": "sagtuvAgOax1",
    • "interval": 2,
    • "expires_in": 120
    }

    Request Access Token

    Authorizations:
    BasicAuth
      Request Body schema: application/x-www-form-urlencoded
      grant_type
      required
      string

      Grant types:

      • urn:safello:params:oauth:grant-type:bankid
      • client_credentials
      • refresh_token
      request_id
      string

      The request_id retrieved from /oauth2/bankid request

      refresh_token
      any

      The refresh token previously issued to the client.

      scope
      string

      The scope of the access request

      Responses

      Response Headers
      Cache-Control
      string
      Example: "no-store"
      Pragma
      string
      Example: "no-cache"
      Response Schema: application/json
      access_token
      string

      The access token issued by the authorization server.

      token_type
      string

      The type of the token issued.

      expires_in
      integer

      The lifetime in seconds of the access token.

      refresh_token
      string

      The refresh token, which can be used to obtain new access tokens.

      scope
      string

      The scope of the access token.

      Response samples

      Content type
      application/json
      {
      • "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
      • "token_type": "Bearer",
      • "expires_in": 3600,
      • "refresh_token": "tGzv3JOkF0XG5Qx2TlKWIA",
      • "scope": "read write"
      }

      Account

      Account management

      Get logged in user

      Returns information about the logged in user

      Authorizations:
      OAuth2 (
      • account.base
      • account.base:read
      )

      Responses

      Response Schema: application/json
      country
      string

      Two-letter country code. ISO 3166-1 alpha-2

      email
      string <email>

      User's email

      emailActive
      boolean

      Indicates if a user has completed the process of email verification

      firstName
      string

      User's first name

      lastName
      string

      User's last name

      hasAcceptedLatestTerms
      boolean

      Indicates whether or not the user has accepted the latest Terms and Conditions for using Safello.

      language
      string

      Two-letter language code, ISO 639-1

      level
      integer

      Defines what percentage fee the user gets

      safeEnvironment
      boolean

      Indicates if the user was put under safe mode

      telephoneNumber
      string <phoneNumber>

      User's contact number

      tier
      integer

      Relates to the maximum amount of money this user is allowed to buy

      Response samples

      Content type
      application/json
      {
      • "country": "SE",
      • "email": "user@example.com",
      • "emailActive": true,
      • "firstName": "John",
      • "lastName": "Doe",
      • "hasAcceptedLatestTerms": true,
      • "language": "sv",
      • "level": 1,
      • "safeEnvironment": false,
      • "telephoneNumber": 46555555555,
      • "tier": 3
      }

      Accept T&C

      Accept Terms and Conditions

      Authorizations:
      OAuth2 (
      • account.base
      )
      Request Body schema: application/json
      marketingEmails
      boolean
      Default: false

      Opt in to receiving marketing emails from Safello

      Responses

      Request samples

      Content type
      application/json
      {
      • "marketingEmails": true
      }

      Response samples

      Content type
      application/json
      {
      • "message": "string"
      }

      Send verification email

      Send email to verify the user has access to that account

      Authorizations:
      OAuth2 (
      • account.base
      )
      Request Body schema: application/json
      email
      required
      string

      Email to send the verification code to

      Responses

      Request samples

      Content type
      application/json
      {
      • "email": "mail@test.com"
      }

      Response samples

      Content type
      application/json
      {
      • "message": "You cannot place an order higher than your buy limit of 500 SEK",
      • "status": 400,
      • "code": "BUY_LIMIT_EXCEEDED"
      }

      Verify email

      Verify user's email address

      Authorizations:
      OAuth2 (
      • account.base
      )
      Request Body schema: application/json
      code
      required
      string

      Verification code sent to the user's email

      Responses

      Request samples

      Content type
      application/json
      {
      • "code": 123456
      }

      Response samples

      Content type
      application/json
      {
      • "message": "You cannot place an order higher than your buy limit of 500 SEK",
      • "status": 400,
      • "code": "BUY_LIMIT_EXCEEDED"
      }

      Check if KYC is required

      Use this endpoint to check is the user is required to complete the KYC questionnaire to continue trading

      Authorizations:
      OAuth2 (
      • account.base
      • account.base:read
      )

      Responses

      Response Schema: application/json
      requireKyc
      boolean

      Indicates if the user is required to complete the KYC questionnaire

      Response samples

      Content type
      application/json
      {
      • "requireKyc": true
      }

      KYC questions

      Gets a list of questions to ask the user in order to complete the "Know Your Customer" (KYC) questionnaire.

      Authorizations:
      OAuth2 (
      • account.base
      • account.base:read
      )
      query Parameters
      lang
      string
      Example: lang=sv

      Two-letter language code, ISO 639-1

      questionnaire
      string
      Example: questionnaire=BASIC

      Which questionnaire questions to get

      Responses

      Response Schema: application/json
      Array
      id
      integer

      Question ID

      questionnaire
      string

      Which questionnaire the question belongs to

      question
      string

      Stated question to present to the user

      Array of objects[ items ]

      Choice options to present to the user

      questionVersion
      integer

      Question version

      status
      string

      Status for this question

      Response samples

      Content type
      application/json
      [
      • {
        }
      ]

      Answer KYC questionnaire

      Submits the user's answers to the KYC questionnaire

      Authorizations:
      OAuth2 (
      • account.base
      )
      Request Body schema: application/json
      questionnaire
      required
      string

      Which questionnaire to answer

      required
      Array of objects[ items ]

      Array of answers

      Responses

      Request samples

      Content type
      application/json
      {
      • "questionnaire": "BASIC",
      • "answers": [
        ]
      }

      Response samples

      Content type
      application/json
      {
      • "message": "You cannot place an order higher than your buy limit of 500 SEK",
      • "status": 400,
      • "code": "BUY_LIMIT_EXCEEDED"
      }

      Get user bank accounts

      Get a list of all bank account the user has connected

      Authorizations:
      OAuth2 (
      • account.bank-account
      • account.bank-account:read
      )

      Responses

      Response Schema: application/json
      Array
      id
      string <uuid>

      Bank account ID

      name
      string

      Name of the account

      accountNumber
      string

      Bank account number

      clearingNumber
      string

      Clearing number

      currency
      string

      Currency of the bank account

      bank
      string

      Name of bank

      default
      boolean

      If bank account is the default selected

      Response samples

      Content type
      application/json
      [
      • {
        }
      ]

      Add or update bank account

      A unique bank account (clearing number + bank account number) can only be added once to a user. Adding the same bank account a second time will update the existing and return the same Bank Account ID.

      Authorizations:
      OAuth2 (
      • account.bank-account
      )
      Request Body schema: application/json
      accountNumber
      required
      string^(\d{7}|\d{11})$

      Bank account number

      clearingNumber
      required
      string^\d{4,5}$

      Clearing number

      currency
      required
      string

      Currency of the bank account

      name
      string

      Name of the account

      Responses

      Response Schema: application/json
      id
      string <uuid>

      Bank account ID

      name
      string

      Name of the account

      accountNumber
      string

      Bank account number

      clearingNumber
      string

      Clearing number

      currency
      string

      Currency of the bank account

      bank
      string

      Name of bank

      default
      boolean

      If bank account is the default selected

      Request samples

      Content type
      application/json
      {
      • "name": "Savings",
      • "accountNumber": "123456789",
      • "clearingNumber": "1234",
      • "currency": "SEK"
      }

      Response samples

      Content type
      application/json
      {
      • "id": "e6eb08e1-b966-4ee9-b43f-db83dd958479",
      • "name": "Savings",
      • "accountNumber": "123456789",
      • "clearingNumber": "1234",
      • "currency": "SEK",
      • "bank": "SHB",
      • "default": true
      }

      Orders

      Buy and sell crypto

      List orders

      Gets a paginated list containing the user's orders history

      Authorizations:
      OAuth2 (
      • order
      • order:read
      )
      query Parameters
      offset
      integer

      Desired offset for pagination purposes

      Responses

      Response Schema: application/json
      offset
      integer

      Offset value for pagination purposes

      size
      integer

      Number of results returned

      total
      integer

      Total number of orders for this user

      Array of objects (OrderRecord) [ items ]

      Response samples

      Content type
      application/json
      {
      • "offset": 0,
      • "size": 0,
      • "total": 0,
      • "data": [
        ]
      }

      Create buy order

      Creates a new order to buy crypto currency using fiat money.

      Upon creation, you can monitor the status of the order by calling Check order status.

      Authorizations:
      OAuth2 (
      • order
      )
      header Parameters
      Source-IP-Address
      required
      string
      Example: 192.168.0.1

      IP Address of the originator of the request

      Source-User-Agent
      required
      string
      Example: curl/7.37.0

      User-Agent of the originator of the request

      Request Body schema: application/json
      cryptoCurrency
      required
      string

      Cryptocurrency code - one of BTC, ETH, LINK, MATIC, or DOT

      required
      object (CurrencyAmount)
      paymentMethod
      required
      string

      Payment method used - one of swish, klarna_bankgiro, klarna_sepa, credit_card, sepa, bank_transfer_dk, bank_transfer_se

      phoneNumber
      string <country code + cellphone number (without leading zero).> ^\d{8,15}$

      Phone number used to make the payment. Optional when using the swish payment method.

      Responses

      Response Schema: application/json
      orderId
      required
      string

      Identifier for the newly created order. Use it to check its status

      pollingUrl
      required
      string <URL>

      URL to call to check the order status

      swishPaymentRequestToken
      string

      Swish payment request token. Needed to open the Swish app. Only supplied if payment method was swish.

      Request samples

      Content type
      application/json
      {
      • "cryptoCurrency": "BTC",
      • "fiat": {
        },
      • "paymentMethod": "string",
      • "phoneNumber": "46712345678"
      }

      Response samples

      Content type
      application/json
      {}

      Create trade order

      Creates a new trade order to exchange crypto.

      Upon creation, you can monitor the status of the order by calling Check order status.

      Authorizations:
      OAuth2 (
      • order
      )
      header Parameters
      Source-IP-Address
      required
      string
      Example: 192.168.0.1

      IP Address of the originator of the request

      Source-User-Agent
      required
      string
      Example: curl/7.37.0

      User-Agent of the originator of the request

      Request Body schema: application/json
      pair
      required
      string

      A trading pair symbol

      amount
      required
      string

      Amount

      side
      required
      string
      Enum: "buy" "sell"

      Order side

      type
      required
      string
      Enum: "market" "limit"

      Order type

      clientId
      required
      string

      Unique ID for this trade.

      price
      string

      Limit price for limit orders

      Responses

      Response Schema: application/json
      orderId
      required
      string

      Identifier for the newly created order. Use it to check its status

      pollingUrl
      required
      string <URL>

      URL to call to check the order status

      Request samples

      Content type
      application/json
      {
      • "pair": "BTC/USDC",
      • "amount": {
        },
      • "side": "buy",
      • "type": "market",
      • "price": "string",
      • "clientId": "string"
      }

      Response samples

      Content type
      application/json
      {}

      Cancel a trade order

      Cancels a limit trade order.

      Authorizations:
      OAuth2 (
      • order
      )
      header Parameters
      Source-IP-Address
      required
      string
      Example: 192.168.0.1

      IP Address of the originator of the request

      Source-User-Agent
      required
      string
      Example: curl/7.37.0

      User-Agent of the originator of the request

      Request Body schema: application/json
      orderId
      required
      string

      Order identifier.

      Responses

      Request samples

      Content type
      application/json
      {
      • "orderId": "string"
      }

      Response samples

      Content type
      application/json
      {
      • "message": "You cannot place an order higher than your buy limit of 500 SEK",
      • "status": 400,
      • "code": "BUY_LIMIT_EXCEEDED"
      }

      Create sell order

      Creates an order to sell crypto currency and receive fiat money.

      Upon creation, you can monitor the status of the order by calling Check order status.

      Authorizations:
      OAuth2 (
      • order
      )
      header Parameters
      Source-IP-Address
      required
      string
      Example: 192.168.0.1

      IP Address of the originator of the request

      Source-User-Agent
      required
      string
      Example: curl/7.37.0

      User-Agent of the originator of the request

      Request Body schema: application/json
      fiatCurrency
      required
      string

      Currency to convert the crypto to - must be a well formed currency code, currently SEK only

      required
      object (CurrencyAmount)
      bankAccountId
      string <uuid>

      Bank account to use when creating a sell order. If not used the user default bank account will be used instead

      Responses

      Response Schema: application/json
      orderId
      required
      string

      Identifier for the newly created order. Use it to check its status

      pollingUrl
      required
      string <URL>

      URL to call to check the order status

      Request samples

      Content type
      application/json
      {
      • "fiatCurrency": "SEK",
      • "crypto": {
        },
      • "bankAccountId": "5b26b598-a880-4e32-8c41-126aa0206857"
      }

      Response samples

      Content type
      application/json
      {}

      Check order status

      Checks the status of an order. Used to monitor if a buy or sell order has been completed.

      Authorizations:
      OAuth2 (
      • order
      • order:read
      )
      path Parameters
      orderId
      required
      string

      Order identifier

      Responses

      Response Schema: application/json
      id
      string

      Identifier for the order

      created
      string <date-time>

      Order creation date in ISO 8601 format.

      object (CurrencyAmount)
      object (CurrencyAmount)
      feeRate
      string

      Fee rate in percentage for the transaction

      object (CurrencyAmount)
      object (CurrencyAmount)
      object (CurrencyAmount)
      object (CurrencyAmount)
      status
      string

      Order status. It can be one of the following:

      • completed
      • done
      • paid
      • traded
      • mempool
      • exchange
      • waiting
      • processing
      • pending
      • error
      • stopped
      • refunded
      • declined
      • halted
      • rejected
      type
      any
      Enum: "buy" "sell"

      Order type

      paymentMethod
      string

      Payment method used

      Response samples

      Content type
      application/json
      {
      • "id": "AS0ZZHU",
      • "created": "2022-01-27T11:29:20+0100",
      • "fiat": {
        },
      • "crypto": {
        },
      • "feeRate": "0.05",
      • "fee": {
        },
      • "receivedCrypto": {
        },
      • "sold": {
        },
      • "payout": {
        },
      • "status": "completed",
      • "type": "sell",
      • "paymentMethod": "swish"
      }

      Wallet

      User's wallet

      Wallet

      Retrieves the user's wallet

      Authorizations:
      OAuth2 (
      • wallet
      )

      Responses

      Response Schema: application/json
      Array of objects (CurrencyAmount) [ items ]

      Current crypto holdings

      created
      string <date-time>

      Creation time in ISO 8601 format.

      Response samples

      Content type
      application/json
      {
      • "balances": [
        ],
      • "created": "2022-02-03T09:44:13.000Z"
      }

      Wallet performance

      Retrieves the user's current wallet performance right now

      Authorizations:
      OAuth2 (
      • wallet
      )

      Responses

      Response Schema: application/json
      fiat
      string

      Fiat currency

      object

      Individual performance for each crypto

      object (WalletPerformanceCrypto)

      Response samples

      Content type
      application/json
      {
      • "fiat": "string",
      • "cryptos": {
        },
      • "total": {
        }
      }

      Wallet performance history

      Retrieves the user's wallet performance history. Each data point is one day at midnight UTC.

      For example a data point at 2022-01-01 would mean what the performance was at 2022-01-01 00:00 UTC

      Authorizations:
      OAuth2 (
      • wallet
      )
      query Parameters
      crypto
      required
      Array of strings
      Example: crypto=BTC,ETH

      Cryptocurrency code

      timePeriod
      required
      string
      Default: "ALL_TIME"
      Enum: "ALL_TIME" "THIS_YEAR" "THREE_YEARS" "ONE_YEAR" "THREE_MONTHS" "ONE_MONTH" "ONE_WEEK" "CUSTOM"

      Time period to get performance history.

      fiat
      string
      Default: "SEK"

      Fiat currency

      start
      string <date>

      Start date if timePeriod is CUSTOM

      end
      string <date>

      End date if timePeriod is CUSTOM

      performanceSince
      string <date>

      Date where to calculate the performance from. Default to wallet creation date when timePeriod is CUSTOM or the first date on all other time periods

      Responses

      Response Schema: application/json
      start
      string <date>
      end
      string <date>
      performanceSince
      string <date>
      fiat
      string

      Fiat currency

      timePeriod
      string
      Array of objects (WalletPerformanceHistoryDataPoint) [ items ]

      Data points

      Response samples

      Content type
      application/json
      {
      • "start": "2019-08-24",
      • "end": "2019-08-24",
      • "performanceSince": "2019-08-24",
      • "fiat": "string",
      • "timePeriod": "string",
      • "data": [
        ]
      }

      Compliance

      User's compliance information/status

      Verify compliance status for a sell operation

      Verify the compliance status for a sell operation

      Authorizations:
      OAuth2 (
      • order
      )
      Request Body schema: application/json
      fiatCurrency
      required
      string

      Currency to convert the crypto to - must be a well formed currency code, currently SEK only

      required
      object (CurrencyAmount)
      bankAccountId
      string <uuid>

      Bank account to use when creating a sell order. If not used the user default bank account will be used instead

      Responses

      Response Schema: application/json
      Array
      decision
      string

      Describes the outcome of the compliance assessment (ACCEPT or REJECT)

      Array of objects (ComplianceRejection) [ items ]

      A list of reasons for the rejection (if any)

      Request samples

      Content type
      application/json
      {
      • "fiatCurrency": "SEK",
      • "crypto": {
        },
      • "bankAccountId": "5b26b598-a880-4e32-8c41-126aa0206857"
      }

      Response samples

      Content type
      application/json
      [
      • {
        }
      ]

      Verify compliance status for a buy operation

      Verify the compliance status for a buy operation

      Authorizations:
      OAuth2 (
      • order
      )
      Request Body schema: application/json
      cryptoCurrency
      required
      string

      Cryptocurrency code - one of BTC, ETH, LINK, MATIC, or DOT

      required
      object (CurrencyAmount)
      paymentMethod
      required
      string

      Payment method used - one of swish, klarna_bankgiro, klarna_sepa, credit_card, sepa, bank_transfer_dk, bank_transfer_se

      phoneNumber
      string <country code + cellphone number (without leading zero).> ^\d{8,15}$

      Phone number used to make the payment. Optional when using the swish payment method.

      Responses

      Response Schema: application/json
      Array
      decision
      string

      Describes the outcome of the compliance assessment (ACCEPT or REJECT)

      Array of objects (ComplianceRejection) [ items ]

      A list of reasons for the rejection (if any)

      Request samples

      Content type
      application/json
      {
      • "cryptoCurrency": "BTC",
      • "fiat": {
        },
      • "paymentMethod": "string",
      • "phoneNumber": "46712345678"
      }

      Response samples

      Content type
      application/json
      [
      • {
        }
      ]