Monerium API (1.1.1)

Download OpenAPI specification:Download

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

Welcome

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

Responses

Response samples

Content type
application/json
{}

Authorization flow

See POST /auth for details.

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'

Authorization flow

This endpoint issues a Temporary Redirect (HTTP 307) to the Authorization Code Flow where users can sign up, onboard, connect their wallets and authorize an app access to their data.

Getting started

Before onboarding users via your application, you must register your application with Monerium. Then, use the Authorization Code Flow client_id and the other parameters below to redirect users to the Monerium onboarding screen.

At the Monerium onboarding screen, users will be prompted to log into their Monerium account or create a new one if necessary. After logging in and undergoing KYC verification, users are required to link an address to their profile to obtain their initial IBAN account number. They must also grant your application permission to access their data.

Upon authorization, users will be redirected back to your application, as specified by the redirect_uri parameter and an authorization code in the query parameters.

This authorization code is then used to request an access token via the token endpoint.

Automated Wallet Address Linking

For users who have previously linked their wallets to your application, you can facilitate their Monerium account onboarding by requesting a signature ahead of time. To ensure their wallet is linked automatically during onboarding, append the address, chain, and signature parameters to your API request.

The signature hash is produced by the user signing this message with their address's private key:

I hereby declare that I am the address owner.

Automated Multi-Signature Wallet Address Linking

To automate multi-signature wallet linking, first initiate a manual signature process within your application. Then, once the signing is completed, set the signature parameter to 0x when calling this endpoint.

Users may need to refresh the page after the signing process to proceed with onboarding.

Additional material:

Request Body schema: application/x-www-form-urlencoded
required
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

Generated challenge from the code_verifier. You must use the same code_verifier when requesting an access token.

Read more about code challenges for PKCE

code_challenge_method
string
Default: "plain"
Enum: "plain" "S256"

Method used to generate the challenge (e.g., S256).

The PKCE spec defines two methods, S256 and plain, the latter is discouraged.

response_type
string
Default: "code"

The kind of credential that will be returned. Only code is supported.

state
string

Recommended. The state parameter will be included when redirecting back to your application. It can be used to store request-specific data and/or prevent CSRF attacks.

redirect_uri
string

The URL to which will redirect the browser after authorization has been granted by the user.

Required if there are more then one redirect URL's registered.
If present, must match one of the registered redirect URLs exactly.

The Authorization Code will be available in the code URL parameter, like so: https://your-app.com/monerium?code=AUTHORIZATION_CODE

Only URLs with the HTTPS-scheme are supported with the exception of http://localhost.

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

The public key of the blockchain account.

signature
string (SignatureAddressOwner)

A predetermined message that must be signed using the private key corresponding to the specified address.

I hereby declare that I am the address owner..

For multi-signature addresses, use "0x" instead of a hash.

Gnosis (string) or Polygon (string) or Ethereum (string) (Chain)

Responses

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'

Get access token

Obtain an access token using one of the three main methods provided by this endpoint:

1. Authorization code

If your application has acquired an authorization code through the PKCE authorization flow and has been granted permission to access the user's data, you can use this authorization code to obtain an access_token using grant_type=authorization_code.

2. Refresh token

Access tokens are short-lived. To maintain access to resources, refresh them upon expiration using grant_type=refresh_token.

3. Client credentials

Request an access_token by using a combination of the Client Credentials client_id and client_secret with grant_type=client_credentials. This method directly authenticates your application for access without user intervention.

NEVER EXPOSE THE CLIENT SECRET TO THE USER, only use client credential in a trusted backend service.

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 partner flow.

code_verifier
required
string

The randomized string that was used to create the code_challenge when a customer/user enters the partner authorization flow. Read more about code challenges for PKCE

redirect_uri
required
string

The same redirect_uri that was used to acquire the authorization_code.

Responses

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"
}

Get auth context

The authentication context provides details about the currently authenticated user, including the method of authentication, their roles, and information on the profiles they are authorized to access.

Authorizations:
BearerAuth

Responses

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": "[email protected]",
  • "roles": [ ],
  • "auth": {},
  • "defaultProfile": "a78d8ff2-e51f-11ed-9e13-cacb9390199c",
  • "profiles": [
    ]
}

Get profiles

Retrieves summaries for all profiles, each summary providing details about the profile, including its type and the permissions the authenticated user holds over these profiles.

Authorizations:
BearerAuth

Responses

Request samples

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

Response samples

Content type
application/json
[
  • {
    }
]

Get profile

Retrieves details about a single profile.

Authorizations:
BearerAuth
path Parameters
profileId
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

Responses

Request samples

curl https://api.monerium.dev/profiles/30f730fd-e51f-11ed-9e13-cacb9390199c \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response samples

Content type
application/json
{
  • "id": "string",
  • "kind": "corporate",
  • "email": "[email protected]",
  • "name": "string",
  • "kyc": {
    },
  • "accounts": [
    ]
}

Get balances

Retrieves the balance for each account within a profile, where each account corresponds to a specific token on a given chain.

Authorizations:
BearerAuth
path Parameters
profileId
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

Responses

Request samples

curl https://api.monerium.dev/profiles/30f730fd-e51f-11ed-9e13-cacb9390199c/balances \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response samples

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

Add address to profile.

Link a blockchain wallet to a profile and establish accounts for Monerium tokens.

Linking a multi-signature contract wallet like Safe

The API supports ERC-1271: Standard Signature Validation Method for Contracts. Both onchain and offchain signatures are supported, example scripts are in the "Request samples" to the right.

For onchain signatures you need to set the signature parameter to 0x.

To use Safe wallet onchain signatures, the signing method needs to be set to Always use on-chain signatures. The setting can be found in the app under Settings > Safe apps > Signing Method.

Safe settings for onchain signatures

Authorizations:
BearerAuth
path Parameters
profileId
required
string

The ID of the profile

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

The public key of the blockchain account.

Array of objects

An EOA Address can exist on multiple chains and hold balances in different currencies. The accounts property represents a collection of account details for an address across different chains and currencies. Each account is a combination of the address, the blockchain (chain) it resides on, and the currency it holds. This structure allows for comprehensive management of your balances by specifying which accounts (defined by their currency, address, and chain) should be visible and accessible.

How to activate EURe on Ethereum and GBPe on Polygon:
[{"currency":"eur","chain":"ethereum"}, {"currency":"gbp","chain":"polygon"}]

signature
required
string (SignatureEOA)

The signature hash of signing the message with the private key associated with the given address.

message
required
string

Fixed message to be signed with the private key corresponding to the given address.

I hereby declare that I am the address owner.

Responses

Request samples

Content type
application/json
Example
{
  • "address": "0x59cFC408d310697f9D3598e1BE75B0157a072407",
  • "accounts": [
    ],
  • "signature": "0x5rc0b4cb4efbb577cb0c19d1cb23c7cc4912d2138b3267ee4799c88a68e203a5d568bec12f5da2b3a416f9bb03257b472a1605bf489bcdb805c2c029c212d3a5120505f52546da16217f630339cd332d6049f11cf15a1a82939663a58b02d129c40607c0c290ace726c89c35228b6485f5d3796d6c10df5b8a0de196092797bfe7e1f",
  • "message": "I hereby declare that I am the address owner."
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "kind": "corporate",
  • "email": "[email protected]",
  • "name": "string",
  • "kyc": {
    },
  • "accounts": [
    ]
}

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.

Authorizations:
BearerAuth
Request Body schema: application/json
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
Gnosis (string) or Polygon (string) or Ethereum (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.

supportingDocumentId
string

File UUID, Required for redeem orders with amount greater or equal to €15,000. See adding supporting document for more details.

Responses

Request samples

Content type
application/json
{
  • "address": "0x59cFC408d310697f9D3598e1BE75B0157a072407",
  • "currency": "eur",
  • "chain": "gnosis",
  • "kind": "redeem",
  • "amount": "1000",
  • "counterpart": {
    },
  • "message": "Send EUR 1 to EE127310138155512606682602 at 2024-07-12T12:02:49Z",
  • "signature": "0x5rc0b4cb4efbb577cb0c19d1cb23c7cc4912d2138b3267ee4799c88a68e203a5d568bec12f5da2b3a416f9bb03257b472a1605bf489bcdb805c2c029c212d3a5120505f52546da16217f630339cd332d6049f11cf15a1a82939663a58b02d129c40607c0c290ace726c89c35228b6485f5d3796d6c10df5b8a0de196092797bfe7e1f",
  • "memo": "Powered by Monerium",
  • "supportingDocumentId": "3ebc51a8-044f-11ed-8b1f-4a76448b7b21"
}

Response samples

Content type
application/json
{
  • "id": "8c0fd7b1-01da-11ed-89c1-52c47a86c354",
  • "kind": "redeem",
  • "profile": "a78d8ff2-e51f-11ed-9e13-cacb9390199c",
  • "address": "0x59cFC408d310697f9D3598e1BE75B0157a072407",
  • "chain": "gnosis",
  • "currency": "eur",
  • "amount": "999",
  • "counterpart": {
    },
  • "memo": "Powered by Monerium",
  • "rejectedReason": "",
  • "supportingDocumentId": "3ebc51a8-044f-11ed-8b1f-4a76448b7b21",
  • "meta": {
    }
}

Get all orders

Retrieves all orders accessible by the authenticated user. 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.

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: "placed" "pending" "processed" "rejected"

Get all orders in a particular state:

  • 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.

Responses

Request samples

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

Response samples

Content type
application/json
[
  • {
    }
]

Add supporting document to order

Attaching a supporting document for payouts (redeem orders) above 15,000 EUR is required. Supporting documents can be an invoice or an agreement.

  1. Upload (POST) the file/document to this endpoint.
  2. Use the file ID as the supportingDocumentId when you place a redeem order.
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

Responses

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": {
    }
}

Orders notifications

API consumers have the option to subscribe to a WebSocket for real-time order notifications. This WebSocket complies with the standard WebSocket Protocol, allowing the use of standard WebSocket libraries for subscription.

The WebSocket emits an event when a order changes state:

  • 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.
Authorizations:
BearerAuth
query Parameters
state
string
Enum: "placed" "pending" "processed" "rejected"

Subscribe to all orders in a specific state.

profile
string
Example: profile=6ca4f5a2-f6c9-11ec-81c1-62a51ab3b761

Subscribe to all orders that belong to a specific profile UUID.

Responses

Request samples

npm install -g wscat
wscat -c "wss://api.monerium.dev/orders?state=processed" --header "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response samples

Content type
application/json
[
  • {
    }
]

Get single 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

Responses

Request samples

curl https://api.monerium.dev/orders/b48f7ca4-e51f-11ed-9e13-cacb9390199c \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response samples

Content type
application/json
{
  • "id": "8c0fd7b1-01da-11ed-89c1-52c47a86c354",
  • "kind": "redeem",
  • "profile": "a78d8ff2-e51f-11ed-9e13-cacb9390199c",
  • "address": "0x59cFC408d310697f9D3598e1BE75B0157a072407",
  • "chain": "gnosis",
  • "currency": "eur",
  • "amount": "999",
  • "counterpart": {
    },
  • "memo": "Powered by Monerium",
  • "rejectedReason": "",
  • "supportingDocumentId": "3ebc51a8-044f-11ed-8b1f-4a76448b7b21",
  • "meta": {
    }
}

Get all balances for accounts

Retrieves balance for every accounts of the default profile. Each account represent one token on a chain.

Authorizations:
BearerAuth

Responses

Request samples

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

Response samples

Content type
application/json
[
  • [
    ]
]

Get tokens

Information about the emoney tokens with tickers, symbols, decimals, token contract address and the chain information, we currently support Ethereum, Polygon and Gnosis.

Token addresses and details here: /docs/tokens/

Authorizations:
BearerAuth

Responses

Request samples

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

Response samples

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