Skip to main content
API docs by Redocly

Monerium API (2.0.0)

Download OpenAPI specification:Download

URL: https://monerium.com License: Apache 2.0 Terms of Service

API for developers to integrate Monerium payments, wallets, and user onboarding functionalities into their applications.

Getting started

New to the Monerium API? See the Getting Started guide for setup instructions, environment details, and integration walkthroughs.

Endpoints marked Whitelabel or Private are only available to those application types.

Welcome

Returns a welcome message with a link to documentation and socials.

Responses

Response Schema: application/json
hello
string
docs
string
twitter
string

Response samples

Content type
application/json
{}

Authentication

Endpoints for authorization and token management. See the OAuth, Whitelabel, and Private guides for integration walkthroughs.

Authorization

OAuth

Initiates user authorization. Redirects users through the Authorization Code Flow (HTTP 307), or completes authorization immediately for existing customers using Sign in with Ethereum (SIWE). The resulting authorization code is exchanged for an access token via POST /auth/token.

Request Body schema: application/x-www-form-urlencoded
required
One of
client_id
required
string <UUID> (AuthClientID) ^[0-9a-f]{8}-[0-9a-f]{4}-[4][0-9a-f]{3}-[89ab...

The Authorization Code Flow client ID of your application.

code_challenge
required
string

PKCE challenge derived from the code_verifier. Use the same code_verifier when requesting an access token.

code_challenge_method
string
Value: "S256"

Method used to generate the challenge. Monerium only supports S256.

redirect_uri
string

The URL to redirect to after authorization. Required if more than one redirect URL is registered; must match a registered URL exactly.

state
string

Opaque value returned with the redirect. Recommended for CSRF protection.

email
boolean

You can prefill the email field for login and sign up steps to ensure the user uses the correct email.

skip_kyc
boolean

You can skip the KYC onboarding steps in the Authorization Flow during testing.

auth_mode
string
Enum: "login" "signup"

Controls which auth screen to show first when the user is not authenticated. Defaults to the start screen.

Responses

Response Headers
Location
string

Redirect URI with either:

  • authorization code as: http://localhost:3000/monerium?code=LFG4269
  • error as: http://localhost:3000/monerium?error=invalid_request&error_description=No+such+client+ID
Response Headers
Location
string
Example: "https://sandbox.monerium.dev/partners/a15806ac-e6d6-11ed-891c-2ea11c960b3f/auth?client_id=a08bfa22-e6d6-11ed-891c-2ea11c960b3f&code_challenge=9Y__uhKapn7GO_ElcaQpd8C3hdOyqTzAU4VXyR2iEV0&redirect_uri=http%3A%2F%2Flocalhost%3A3000&response_type=code"

Uri to authorization flow. Customer has to go through the Monerium onboarding screen and will eventually give the application permission to read their data.

Request samples 

curl -i 'https://api.monerium.dev/auth' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'code_challenge=9Y__uhKapn7GO_ElcaQpd8C3hdOyqTzAU4VXyR2iEV0' \
--data-urlencode 'client_id=a08bfa22-e6d6-11ed-891c-2ea11c960b3f' \
--data-urlencode 'redirect_uri=http://localhost:3000' \
--data-urlencode 'code_challenge_method=S256'

Authorization

OAuth

Same as POST /auth using a GET request with the same properties as query parameters.

Request samples 

curl https://api.monerium.dev/auth?code_challenge=9Y__uhKapn7GO_ElcaQpd8C3hdOyqTzAU4VXyR2iEV0&client_id=a08bfa22-e6d6-11ed-891c-2ea11c960b3f&redirect_uri=http://localhost:3000&code_challenge_method=S256

Context

Returns details about the currently authenticated user, including their roles and accessible profiles.

Authorizations:
BearerAuth

Responses

Response Schema: application/json
userId
string <UUID> (UUID) ^[0-9a-f]{8}-[0-9a-f]{4}-[4][0-9a-f]{3}-[89ab...

Unique identifier of the User.

email
string <email>

An email address associated with the account.

name
string

The user name or alias. You can treat this as metadata.

roles
Array of strings
Default: []
Items Value: "admin"

List of Role

object

Information about how the user was authenticated.

defaultProfile
string <UUID> (UUID) ^[0-9a-f]{8}-[0-9a-f]{4}-[4][0-9a-f]{3}-[89ab...

Unique identifier of the default profile. The default profile allows the API consumer to use the simpler API endpoints omitting the profile ID from the structure.

Array of objects (ProfileSummary)

List containing information about every profiles accessible to the User.

Request samples 

curl https://api.monerium.dev/auth/context \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response samples

Content type
application/json
{
  • "userId": "a78d8ff2-e51f-11ed-9e13-cacb9390199c",
  • "email": "user@example.com",
  • "name": "user@example.com",
  • "roles": [ ],
  • "auth": {
    },
  • "defaultProfile": "a78d8ff2-e51f-11ed-9e13-cacb9390199c",
  • "profiles": [
    ]
}

Access token

Obtain an OAuth 2.0 access token. Supports three grant types:

  • authorization_code: Exchange the code received after the OAuth authorization flow for an access token.
  • refresh_token: Use a refresh token to obtain a new access token without user interaction. See Refresh the access token.
  • client_credentials: Authenticate directly with your client ID and secret. Used by Whitelabel and Private applications.
Request Body schema: application/x-www-form-urlencoded
One of
client_id
required
string <UUID> (AuthClientID) ^[0-9a-f]{8}-[0-9a-f]{4}-[4][0-9a-f]{3}-[89ab...

The Authorization Code Flow client ID of your application.

grant_type
required
string
Value: "authorization_code"
code
required
string

The authorization code that was acquired from authorization flow.

code_verifier
required
string

The random string used to generate the code_challenge in the PKCE authorization flow.

redirect_uri
required
string

The same redirect_uri that was used to acquire the authorization_code.

Responses

Response Schema: application/json
access_token
string

Bearer token used to authenticate API requests.

expires_in
integer

The duration in seconds for which the access token is valid.

refresh_token
string

A token used to obtain a new access token after the current one expires.

token_type
string

The type of token returned. In this case, it is always 'Bearer'.

Request samples 

curl --location --request POST 'https://api.monerium.dev/auth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'client_id=a08bfa22-e6d6-11ed-891c-2ea11c960b3f' \
--data-urlencode 'code=BvTYQprmQzKt8YSn3xsTWQ' \
--data-urlencode 'code_verifier=KO2yF8CUSxU8KJepixDmXdiCOFTMMZFLDmVjNd4J2VhbFUSSgU1lXl0aYyWYK8hIZIEH9bEBDeJ78CIuNoeOIcZOybzzqFlIGedtclJ7ZTKF6GmRBZ4fdMvg6OXnf2dl' \
--data-urlencode 'redirect_uri=http://localhost:3000'

Response samples

Content type
application/json
{
  • "access_token": "EoWmpc2uSZar6h2bKgh",
  • "expires_in": 3600,
  • "refresh_token": "cowYzCowQxGPUl4p15iwKA",
  • "token_type": "Bearer"
}

Profiles

A profile represents a customer undergoing KYC/KYB onboarding (personal or corporate) and is the owner of associated IBANs and addresses. See the Onboarding guide for the full flow.

List countries

Returns a list of countries with their risk tiers for KYC and KYB onboarding.

Responses

Response Schema: application/json
Array of objects
total
integer

Response samples

Content type
application/json
{
  • "countries": [
    ],
  • "total": 1
}

Create profile

Whitelabel

Create a new profile. The kind determines whether the personal or corporate body structure is used in the subsequent form, verifications, and share endpoints. The kind cannot be changed after creation.

Authorizations:
BearerAuth
header Parameters
Accept
required
string
Example: application/vnd.monerium.api-v2+json

Accept header to specify API version 2

Request Body schema: application/json
required
id
string <UUID> (UUID) ^[0-9a-f]{8}-[0-9a-f]{4}-[4][0-9a-f]{3}-[89ab...

Optional partner-supplied profile ID.

kind
required
string (ProfileKind)
Enum: "corporate" "personal"

Determines whether the profile is personal or corporate, and which body structure to use in subsequent PATCH endpoints.

Responses

Response Schema: application/json
One of
id
string

Unique identifier of the profile. The Profile ID is the main identifier used to represent ownership of other API resources

kind
string
Value: "personal"
name
string

The Profile name. This can be a corporate or an individual.

state
string (ProfileState)
Enum: "created" "incomplete" "pending" "approved" "rejected"

The state of the profile lifecycle:

  • created: The profile has been created but no data has been submitted yet.
  • incomplete: One or more sections still require information. The partner can submit or update data.
  • pending: All required information has been provided and the profile is awaiting review. Further submissions are blocked until the state transitions to approved, rejected, or back to incomplete.
  • approved: The profile is active and all Monerium services are available.
  • rejected: Final rejection — the applicant details did not meet compliance requirements.
object (ProfileSection)

KYC details section with its current state.

object (ProfileSection)

Additional data section used for risk calculations.

Array of objects (PersonalVerifications)

Verifications for an individual

Request samples

Content type
application/json
{
  • "id": "a78d8ff2-e51f-11ed-9e13-cacb9390199c",
  • "kind": "personal"
}

Response samples

Content type
application/json
{
  • "id": "4f079ef8-6d26-11eb-9bc8-acde48001122",
  • "kind": "personal",
  • "name": "Jane Doe",
  • "state": "incomplete",
  • "details": {
    },
  • "form": {
    },
  • "verifications": [
    ]
}

Profiles

Retrieves a list of all profiles that your application has access to.

Authorizations:
BearerAuth
query Parameters
state
string (ProfileState)
Enum: "created" "incomplete" "pending" "approved" "rejected"
Example: state=incomplete

Filter the list on the state of profiles

kind
string (ProfileKind)
Enum: "corporate" "personal"
Example: kind=personal

Filter the list on the kind of profiles

header Parameters
Accept
required
string
Example: application/vnd.monerium.api-v2+json

Accept header to specify API version 2

Responses

Response Schema: application/json
Array of objects (Profiles)
Array
id
string <UUID> (UUID) ^[0-9a-f]{8}-[0-9a-f]{4}-[4][0-9a-f]{3}-[89ab...

Unique identifier of the profile. The Profile ID is the main identifier used to represent ownership of other API resources.

kind
string
Enum: "corporate" "personal"

String identifier specifying the type of the profile.

name
string

The Profile name. This can be a corporate or an individual.

state
string (ProfileState)
Enum: "created" "incomplete" "pending" "approved" "rejected"

The state of the profile lifecycle:

  • created: The profile has been created but no data has been submitted yet.
  • incomplete: One or more sections still require information. The partner can submit or update data.
  • pending: All required information has been provided and the profile is awaiting review. Further submissions are blocked until the state transitions to approved, rejected, or back to incomplete.
  • approved: The profile is active and all Monerium services are available.
  • rejected: Final rejection — the applicant details did not meet compliance requirements.

Request samples 

curl https://api.monerium.dev/profiles?state=approved&kind=personal \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Accept: application/vnd.monerium.api-v2+json"

Response samples

Content type
application/json
{
  • "profiles": [
    ]
}

Profile

Retrieves details about a single profile, including the state of each section (details, form, verifications).

Authorizations:
BearerAuth
path Parameters
profile
required
string <UUID> (UUID) ^[0-9a-f]{8}-[0-9a-f]{4}-[4][0-9a-f]{3}-[89ab...
Example: a78d8ff2-e51f-11ed-9e13-cacb9390199c

The ID of the profile

header Parameters
Accept
required
string
Example: application/vnd.monerium.api-v2+json

Accept header to specify API version 2

Responses

Response Schema: application/json
One of
id
string

Unique identifier of the profile. The Profile ID is the main identifier used to represent ownership of other API resources

kind
string
Value: "personal"
name
string

The Profile name. This can be a corporate or an individual.

state
string (ProfileState)
Enum: "created" "incomplete" "pending" "approved" "rejected"

The state of the profile lifecycle:

  • created: The profile has been created but no data has been submitted yet.
  • incomplete: One or more sections still require information. The partner can submit or update data.
  • pending: All required information has been provided and the profile is awaiting review. Further submissions are blocked until the state transitions to approved, rejected, or back to incomplete.
  • approved: The profile is active and all Monerium services are available.
  • rejected: Final rejection — the applicant details did not meet compliance requirements.
object (ProfileSection)

KYC details section with its current state.

object (ProfileSection)

Additional data section used for risk calculations.

Array of objects (PersonalVerifications)

Verifications for an individual

Request samples 

curl https://api.monerium.dev/profiles/4f079ef8-6d26-11eb-9bc8-acde48001122 \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Accept: application/vnd.monerium.api-v2+json"

Response samples

Content type
application/json
{
  • "kind": "personal",
  • "state": "incomplete",
  • "details": {
    },
  • "form": {
    },
  • "verifications": [
    ]
}

Share KYC data

Whitelabel

Reuse KYC data from a third-party provider (e.g. Sumsub) to populate the profile's details and verifications.

Monerium uses the supplied token to fetch data from the provider and updates the relevant sections. Each section that receives sufficient data transitions to pending; any that remain incomplete stay incomplete.

Authorizations:
BearerAuth
path Parameters
profile
required
string <UUID> (UUID) ^[0-9a-f]{8}-[0-9a-f]{4}-[4][0-9a-f]{3}-[89ab...
Example: a78d8ff2-e51f-11ed-9e13-cacb9390199c

The ID of the profile

header Parameters
Accept
required
string
Example: application/vnd.monerium.api-v2+json

Accept header to specify API version 2

Request Body schema: application/json
required
provider
required
string
Value: "sumsub"

The KYC data provider.

required
object

Token for a personal profile applicant.

Responses

Request samples

Content type
application/json
{
  • "provider": "sumsub",
  • "personal": {
    }
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "status": "string",
  • "message": "string",
  • "errors": {
    }
}

Update profile details

Whitelabel

Submit the compliance details for a profile. Updates only the details section without affecting other sections.

KYC reliance model only. Most integrations should use POST /profiles/{profile}/share to populate details via Sumsub instead.

Authorizations:
BearerAuth
path Parameters
profile
required
string <UUID> (UUID) ^[0-9a-f]{8}-[0-9a-f]{4}-[4][0-9a-f]{3}-[89ab...
Example: a78d8ff2-e51f-11ed-9e13-cacb9390199c

The ID of the profile

header Parameters
Accept
required
string
Example: application/vnd.monerium.api-v2+json

Accept header to specify API version 2

Request Body schema: application/json
One of
object

Details for an individual

firstName
required
string

First name

lastName
required
string

Last name

address
required
string

Street and building number where the person lives.

postalCode
required
string

Postal code where the person lives.

city
required
string

City where the person lives.

country
required
string (CountryCode) = 2 characters

Two-letter country code ISO 3166-1 alpha-2 where the person lives

countryState
string

State/County where the person lives.

nationality
required
string (CountryCode) = 2 characters

Two-letter country code ISO 3166-1 alpha-2 for the person's nationality.

birthday
required
string <date> ^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|1\d|2\d|3[01])...

The person's date of birth in YYYY-MM-DD format.

object (IdDocument)

Details of the ID document used to verify the person's identity.

Responses

Response Schema: application/json
object

Request samples

Content type
application/json
Example
{
  • "personal": {
    }
}

Response samples

Content type
application/json
{ }

Update profile form

Whitelabel

Submit additional data for a profile used for risk calculations (e.g. purpose of account, source of funds). Updates only the form section without affecting other sections.

Authorizations:
BearerAuth
path Parameters
profile
required
string <UUID> (UUID) ^[0-9a-f]{8}-[0-9a-f]{4}-[4][0-9a-f]{3}-[89ab...
Example: a78d8ff2-e51f-11ed-9e13-cacb9390199c

The ID of the profile

header Parameters
Accept
required
string
Example: application/vnd.monerium.api-v2+json

Accept header to specify API version 2

Request Body schema: application/json
One of
object (PersonalForm)

Form for an individual

occupation
required
string
Enum: "OCCUPATION_STUDENT" "OCCUPATION_EMPLOYED" "OCCUPATION_SELF_EMPLOYED" "OCCUPATION_UNEMPLOYED" "OCCUPATION_RETIRED"

The occupation code representing the individual's current employment status.

profession
required
string
Enum: "PROF_ACCOUNTANCY" "PROF_ADMINISTRATIVE" "PROF_AGRICULTURE" "PROF_ARTS_MEDIA" "PROF_BROKER_DEALER" "PROF_CATERING_HOSPITALITY" "PROF_CHARITY" "PROF_CONSTRUCTION_REAL_ESTATE" "PROF_DEALER_HIGH_VALUE_GOODS" "PROF_DEALER_PRECIOUS_METALS" "PROF_EDUCATION" "PROF_EMERGENCY_SERVICES" "PROF_EXTRACTIVE_INDUSTRY" "PROF_FIN_SERVICES_BANKING" "PROF_FIN_SERVICES_INSURANCE" "PROF_FIN_SERVICES_OTHER" "PROF_FIN_SERVICES_PRIVATE_BANKING" "PROF_GAMBLING" "PROF_GOVERNMENT" "PROF_HEALTHCARE_MEDICAL" "PROF_INFORMATION_TECHNOLOGY" "PROF_LEGAL" "PROF_MANUFACTURING" "PROF_MARKETING" "PROF_MILITARY_DEFENCE" "PROF_MONEY_SERVICE_BUSINESS" "PROF_PENSIONER" "PROF_PUBLIC_PROCUREMENT" "PROF_RETAIL_SALES"

The profession code representing the individual's professional field.

fundOrigin
required
string
Enum: "FUND_ORIGIN_SALARY" "FUND_ORIGIN_DIVIDENDS" "FUND_ORIGIN_INHERITANCE" "FUND_ORIGIN_SAVINGS" "FUND_ORIGIN_INVESTMENT" "FUND_ORIGIN_GIFT" "FUND_ORIGIN_MINING" "FUND_ORIGIN_REAL_ESTATE" "FUND_ORIGIN_LOAN"

The code representing the origins of the individual's funds.

annualIncome
required
string
Enum: "ANNUAL_INCOME_UNDER_10K" "ANNUAL_INCOME_10K_TO_50K" "ANNUAL_INCOME_50K_TO_150K" "ANNUAL_INCOME_150K_TO_300K" "ANNUAL_INCOME_OVER_300K"

The code representing the individual's annual income range.

monthlyTurnover
required
string
Enum: "TURNOVER_UNDER_10K" "TURNOVER_10K_TO_50K" "TURNOVER_50K_TO_150K" "TURNOVER_150K_TO_500K" "TURNOVER_OVER_500K"

The code representing the individual's monthly turnover range.

monthlyTransactionCount
required
string
Enum: "TRANSACTION_COUNT_LESS_THAN_5" "TRANSACTION_COUNT_5_TO_50" "TRANSACTION_COUNT_50_TO_100" "TRANSACTION_COUNT_100_TO_200" "TRANSACTION_COUNT_OVER_200"

The code representing the number of transactions the individual makes each month.

activities
required
Array of strings
Items Enum: "ACTIVITY_COMMERCE_SELLING" "ACTIVITY_COMMERCE_BUYING" "ACTIVITY_INVESTING_CRYPTO" "ACTIVITY_OTHER"

List of codes representing the individual's financial activities.

activityOther
string

A description of the other activity if the code ACTIVITY_OTHER is chosen.

publicFunction
required
boolean

Indicates whether the individual holds a politically exposed person (PEP) status.

fundOwner
required
boolean

Indicates whether the individual is the owner of the funds.

usCitizen
required
boolean

Indicates whether the individual is a United States citizen.

usTaxPerson
required
boolean

Indicates whether the individual is subject to US tax obligations (e.g. holds a US tax identification number or is a US resident for tax purposes).

tin
required
string

Tax Identification Number (TIN) assigned by the individual's tax authority. Format varies by country (e.g. SSN in the US, NI number in the UK).

taxResidenceCountry
required
string (CountryCode) = 2 characters

Two-letter country code ISO 3166-1 alpha-2 for the tax residency.

Responses

Response Schema: application/json
object

Request samples

Content type
application/json
Example
{
  • "personal": {
    }
}

Response samples

Content type
application/json
{ }

Update profile verifications

Whitelabel

Submit verifications for a profile. Only the verifications provided are updated. sourceOfFunds is submitted here by all partners when required; other verification kinds are populated automatically when using the Sumsub share flow.

Authorizations:
BearerAuth
path Parameters
profile
required
string <UUID> (UUID) ^[0-9a-f]{8}-[0-9a-f]{4}-[4][0-9a-f]{3}-[89ab...
Example: a78d8ff2-e51f-11ed-9e13-cacb9390199c

The ID of the profile

header Parameters
Accept
required
string
Example: application/vnd.monerium.api-v2+json

Accept header to specify API version 2

Request Body schema: application/json
One of
Array of objects (UpdatePersonalVerifications)

Verifications for an individual

Array
kind
required
string
Enum: "idDocument" "facialSimilarityMotion" "proofOfResidency" "sourceOfFunds"

The type of the verification.

Array of objects (VerificationDocument)

Documents to attach to this verification.

Responses

Response Schema: application/json
object

Request samples

Content type
application/json
Example
{
  • "personal": [
    ]
}

Response samples

Content type
application/json
{ }

Addresses

Link a blockchain address to a profile with a cryptographic proof of ownership. See the Link a wallet guide for signing walkthroughs including EOA and smart contract wallets.

Addresses

List of addresses that have been connected. You can filter the addresses by the chain they are connected to.

Authorizations:
BearerAuth
query Parameters
profile
string <UUID> (UUID) ^[0-9a-f]{8}-[0-9a-f]{4}-[4][0-9a-f]{3}-[89ab...
Example: profile=a78d8ff2-e51f-11ed-9e13-cacb9390199c

Return addresses for a given profile ID. By default the caller profile ID is used.

Ethereum (string) or Gnosis (string) or Polygon (string) or Arbitrum (string) or Linea (string) or Base (string) or Noble (string) or Sepolia (string) or Chiado (string) or Amoy (string) or Arbitrum Sepolia (string) or Linea Sepolia (string) or Base Sepolia (string) or Noble Grand (string) (Chain)
Example: chain=ethereum

Filter the list on the chain

header Parameters
Accept
required
string
Example: application/vnd.monerium.api-v2+json

Accept header to specify API version 2

Responses

Response Schema: application/json
Array of objects (AddressObject)
Array
profile
string <UUID> (UUID) ^[0-9a-f]{8}-[0-9a-f]{4}-[4][0-9a-f]{3}-[89ab...

The profile id that owns the address

address
string (Address) ^0x[0-9a-fA-F]{40}$

The public key of the blockchain account.

Array of Ethereum (string) or Gnosis (string) or Polygon (string) or Arbitrum (string) or Linea (string) or Base (string) or Noble (string) or Sepolia (string) or Chiado (string) or Amoy (string) or Arbitrum Sepolia (string) or Linea Sepolia (string) or Base Sepolia (string) or Noble Grand (string) (Chain)

list of chains that this address has been connected to

Request samples 

curl https://api.monerium.dev/addresses?profile=a78d8ff2-e51f-11ed-9e13-cacb9390199c&chain=ethereum \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Accept: application/vnd.monerium.api-v2+json"

Response samples

Content type
application/json
{
  • "addresses": [
    ]
}

Address

Get details for a single address by using the address public key after the address has been successfully linked to Monerium.

Authorizations:
BearerAuth
path Parameters
address
required
string (Address) ^0x[0-9a-fA-F]{40}$
Example: 0x59cFC408d310697f9D3598e1BE75B0157a072407

The public key of the blockchain account.

header Parameters
Accept
required
string
Example: application/vnd.monerium.api-v2+json

Accept header to specify API version 2

Responses

Response Schema: application/json
profile
string <UUID> (UUID) ^[0-9a-f]{8}-[0-9a-f]{4}-[4][0-9a-f]{3}-[89ab...

The profile id that owns the address

address
string (Address) ^0x[0-9a-fA-F]{40}$

The public key of the blockchain account.

Array of Ethereum (string) or Gnosis (string) or Polygon (string) or Arbitrum (string) or Linea (string) or Base (string) or Noble (string) or Sepolia (string) or Chiado (string) or Amoy (string) or Arbitrum Sepolia (string) or Linea Sepolia (string) or Base Sepolia (string) or Noble Grand (string) (Chain)

list of chains that this address has been connected to

Request samples 

curl https://api.monerium.dev/addresses/0x59cFC408d310697f9D3598e1BE75B0157a072407 \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Accept: application/vnd.monerium.api-v2+json"

Response samples

Content type
application/json
{
  • "profile": "a78d8ff2-e51f-11ed-9e13-cacb9390199c",
  • "address": "0x59cFC408d310697f9D3598e1BE75B0157a072407",
  • "chains": [
    ]
}

Balances

Retrieves the balance for an address on a given chain.

Authorizations:
BearerAuth
path Parameters
address
required
string (Address) ^0x[0-9a-fA-F]{40}$
Example: 0x59cFC408d310697f9D3598e1BE75B0157a072407

Address

required
Ethereum (string) or Gnosis (string) or Polygon (string) or Arbitrum (string) or Linea (string) or Base (string) or Noble (string) or Sepolia (string) or Chiado (string) or Amoy (string) or Arbitrum Sepolia (string) or Linea Sepolia (string) or Base Sepolia (string) or Noble Grand (string) (Chain)
Example: ethereum

Chain name

query Parameters
currency
string (Currency)
Enum: "eur" "usd" "gbp" "isk"

Currency to return the balance for. If not provided eur is used. Can be used multiple times to get multiple currencies.

Responses

Response Schema: application/json
address
string (Address) ^0x[0-9a-fA-F]{40}$

The public key of the blockchain account.

Ethereum (string) or Gnosis (string) or Polygon (string) or Arbitrum (string) or Linea (string) or Base (string) or Noble (string) or Sepolia (string) or Chiado (string) or Amoy (string) or Arbitrum Sepolia (string) or Linea Sepolia (string) or Base Sepolia (string) or Noble Grand (string) (Chain)
Array of objects

The amount owned of currency

Request samples 

curl https://api.monerium.dev/balances/ethereum/0x59cFC408d310697f9D3598e1BE75B0157a072407 \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response samples

Content type
application/json
{
  • "address": "0x59cFC408d310697f9D3598e1BE75B0157a072407",
  • "chain": "ethereum",
  • "balances": [
    ]
}

IBANs

Provision and manage IBANs linked to blockchain addresses. Incoming SEPA payments are automatically minted as EURe to the linked address. See the EUR IBAN guide.

Request IBAN

Create an IBAN for a specified address and chain. All incoming EUR payments will automatically be routed to the linked address on that chain. Any linked address can use this IBAN for outgoing payments.

Authorizations:
BearerAuth
header Parameters
Accept
required
string
Example: application/vnd.monerium.api-v2+json

Accept header to specify API version 2

Request Body schema: application/json
address
required
string (Address) ^0x[0-9a-fA-F]{40}$

The public key of the blockchain account.

required
Ethereum (string) or Gnosis (string) or Polygon (string) or Arbitrum (string) or Linea (string) or Base (string) or Noble (string) or Sepolia (string) or Chiado (string) or Amoy (string) or Arbitrum Sepolia (string) or Linea Sepolia (string) or Base Sepolia (string) or Noble Grand (string) (Chain)

Responses

Response Schema: application/json
object

Request samples

Content type
application/json
{
  • "address": "0x59cFC408d310697f9D3598e1BE75B0157a072407",
  • "chain": "ethereum"
}

Response samples

Content type
application/json
{ }

IBANs

List of IBANs that have been created. You can filter by the address, or the chain they are connected to.

Authorizations:
BearerAuth
query Parameters
profile
string <UUID> (UUID) ^[0-9a-f]{8}-[0-9a-f]{4}-[4][0-9a-f]{3}-[89ab...
Example: profile=a78d8ff2-e51f-11ed-9e13-cacb9390199c

Return the list for the profile ID. By default the caller profile is used.

Ethereum (string) or Gnosis (string) or Polygon (string) or Arbitrum (string) or Linea (string) or Base (string) or Noble (string) or Sepolia (string) or Chiado (string) or Amoy (string) or Arbitrum Sepolia (string) or Linea Sepolia (string) or Base Sepolia (string) or Noble Grand (string) (Chain)
Example: chain=ethereum

Filter the list on the chain

header Parameters
Accept
required
string
Example: application/vnd.monerium.api-v2+json

Accept header to specify API version 2

Responses

Response Schema: application/json
Array of objects (IBANObject)
Array
iban
string (IBAN) ^(?:[A-Z]{2}[0-9]{2}(?:\s?[0-9A-Z]{4}){1,7}\s...

The IBAN is a unique identifier for a bank account across different countries and includes a two-letter country code, two check digits, and a number of alphanumeric characters. It may include spaces for readability but should be stored without spaces.

name
string

The name of the IBAN owner. This can be a corporate or an individual.

bic
string

Bank Identifier Code (BIC) of the bank associated with this IBAN.

profile
string <UUID> (UUID) ^[0-9a-f]{8}-[0-9a-f]{4}-[4][0-9a-f]{3}-[89ab...

The profile id that owns the IBAN

address
string (Address) ^0x[0-9a-fA-F]{40}$

The address that this IBAN is connected to

Ethereum (string) or Gnosis (string) or Polygon (string) or Arbitrum (string) or Linea (string) or Base (string) or Noble (string) or Sepolia (string) or Chiado (string) or Amoy (string) or Arbitrum Sepolia (string) or Linea Sepolia (string) or Base Sepolia (string) or Noble Grand (string) (Chain)

Request samples 

curl https://api.monerium.dev/ibans?profile=a78d8ff2-e51f-11ed-9e13-cacb9390199 \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Accept: application/vnd.monerium.api-v2+json"

Response samples

Content type
application/json
{
  • "ibans": [
    ]
}

IBAN

Get details for a single IBAN.

Authorizations:
BearerAuth
path Parameters
iban
required
string (IBAN) ^(?:[A-Z]{2}[0-9]{2}(?:\s?[0-9A-Z]{4}){1,7}\s...
Example: EE127310138155512606682602

The IBAN is a unique identifier for a bank account across different countries and includes a two-letter country code, two check digits, and a number of alphanumeric characters. It may include spaces for readability but should be stored without spaces.

header Parameters
Accept
required
string
Example: application/vnd.monerium.api-v2+json

Accept header to specify API version 2

Responses

Response Schema: application/json
iban
string (IBAN) ^(?:[A-Z]{2}[0-9]{2}(?:\s?[0-9A-Z]{4}){1,7}\s...

The IBAN is a unique identifier for a bank account across different countries and includes a two-letter country code, two check digits, and a number of alphanumeric characters. It may include spaces for readability but should be stored without spaces.

name
string

The name of the IBAN owner. This can be a corporate or an individual.

bic
string

Bank Identifier Code (BIC) of the bank associated with this IBAN.

profile
string <UUID> (UUID) ^[0-9a-f]{8}-[0-9a-f]{4}-[4][0-9a-f]{3}-[89ab...

The profile id that owns the IBAN

address
string (Address) ^0x[0-9a-fA-F]{40}$

The address that this IBAN is connected to

Ethereum (string) or Gnosis (string) or Polygon (string) or Arbitrum (string) or Linea (string) or Base (string) or Noble (string) or Sepolia (string) or Chiado (string) or Amoy (string) or Arbitrum Sepolia (string) or Linea Sepolia (string) or Base Sepolia (string) or Noble Grand (string) (Chain)

Request samples 

curl https://api.monerium.dev/ibans/EE73I9684012278810458214196 \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Accept: application/vnd.monerium.api-v2+json"

Response samples

Content type
application/json
{
  • "iban": "EE127310138155512606682602",
  • "name": "Jane Doe",
  • "bic": "EAPFESM2XXX",
  • "profile": "a78d8ff2-e51f-11ed-9e13-cacb9390199c",
  • "address": "0x59cFC408d310697f9D3598e1BE75B0157a072407",
  • "chain": "ethereum"
}

Move IBAN

Move an existing IBAN to a specified address an chain. All incoming EUR payments will automatically be routed to the address on that chain.

Authorizations:
BearerAuth
path Parameters
iban
required
string (IBAN) ^(?:[A-Z]{2}[0-9]{2}(?:\s?[0-9A-Z]{4}){1,7}\s...
Example: EE127310138155512606682602

The IBAN is a unique identifier for a bank account across different countries and includes a two-letter country code, two check digits, and a number of alphanumeric characters. It may include spaces for readability but should be stored without spaces.

header Parameters
Accept
required
string
Example: application/vnd.monerium.api-v2+json

Accept header to specify API version 2

Request Body schema: application/json
address
required
string (Address) ^0x[0-9a-fA-F]{40}$

The public key of the blockchain account.

required
Ethereum (string) or Gnosis (string) or Polygon (string) or Arbitrum (string) or Linea (string) or Base (string) or Noble (string) or Sepolia (string) or Chiado (string) or Amoy (string) or Arbitrum Sepolia (string) or Linea Sepolia (string) or Base Sepolia (string) or Noble Grand (string) (Chain)

Responses

Response Schema: application/json
object

Request samples

Content type
application/json
{
  • "address": "0x59cFC408d310697f9D3598e1BE75B0157a072407",
  • "chain": "ethereum"
}

Response samples

Content type
application/json
{ }

Orders

An order represents a fund movement: an issue (EURe minted on incoming payment) or a redeem (EURe burned for an outgoing SEPA payment or cross-chain transfer). See the Orders guide.

Place order

An order represents an instruction to transfer funds from one account to another. The transfer can occur within the blockchain ecosystem (cross-chain) or from a blockchain account to a traditional bank account via SEPA.

An order requires a signature from the wallet owner to authorize the processing of the order. The wallet owner signs a specific message to prove ownership and consent for the transaction.

Attaching a supporting document for amounts above 15,000 EUR is required. Supporting document can be an invoice or an agreement.

Read more about how to upload a file.
Authorizations:
BearerAuth
header Parameters
Accept
required
string
Example: application/vnd.monerium.api-v2+json

Accept header to specify API version 2

Request Body schema: application/json
id
string <UUID> (UUID) ^[0-9a-f]{8}-[0-9a-f]{4}-[4][0-9a-f]{3}-[89ab...

The unique identifier of the order.

address
required
string (Address) ^0x[0-9a-fA-F]{40}$

The address to redeem from. Can be any Monerium linked address.

currency
required
string (Currency)
Enum: "eur" "usd" "gbp" "isk"

Three-letter ISO currency code, in lowercase.

required
Ethereum (string) or Gnosis (string) or Polygon (string) or Arbitrum (string) or Linea (string) or Base (string) or Noble (string) or Sepolia (string) or Chiado (string) or Amoy (string) or Arbitrum Sepolia (string) or Linea Sepolia (string) or Base Sepolia (string) or Noble Grand (string) (Chain)
kind
required
string
Value: "redeem"

Identifier specifying the nature of the order.

Redeem order is when tokens are burned on blockchain and sent to bank.

amount
required
string

The quantity of money sent, represented as a series of digits, possibly followed by a decimal point and up to two additional digits. The amount must be a non-negative value.

required
object (Counterpart)

The counterpart represents the other party involved in a financial transaction, such as the recipient of a payment or the payer. The counterpart can be either an individual or a corporate. It includes identifying information such as account details, name, and country.

required
IBAN (string) or Cross-chain transaction (string)

A string message that the wallet owner must sign to authorize the processing of the order. This signed message verifies the consent of the wallet owner, ensuring that the transaction can proceed securely and legitimately.

required
EOA address (string) or Safe onchain (string) or Safe offchain (string)
memo
string (Memo) [ 5 .. 140 ] characters

UTF-8 Payment reference / memo. Can be used as filter parameters when querying orders.

referenceNumber
string (ReferenceNumber) [ 0 .. 35 ] characters

UTF-8 Payment reference. Structured identifier for a transaction or order, typically used for automatic payment reconciliation

supportingDocumentId
string <UUID> (UUID) ^[0-9a-f]{8}-[0-9a-f]{4}-[4][0-9a-f]{3}-[89ab...

File ID, required for orders with amount greater or equal to €15,000.

Responses

Response Schema: application/json
id
required
string <UUID> ^[0-9a-f]{8}-[0-9a-f]{4}-[4][0-9a-f]{3}-[89ab...

The ID of the order.

kind
required
string
Enum: "issue" "redeem"

Issue orders are created when payment is received and the token, e.g. EURe, is minted to the specified address and chain. Redeem orders are created for sending outgoing payments. The tokens, e.g. EURe, are burned from the specified address and chain and then sent to the Counterpart.

profile
required
string <UUID> (UUID) ^[0-9a-f]{8}-[0-9a-f]{4}-[4][0-9a-f]{3}-[89ab...

Unique identifier of the profile involved in the order.

address
required
string (Address) ^0x[0-9a-fA-F]{40}$

The public key of the blockchain account.

required
Ethereum (string) or Gnosis (string) or Polygon (string) or Arbitrum (string) or Linea (string) or Base (string) or Noble (string) or Sepolia (string) or Chiado (string) or Amoy (string) or Arbitrum Sepolia (string) or Linea Sepolia (string) or Base Sepolia (string) or Noble Grand (string) (Chain)
currency
required
string (Currency)
Enum: "eur" "usd" "gbp" "isk"

Three-letter ISO currency code, in lowercase.

amount
required
string

The order amount.

required
object (CounterpartResponse)

The counterpart represents the other party involved in a financial transaction, such as the recipient of a payment or the payer. The counterpart can be either an individual or a corporate. It includes identifying information such as account details, name, and country.

memo
required
string (Memo) [ 5 .. 140 ] characters

UTF-8 Payment reference / memo. Can be used as filter parameters when querying orders.

referenceNumber
string (ReferenceNumber) [ 0 .. 35 ] characters

UTF-8 Payment reference. Structured identifier for a transaction or order, typically used for automatic payment reconciliation

state
required
string
Enum: "placed" "pending" "processed" "rejected"

The state of the order:

  • placed: The order has been created but not yet processed.
  • pending: The order is awaiting fulfillment (e.g., review, minting/burning tokens, or sending/receiving SEPA payment).
  • processed: The order has been completed successfully.
  • rejected: The order was rejected, possibly due to compliance reasons or insufficient funds.
required
object
Response Schema: application/json
code
integer
status
string

Request samples

Content type
application/json
{
  • "id": "a78d8ff2-e51f-11ed-9e13-cacb9390199c",
  • "address": "0x59cFC408d310697f9D3598e1BE75B0157a072407",
  • "currency": "eur",
  • "chain": "ethereum",
  • "kind": "redeem",
  • "amount": "1000",
  • "counterpart": {
    },
  • "message": "Send EUR 1 to EE127310138155512606682602 at 2024-07-12T12:02:49Z",
  • "signature": "0x5rc0b4cb4efbb577cb0c19d1cb23c7cc4912d2138b3267ee4799c88a68e203a5d568bec12f5da2b3a416f9bb03257b472a1605bf489bcdb805c2c029c212d3a5120505f52546da16217f630339cd332d6049f11cf15a1a82939663a58b02d129c40607c0c290ace726c89c35228b6485f5d3796d6c10df5b8a0de196092797bfe7e1f",
  • "memo": "Powered by Monerium",
  • "referenceNumber": "RF123456789",
  • "supportingDocumentId": "a78d8ff2-e51f-11ed-9e13-cacb9390199c"
}

Response samples

Content type
application/json
{
  • "id": "8c0fd7b1-01da-11ed-89c1-52c47a86c354",
  • "kind": "redeem",
  • "profile": "a78d8ff2-e51f-11ed-9e13-cacb9390199c",
  • "address": "0x59cFC408d310697f9D3598e1BE75B0157a072407",
  • "chain": "ethereum",
  • "currency": "eur",
  • "amount": "999",
  • "counterpart": {
    },
  • "memo": "Powered by Monerium",
  • "referenceNumber": "RF123456789",
  • "state": "rejected",
  • "meta": {
    }
}

Orders

Retrieves all orders for the caller profile. Query parameters can be used to filter and sort the result.

Authorizations:
BearerAuth
query Parameters
address
string (Address) ^0x[0-9a-fA-F]{40}$
Example: address=0x798728D5410aB4FB49d2C277A49baC5048aB43ca

Get all orders belonging to a specific blockchain address.

txHash
string
Example: txHash=0x692ff12125b71c167b3ea90bddb3b28edd60941851cb0cdd852cc3b6d79311cd

The blockchains transaction hash.

profile
string <UUID> (UUID) ^[0-9a-f]{8}-[0-9a-f]{4}-[4][0-9a-f]{3}-[89ab...
Example: profile=123e4567-e89b-12d3-a456-426614174000

The profile ID which the order belongs to. By default the caller profile ID is used.

memo
string (Memo) [ 5 .. 140 ] characters
Example: memo=Powered by Monerium

UTF-8 Payment reference / memo. Can be used as filter parameters when querying orders.

state
string
Enum: "pending" "processed" "rejected"

Get all orders in a particular state:

  • pending: The order is being processed (e.g., review, minting/burning tokens, or sending/receiving SEPA payment).
  • processed: The order has been completed successfully.
  • rejected: The order was rejected, possibly due to compliance reasons or insufficient funds.
header Parameters
Accept
required
string
Example: application/vnd.monerium.api-v2+json

Accept header to specify API version 2

Responses

Response Schema: application/json
Array of objects (Order)
Array
id
required
string <UUID> ^[0-9a-f]{8}-[0-9a-f]{4}-[4][0-9a-f]{3}-[89ab...

The ID of the order.

kind
required
string
Enum: "issue" "redeem"

Issue orders are created when payment is received and the token, e.g. EURe, is minted to the specified address and chain. Redeem orders are created for sending outgoing payments. The tokens, e.g. EURe, are burned from the specified address and chain and then sent to the Counterpart.

profile
required
string <UUID> (UUID) ^[0-9a-f]{8}-[0-9a-f]{4}-[4][0-9a-f]{3}-[89ab...

Unique identifier of the profile involved in the order.

address
required
string (Address) ^0x[0-9a-fA-F]{40}$

The public key of the blockchain account.

required
Ethereum (string) or Gnosis (string) or Polygon (string) or Arbitrum (string) or Linea (string) or Base (string) or Noble (string) or Sepolia (string) or Chiado (string) or Amoy (string) or Arbitrum Sepolia (string) or Linea Sepolia (string) or Base Sepolia (string) or Noble Grand (string) (Chain)
currency
required
string (Currency)
Enum: "eur" "usd" "gbp" "isk"

Three-letter ISO currency code, in lowercase.

amount
required
string

The order amount.

required
object (CounterpartResponse)

The counterpart represents the other party involved in a financial transaction, such as the recipient of a payment or the payer. The counterpart can be either an individual or a corporate. It includes identifying information such as account details, name, and country.

memo
required
string (Memo) [ 5 .. 140 ] characters

UTF-8 Payment reference / memo. Can be used as filter parameters when querying orders.

referenceNumber
string (ReferenceNumber) [ 0 .. 35 ] characters

UTF-8 Payment reference. Structured identifier for a transaction or order, typically used for automatic payment reconciliation

state
required
string
Enum: "placed" "pending" "processed" "rejected"

The state of the order:

  • placed: The order has been created but not yet processed.
  • pending: The order is awaiting fulfillment (e.g., review, minting/burning tokens, or sending/receiving SEPA payment).
  • processed: The order has been completed successfully.
  • rejected: The order was rejected, possibly due to compliance reasons or insufficient funds.
required
object

Request samples 

curl https://api.monerium.dev/orders \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Accept: application/vnd.monerium.api-v2+json"

Response samples

Content type
application/json
{
  • "orders": [
    ]
}

Order

Retrieve the details of an existing order. Supply the unique order ID from either an order creation or the order list, and Monerium will return the corresponding order information

Authorizations:
BearerAuth
path Parameters
orderId
required
string

The ID of the order

header Parameters
Accept
required
string
Example: application/vnd.monerium.api-v2+json

Accept header to specify API version 2

Responses

Response Schema: application/json
id
required
string <UUID> ^[0-9a-f]{8}-[0-9a-f]{4}-[4][0-9a-f]{3}-[89ab...

The ID of the order.

kind
required
string
Enum: "issue" "redeem"

Issue orders are created when payment is received and the token, e.g. EURe, is minted to the specified address and chain. Redeem orders are created for sending outgoing payments. The tokens, e.g. EURe, are burned from the specified address and chain and then sent to the Counterpart.

profile
required
string <UUID> (UUID) ^[0-9a-f]{8}-[0-9a-f]{4}-[4][0-9a-f]{3}-[89ab...

Unique identifier of the profile involved in the order.

address
required
string (Address) ^0x[0-9a-fA-F]{40}$

The public key of the blockchain account.

required
Ethereum (string) or Gnosis (string) or Polygon (string) or Arbitrum (string) or Linea (string) or Base (string) or Noble (string) or Sepolia (string) or Chiado (string) or Amoy (string) or Arbitrum Sepolia (string) or Linea Sepolia (string) or Base Sepolia (string) or Noble Grand (string) (Chain)
currency
required
string (Currency)
Enum: "eur" "usd" "gbp" "isk"

Three-letter ISO currency code, in lowercase.

amount
required
string

The order amount.

required
object (CounterpartResponse)

The counterpart represents the other party involved in a financial transaction, such as the recipient of a payment or the payer. The counterpart can be either an individual or a corporate. It includes identifying information such as account details, name, and country.

memo
required
string (Memo) [ 5 .. 140 ] characters

UTF-8 Payment reference / memo. Can be used as filter parameters when querying orders.

referenceNumber
string (ReferenceNumber) [ 0 .. 35 ] characters

UTF-8 Payment reference. Structured identifier for a transaction or order, typically used for automatic payment reconciliation

state
required
string
Enum: "placed" "pending" "processed" "rejected"

The state of the order:

  • placed: The order has been created but not yet processed.
  • pending: The order is awaiting fulfillment (e.g., review, minting/burning tokens, or sending/receiving SEPA payment).
  • processed: The order has been completed successfully.
  • rejected: The order was rejected, possibly due to compliance reasons or insufficient funds.
required
object

Request samples 

curl https://api.monerium.dev/orders/b48f7ca4-e51f-11ed-9e13-cacb9390199c \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Accept: application/vnd.monerium.api-v2+json"

Response samples

Content type
application/json
{
  • "id": "8c0fd7b1-01da-11ed-89c1-52c47a86c354",
  • "kind": "redeem",
  • "profile": "a78d8ff2-e51f-11ed-9e13-cacb9390199c",
  • "address": "0x59cFC408d310697f9D3598e1BE75B0157a072407",
  • "chain": "ethereum",
  • "currency": "eur",
  • "amount": "999",
  • "counterpart": {
    },
  • "memo": "Powered by Monerium",
  • "referenceNumber": "RF123456789",
  • "state": "rejected",
  • "meta": {
    }
}

Signatures

Fetch pending signature requests for linking addresses and approving orders. Used with smart contract wallets that sign on-chain. See the Link a wallet guide.

Get pending signatures

Returns pending signatures for the authenticated user, filterable by address, chain, and kind (order, linkAddress).

Authorizations:
BearerAuth
query Parameters
address
string (Address) ^0x[0-9a-fA-F]{40}$
Example: address=0x59cFC408d310697f9D3598e1BE75B0157a072407

Filter by blockchain address

Ethereum (string) or Gnosis (string) or Polygon (string) or Arbitrum (string) or Linea (string) or Base (string) or Noble (string) or Sepolia (string) or Chiado (string) or Amoy (string) or Arbitrum Sepolia (string) or Linea Sepolia (string) or Base Sepolia (string) or Noble Grand (string) (Chain)
Example: chain=ethereum

Filter by blockchain network

kind
string
Enum: "linkAddress" "order"

Filter by signature request kind

profile
string <UUID> (UUID) ^[0-9a-f]{8}-[0-9a-f]{4}-[4][0-9a-f]{3}-[89ab...
Example: profile=a78d8ff2-e51f-11ed-9e13-cacb9390199c

UUID of the profile (defaults to authenticated user's default profile)

header Parameters
Accept
required
string
Example: application/vnd.monerium.api-v2+json

Accept header to specify API version 2

Responses

Response Headers
X-Total-Count
integer

Total number of signatures returned

Response Schema: application/json
Array of objects (PendingSignature)
total
integer

Total number of pending signatures

Request samples 

curl https://api.monerium.dev/signatures \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Accept: application/vnd.monerium.api-v2+json"

Response samples

Content type
application/json
Example
{
  • "pending": [
    ],
  • "total": 1
}

Files

Upload files to obtain a fileId for use in profile verifications and orders above €15,000. See the Onboarding guide for verification requirements.

File upload

Upload documents for KYC onboarding and order support.

Authorizations:
BearerAuth
Request Body schema: multipart/form-data
required
file
required
string (file)

Path to the file.

Maximum length filename: 100
Maximum size: 5 MB
Allowed file types: PDF, JPEG

Responses

Response Schema: application/json
id
string

File ID

name
string

File name

type
string

File type

size
integer

File size

hash
string
object

Request samples 

curl --form file='@doc.pdf' https://api.monerium.dev/files

Response samples

Content type
application/json
{
  • "id": "3ebc51a8-044f-11ed-8b1f-4a76448b7b21",
  • "name": "doc.pdf",
  • "type": "application/pdf",
  • "size": 595101,
  • "hash": "f2d8e62b44c59079536910eeb595f91833874a44aafc42c73c80588d91e7796b",
  • "meta": {
    }
}

Webhooks

Receive real-time event notifications for profile approvals, IBAN provisioning, and order state changes. See the Webhooks guide for registration and signature verification details.

Subscription created Webhook

This notification is used to validate if receiver is able to handle webhook notifications. Your webhook endpoint must respond with a 200 OK status code to indicate successful receipt. If the delivery fails, the subscription won't be created.

Request Body schema: application/json
required
type
string
Value: "subscription.created"

The type of the event.

timestamp
string <date-time> (TimeStamp) ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z...

The timestamp in RFC3339 format. It includes the date, time to the second, and optional fractional seconds, followed by 'Z' to indicate UTC time.

Responses

Request samples

Content type
application/json
{
  • "type": "subscription.created",
  • "timestamp": "2024-07-29T12:21:58.777884Z"
}

Order created Webhook

This notification represents an order creation.

It's send as a POST request to the endpoint specified during subscription creation.

Request Body schema: application/json
required
type
string
Value: "order.created"

The type of the event.

timestamp
string <date-time> (TimeStamp) ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z...

The timestamp in RFC3339 format. It includes the date, time to the second, and optional fractional seconds, followed by 'Z' to indicate UTC time.

object (Order)

Responses

Request samples

Content type
application/json
{
  • "type": "order.created",
  • "timestamp": "2024-07-29T12:21:58.777884Z",
  • "data": {
    }
}

Order updated Webhook

This notification represents an order update event. It's sent when an order is processed or rejected.

It's send as a POST request to the endpoint specified during subscription creation.

Request Body schema: application/json
required
type
string
Value: "order.updated"

The type of the event.

timestamp
string <date-time> (TimeStamp) ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z...

The timestamp in RFC3339 format. It includes the date, time to the second, and optional fractional seconds, followed by 'Z' to indicate UTC time.

object (Order)

Responses

Request samples

Content type
application/json
{
  • "type": "order.updated",
  • "timestamp": "2024-07-29T12:21:58.777884Z",
  • "data": {
    }
}

Profile updated Webhook

Sent when a profile's state changes. Your endpoint must respond with 200 OK; failed deliveries are retried with exponential backoff up to 10 times over 12 hours.

Request Body schema: application/json
required
type
string
Value: "profile.updated"

The type of the event.

timestamp
string <date-time> (TimeStamp) ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z...

The timestamp in RFC3339 format. It includes the date, time to the second, and optional fractional seconds, followed by 'Z' to indicate UTC time.

Personal (object) or Corporate (object) (Profile)

Responses

Request samples

Content type
application/json
{
  • "type": "profile.updated",
  • "timestamp": "2024-07-29T12:21:58.777884Z",
  • "data": {
    }
}

IBAN updated Webhook

Sent when an IBAN is updated. Your endpoint must respond with 200 OK; failed deliveries are retried with exponential backoff up to 10 times over 12 hours.

Request Body schema: application/json
required
type
string
Value: "iban.updated"

The type of the event.

timestamp
string <date-time> (TimeStamp) ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z...

The timestamp in RFC3339 format. It includes the date, time to the second, and optional fractional seconds, followed by 'Z' to indicate UTC time.

object (IBANObject)

Responses

Request samples

Content type
application/json
{
  • "type": "iban.updated",
  • "timestamp": "2024-07-29T12:21:58.777884Z",
  • "data": {
    }
}

List subscriptions

Whitelabel Private

List all webhook subscriptions for the authenticated user. The response includes the details of each subscription, such as the URL, secret, and event types.

Authorizations:
BearerAuth
header Parameters
Accept
required
string
Example: application/vnd.monerium.api-v2+json

Accept header to specify API version 2

Responses

Response Schema: application/json
Array of objects (WebhookSubscription)
Array
id
required
string <UUID> (UUID) ^[0-9a-f]{8}-[0-9a-f]{4}-[4][0-9a-f]{3}-[89ab...

Unique identifier of the webhook subscription.

url
required
string <uri>

The URL to which the webhook events will be sent.

types
required
Array of arrays

List of event types that trigger the webhook.

state
required
string
Enum: "active" "inactive"

The state of the webhook subscription.

Response samples

Content type
application/json
{
  • "subscriptions": [
    ]
}

Create subscription

Whitelabel Private

Create webhook subscription to receive notifications like profile update on specified endpoint. Subscription created notification is sent during subscription creation to validate if receiver is able to handle further notifications.

Authorizations:
BearerAuth
Request Body schema: application/json
required
url
required
string

The URL where the notification will be sent.

secret
required
string

A secret key used to verify the authenticity of webhook notifications. Each notification is sent with a webhook-signature header, which contains a minified JSON payload encrypted using the secret key via the HMAC-SHA256 scheme. The secret key must be a base64-encoded, random value between 24 and 64 bytes, prefixed with whsec_.

types
Array of strings
Items Enum: "iban.updated" "order.created" "order.updated" "profile.updated"

An array of event types that the webhook will subscribe to. If not specified, default events types are subscribed to.

Default event types:

  • iban.updated
  • profile.updated

Responses

Response Schema: application/json
id
required
string <UUID> (UUID) ^[0-9a-f]{8}-[0-9a-f]{4}-[4][0-9a-f]{3}-[89ab...

Unique identifier of the webhook subscription.

url
required
string <uri>

The URL to which the webhook events will be sent.

types
required
Array of arrays

List of event types that trigger the webhook.

state
required
string
Enum: "active" "inactive"

The state of the webhook subscription.

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "id": "a78d8ff2-e51f-11ed-9e13-cacb9390199c",
  • "url": "https://example.com/webhook",
  • "types": [
    ],
  • "state": "active"
}

Update subscription

Whitelabel Private

Update an existing webhook subscription to change the URL, secret, or event types. The updated subscription will be validated by sending a subscription created notification to the new URL.

Authorizations:
BearerAuth
path Parameters
subscription
required
string <uuid>

The ID of the webhook subscription

header Parameters
Accept
required
string
Example: application/vnd.monerium.api-v2+json

Accept header to specify API version 2

Request Body schema: application/json
state
string
Enum: "active" "inactive"

The state of the webhook subscription. If set to inactive, the webhook will not send notifications. If set to active, the webhook will send notifications as usual.

types
Array of strings
Items Enum: "iban.updated" "order.created" "order.updated" "profile.updated"

An array of event types that the webhook will subscribe to. If not specified, default events types are subscribed to.

Default event types:

  • iban.updated
  • profile.updated

Responses

Response Schema: application/json
id
required
string <UUID> (UUID) ^[0-9a-f]{8}-[0-9a-f]{4}-[4][0-9a-f]{3}-[89ab...

Unique identifier of the webhook subscription.

url
required
string <uri>

The URL to which the webhook events will be sent.

types
required
Array of arrays

List of event types that trigger the webhook.

state
required
string
Enum: "active" "inactive"

The state of the webhook subscription.

Request samples

Content type
application/json
{
  • "state": "active",
  • "types": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "a78d8ff2-e51f-11ed-9e13-cacb9390199c",
  • "url": "https://example.com/webhook",
  • "types": [
    ],
  • "state": "active"
}

Tokens

Supported e-money tokens with contract addresses and chain details. For icons, integration examples, and supported standards, see the Tokens section in the developer docs.

Tokens

Returns supported tokens with their tickers, decimals, and contract addresses per chain. For icons, integration examples, and supported standards, see the Tokens section in the developer docs.

Authorizations:
BearerAuth

Responses

Response Schema: application/json
Array
currency
string (Currency)
Enum: "eur" "usd" "gbp" "isk"

Three-letter ISO currency code, in lowercase.

ticker
any
Enum: "EUR" "GBP" "USD" "ISK"

The traditional currency abbreviation.

symbol
any
Enum: "EURe" "GBPe" "USDe" "ISKe"

The official symbol of the token used in DeFi platforms.

Ethereum (string) or Gnosis (string) or Polygon (string) or Arbitrum (string) or Linea (string) or Base (string) or Noble (string) or Sepolia (string) or Chiado (string) or Amoy (string) or Arbitrum Sepolia (string) or Linea Sepolia (string) or Base Sepolia (string) or Noble Grand (string) (Chain)
address
string

The address of the token.

decimals
string

Number of decimals used in the asset.

Request samples 

curl https://api.monerium.dev/tokens \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response samples

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

Changelog

2026-05-08:

  • PATCH /profiles/{profile}/verifications - Each verification item now takes a documents array instead of a single fileId. Each document has kind, fileId, and an optional side. Corporate verifications support a personId field to submit documents for a specific person (representative, director, or beneficial owner).
  • PATCH /profiles/{profile}/verifications - Updated verification type facialSimilarity to facialSimilarityMotion for better alignment with the wire value.

2026-05-07:

2026-05-06:

2026-04-29:

  • PATCH /profiles/{profileId}/verifications - Separated request schemas (UpdatePersonalVerifications and UpdateCorporateVerifications) from response schemas.
  • Profile response schema now explicitly uses oneOf to return either a ProfilePersonal or ProfileCorporate structure based on the kind.
  • Verification items in profile responses now correctly document the state property.

2026-04-28:

  • GET /countries - Added countries endpoint to fetch supported countries and their details.

2026-04-27:

  • POST /auth, GET /auth - Added auth_mode query parameter to control initial auth screen (login or signup) when the user is not authenticated.

2026-04-08:

2026-02-25:

  • Orders now include txHashes in the meta field, containing the blockchain transaction hashes for the mint or burn. Only present once the order has been processed on-chain.

2026-02-17:

  • Removed skip_create_account from Athorization endpoint query parameters as it is no longer used in the flow. Use the Link Address and Request IBAN endpoints instead.
  • Enabled KYC testing in the Authorization flow. By default the skip_kyc parameter is false.

2026-02-02:

  • Add missing 202 Status for Order creation endpoint.
  • Add /signatures documentation to fetch pending signature requests.

2026-01-22:

  • Base chain supported.

2025-11-14:

  • Orders now support the referenceNumber field for structured SEPA reference info (max 35 characters). The field is available in the POST /place-order request, GET /order/{id} and GET /orders responses, as well as in order webhooks.
  • WIP Order memo field - Effective 15th of December, the memo field in incoming SEPA payments will hold only unstructured remittance text. Structured reference will be provided exclusively in the referenceNumber field. Please ensure your integration uses referenceNumber for structured references before this change takes effect.

2025-07-17:

  • Noble testnet chain identifier is now grand, previously noble.
  • Noble chain identifier, noble, documented.
  • Linea and Linea Sepolia chain identifiers, linea and lineasepolia documented.

2024-11-11:

  • GET/POST /auth changes to query parameters.
    • added email: You can prefill the email field for login and sign up steps to ensure the user uses the correct email.
    • added skip_kyc: You can skip the KYC onboarding steps in the Authorization Flow and use the the details, additional data, and verifications API endpoints after you have gotten the authorization.
    • changed skip_create_account: changed skipCreateAccount to snake case for consistency.

2024-10-22:

  • WIP GET /orders - We're updating the orders response to return an object with an orders key containing an array of all orders. This new structure makes it easier to handle pagination and extend the response with additional metadata in the future. We plan to release this upgrade within 5th of November.

2024-10-07:

  • POST /orders - Introduced a short format IBAN in the message.

2024-10-04:

2024-09-27

  • GET /balances - added a new endpoint to retrieve the account balances. Removed the deprecated GET /profiles/{profile}/balances endpoint.

2024-09-09

  • POST /auth - removed required version=v2 argument from the request. Clarified required parameters for the oauth flow.

2024-08-30

  • POST /auth - added required version=v2 and Sign in with Ethereum (SIWE) flow.

2024-08-19:

2024-08-09:

2024-07-15:

2024-06-20:

  • POST /auth/signup - Added a 304 response when trying to sign up existing users. This will require explicit authorization from the user using the authorization flow.
  • PUT /ibans/{iban} - New endpoint released to move existing IBANs to another wallet address.