Technical Reference

API Reference

Send Notification

POSThttps://developer.worldcoin.org/api/v2/minikit/send-notification

This endpoint lets you send notifications to users of your mini app and requires an api_key.

Body Params

Name
wallet_addresses
Type
string[]
Required
REQUIRED
Description
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.
Name
title
Type
string
Required
REQUIRED
Description
The title is the title of the notification. It should be 30 characters or less.
Name
message
Type
string
Required
REQUIRED
Description
The message is the message of the notification. It should be 200 characters or less.
Name
mini_app_path
Type
string
Required
REQUIRED
Description
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).
Name
app_id
Type
string
Required
REQUIRED
Description
The app_id is the identifier of the app initiating the transaction.

Request Headers

Name
Authorization
Type
string
Required
REQUIRED
Description
The Authorization header should be the api_key for your app from the Developer Portal. Make sure to prefix it with Bearer {api_key}.

Request

POST

https://developer.worldcoin.org/api/v2/minikit/send-notification

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": "message", "mini_app_path": "mini_app_path"}'

Response

Name
success
Type
boolean
Description
Indicates if the API request was successful.
Name
status
Type
number
Description
The HTTP status code of the response.
Name
result
Type
array
Description
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

Response

{
    "success": true,
    "status": 200,
    "result": [
        {
            "walletAddress": "0x377da9cab87c04a1d6f19d8b4be9aef8df26fcdd",
            "sent": true
        },
        {
            "walletAddress": "0x444da9cab87c04a1d6f19d8b4be9aef8df26fcdd",
            "sent": false,
            "reason": "User has notification disabled for World App"
        }
    ]
}

Get Transaction

GEThttps://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

Name
app_id
Type
string
Required
REQUIRED
Description
The app_id corresponding to the transaction that is being queried.
Name
type
Type
string
Required
REQUIRED
Description
The type is either payment (pay) or transaction (sendTransaction) depending on the command you used.

Request

GET

https://developer.worldcoin.org/api/v2/minikit/transaction/{transaction_id}

curl -X GET "https://developer.worldcoin.org/api/v2/minikit/transaction/{transaction_id}"

Response

Name
reference
Type
string
Description
The reference is your specified unique identifier for the transaction.
Name
transaction_hash
Type
string
Description
The transaction_hash is the hash of the transaction on the blockchain.
Name
transaction_status
Type
string
Description
The current transaction_status, can be either 'pending', 'mined', or 'failed'.
Name
from
Type
string
Description
The from is the address of the sender.
Name
chain
Type
string
Description
The chain is the name of the blockchain network.
Name
timestamp
Type
string
Description
The timestamp is the time when the transaction was created, in ISO 8601 format.
Name
token_amount
Type
string
Description
The token_amount is the amount of tokens transferred, in BigInt with 6 decimals.
Name
token
Type
string
Description
The token is the type of token transferred.
Name
to
Type
string
Description
The to is the address of the receiver.
Name
app_id
Type
string
Description
The app_id is the identifier of the app initiating the transaction.

Response

GET

https://developer.worldcoin.org/api/v2/minikit/transaction/{transaction_id}

{
    "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": "USDCE",
    "to": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    "app_id": "app_9a73963d73efdf2e7d9472593dc9dffd"
}

Get Transaction Debug URL

GEThttps://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.

Note that the debug URLs provided by this endpoint typically expire after 1 hour.

Query Params

Name
app_id
Type
string
Required
REQUIRED
Description
The app_id corresponding to the transaction that is being queried.

Request Headers

Name
Authorization
Type
string
Required
REQUIRED
Description
The Authorization header should be the api_key for your app from the Developer Portal. Make sure to prefix it with Bearer {api_key}.

Request

GET

https://developer.worldcoin.org/api/v2/minikit/transaction/debug

curl -X GET "https://developer.worldcoin.org/api/v2/minikit/transaction/debug?app_id={app_id}" \
    -H "Authorization: Bearer {api_key}"

Response

Name
transactions
Type
array
Description
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

Response

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

GEThttps://app-backend.worldcoin.dev/public/v1/miniapps/prices?cryptoCurrencies=WLD,USDCE&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

Name
fiatCurrencies
Type
string
Required
REQUIRED
Description
The fiatCurrencies is a comma-separated list of fiat currencies following ISO4217 currency code. eg. USD,EUR,JPY,ARS

Name
cryptoCurrencies
Type
string
Required
REQUIRED
Description
The cryptoCurrencies is a comma-separated list of currencies we support. eg. USDCE,WLD

Request

GET

https://app-backend.worldcoin.dev/public/v1/miniapps/prices?...

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

Name
prices
Type
string
Description
The prices is an object where each key is the respective currency code
Name
amount
Type
string
Description
The amount represents the non converted value for the price of 1 WLD for a given currency
Name
decimals
Type
string
Description
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

Response

GET

https://app-backend.worldcoin.dev/public/v1/miniapps/prices?...

{
    "result": {
        "prices": {
            "WLD": {
                "USD": {
                    "asset": "USD",
                    "amount": "1510763",
                    "decimals": 6,
                    "symbol": "USD"
                },
            },
            "USDCE": {
                "USD": {
                    "asset": "USD",
                    "amount": "1000058",
                    "decimals": 6,
                    "symbol": "USD"
                },
            }
        }
    }
}