Skip to main content
This section now uses an OpenAPI spec to power endpoint pages and the playground. Prefer the endpoint pages in the sidebar for the latest parameters, responses, and live requests. Spec: /openapi/world-miniapps.json.

​
Endpoints

  • POST /api/v2/create-action/
  • POST /api/v2/minikit/send-notification
  • POST /api/v2/verify/
  • GET /api/v2/minikit/transaction/
  • GET /api/v2/minikit/transaction/debug
  • GET /api/v2/minikit/user-grant-cycle
  • GET /public/v1/miniapps/prices
Below content was removed to avoid duplication. Use the endpoint pages in the sidebar.

​
Send Notification

​
method
POST
https://developer.worldcoin.org/api/v2/minikit/send-notification
This endpoint lets you send localized notifications to users of your mini app and requires an api_key.

​
How do localizations work?

The user’s language is available to you when they access your mini app (via Navigator). All you need to do is provide localizations. Our backend will automatically infer which language is preferred by the user. Currently we support only a subset of languages, with plans to expand. Find the entire list here. You can only specify languages that we support.
  • If a user prefers a language that we don’t currently support, we will deliver the notification in English.
  • If you don’t specify a localization for the user’s preferred language, the notification will not be delivered. The response will include a specific reason to inform you of this.

​
Body Params

You are required to either specify both title and message OR localisations.
​
wallet_addresses
string[]
required
The wallet_addresses is an array of wallet addresses to send the notification to. Users must have opted in to notifications for your app. Max 1000 users per call.
​
localisations
object[]
localisations is an array of objects with properties:
  • language (string, required): The language of the notification.
  • title (string, required): The localized title of the notification.
  • message (string, required): The localized message of the notification.
It’s required to provide at least the en language.
​
title
string
Note: This will not localize your notifications. The title is the title of the notification. It should be 30 characters or less. May contain emojis.
​
message
string
Note: This will not localize your notifications. The message is the message of the notification. It should be 200 characters or less. You can include the special variable ${username} in your message, which will be replaced with the actual username of the recipient when the notification is delivered.
​
mini_app_path
string
required
The mini_app_path is the url encoded path of the mini app where your notification should link to when the user clicks on it. Should be of the format worldapp://mini-app?app_id=[app_id]&path=[path] (path is optional).
​
app_id
string
required
The app_id is the identifier of the app initiating the transaction.

​
Request Headers

​
Authorization
string
required
The Authorization header should be the api_key for your app from the Developer Portal. Make sure to prefix it with Bearer {api_key}.
curl -X POST "https://developer.worldcoin.org/api/v2/minikit/send-notification" \
    -H "Authorization: Bearer {api_key}" \
    -H "Content-Type: application/json" \
    -d '{"app_id": "app_id", "wallet_addresses": ["0x123", "0x456"], "title": "title", "message": "Hello ${username}, your transaction is complete!", "mini_app_path": "mini_app_path"}'

​
Response

​
success
boolean
Indicates if the API request was successful.
​
status
number
The HTTP status code of the response.
​
result
array
An array of notification delivery results for each wallet address, where each item contains: - walletAddress (string): The wallet address that the notification was attempted to be sent to - sent (boolean): Whether the notification was successfully sent to this wallet address - reason (string, optional): If the notification failed to send, this field contains the reason
{
    "success": true,
    "status": 200,
    "result": [
        {
            "walletAddress": "0x377da9cab87c04a1d6f19d8b4be9aef8df26fcdd",
            "sent": true
        },
        {
            "walletAddress": "0x444da9cab87c04a1d6f19d8b4be9aef8df26fcdd",
            "sent": false,
            "reason": "User has notification disabled for World App"
        }
    ]
}

​
Supported Languages

LanguageCode
Englishen
Catalanca
Chinese Simplifiedzh_CN
Frenchfr
Germande
Hindihi
Indonesianid
Japaneseja
Koreanko
Malayms
Polishpl
Portuguesept
Spanishes
Spanish (Latin America)es_419
Thaith
Traditional Chinese (Taiwan)zh_TW

​
Get Transaction

​
method
GET
https://developer.worldcoin.org/api/v2/minikit/transaction/{transaction_id} ?app_id=&type=
This endpoint lets you query your apps transactions for their current status. You will only be able to query for transactions of apps where you possess the api_key.

​
Query Params

​
app_id
string
required
The app_id corresponding to the transaction that is being queried.
​
type
string
required
The type is either payment (pay) or transaction (sendTransaction) depending on the command you used.
curl -X GET "https://developer.worldcoin.org/api/v2/minikit/transaction/{transaction_id}"

​
Response

​
reference
string
The reference is your specified unique identifier for the transaction.
​
transaction_hash
string
The transaction_hash is the hash of the transaction on the blockchain.
​
transaction_status
string
The current transaction_status, can be either ‘pending’, ‘mined’, or ‘failed’.
​
from
string
The from is the address of the sender.
​
chain
string
The chain is the name of the blockchain network.
​
timestamp
string
The timestamp is the time when the transaction was created, in ISO 8601 format.
​
token_amount
string
The token_amount is the amount of tokens transferred, in BigInt with 6 decimals.
​
token
string
The token is the type of token transferred.
​
to
string
The to is the address of the receiver.
​
app_id
string
The app_id is the identifier of the app initiating the transaction.
{
    "reference": "1fa38f30-8ee1-4e4b-9988-0517a774f96c",
    "transaction_hash": "0xfb25cb74b13d51deeb1a91460619c3d86a7637d40dd29831aa38dd6cbb05e880",
    "transaction_status": "pending | mined | failed",
    "from": "0x0c892815f0B058E69987920A23FBb33c834289cf",
    "chain": "worldchain",
    "timestamp": "2024-01-01T00:00:00.000Z", // ISO 8601
    "token_amount": "100000000", // amount in BigInt with 6 decimals
    "token": "USDC",
    "to": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    "app_id": "app_9a73963d73efdf2e7d9472593dc9dffd"
}

​
Get Transaction Debug URL

​
method
GET
https://developer.worldcoin.org/api/v2/minikit/transaction/debug?app_id=
This endpoint lets you debug transactions that failed during the prepare stage. It provides Tenderly URLs for permit2 operations with expired permits. You will only be able to query for transactions of apps where you possess the api_key. The debug URL is only available once the permit2 expires. So for development it will be better to set a shorter expiry time so you can get the debug URL quicker.

​
Query Params

​
app_id
string
required
The app_id corresponding to the transaction that is being queried.

​
Request Headers

​
Authorization
string
required
The Authorization header should be the api_key for your app from the Developer Portal. Make sure to prefix it with Bearer {api_key}.
curl -X GET "https://developer.worldcoin.org/api/v2/minikit/transaction/debug?app_id={app_id}" \
    -H "Authorization: Bearer {api_key}"

​
Response

​
transactions
array
An array of transaction debug information, where each item contains: - debugUrl (string): The Tenderly URL for debugging the transaction - createdAt (string): The timestamp when the transaction was created, in ISO 8601 format - block (number): The block number where the transaction was attempted - simulationRequestId (string): The ID of the simulation request - simulationError (string): The error message from the simulation, if any - walletAddress (string): The wallet address associated with the transaction
{
    "transactions": [
        {
            "debugUrl": "https://dashboard.tenderly.co/tx/...",
            "createdAt": "2024-03-21T10:30:00.000Z",
            "block": 12345678,
            "simulationRequestId": "sim_abc123def456",
            "simulationError": "Permit signature expired",
            "walletAddress": "0x1234..."
        }
    ]
}

​
Get Prices

​
method
GET
https://app-backend.worldcoin.dev/public/v1/miniapps/prices?cryptoCurrencies=WLD,USDC&fiatCurrencies=
This endpoint lets you query the latest prices of the Worldcoin token in various fiat currencies. We offer this as a service to make it easier to use WLD as a currency.

​
Query Params

​
fiatCurrencies
string
required
The fiatCurrencies is a comma-separated list of fiat currencies following ISO4217 currency code. eg. USD,EUR,JPY,ARS
​
cryptoCurrencies
string
required
The cryptoCurrencies is a comma-separated list of currencies we support. eg. USDC,WLD
curl -X GET "https://app-backend.worldcoin.dev/public/v1/miniapps/prices?cryptoCurrencies=WLD&fiatCurrencies=USD"

​
Response (abridged)

Detailed are a just a few values in the return that could be confusing. See the response object in the bottom right column for the full list of fields
​
prices
string
The prices is an object where each key is the respective currency code
​
amount
string
The amount represents the non converted value for the price of 1 WLD for a given currency
​
decimals
string
The current decimals, should be used to calculate the converted price. ie an amount of 1000000 with 6 decimals would mean a price of $1.00 via, 1000000 * 10^-6
{
    "result": {
        "prices": {
            "WLD": {
                "USD": {
                    "asset": "USD",
                    "amount": "1510763",
                    "decimals": 6,
                    "symbol": "USD"
                },
            },
            "USDC": {
                "USD": {
                    "asset": "USD",
                    "amount": "1000058",
                    "decimals": 6,
                    "symbol": "USD"
                },
            }
        }
    }
}