Technical Reference

API Reference

Base URL

https://developer.worldcoin.org

Verify Proof

POST/api/v2/verify/{app_id}

Enables you to verify a World ID proof for a Cloud action. To ensure sybil-resistance, by default, a single person can only verify once for every action. The number of allowed verifications for a single user can be configured in the Developer Portal.

Request Body

  • Name
    nullifier_hash
    Type
    string
    Required
    REQUIRED
    Description

    The unique user identifier (called the nullifier hash in the ZKP), as provided by IDKit. See IDKit response for details.

  • Name
    proof
    Type
    string
    Required
    REQUIRED
    Description

    The zero-knowledge proof, as provided by IDKit. See IDKit response for details.

  • Name
    merkle_root
    Type
    string
    Required
    REQUIRED
    Description

    Part of the ZKP, the hash of the Merkle root that proves membership to the set of credentials. As provided by IDKit. See IDKit response for details.

  • Name
    verification_level
    Type
    string
    Required
    REQUIRED
    Description

    The verification level, as provided by IDKit. See IDKit response for details.

  • Name
    action
    Type
    string
    Required
    REQUIRED
    Description

    Same action identifier as passed to IDKit.

  • Name
    signal_hash
    Type
    string: hashToField('').digest
    Description

    The hash of the signal that was used to generate the proof. Defaults to the hash of an empty string.

  • Name
    max_age
    Type
    number: 7200
    Description

    The maximum age of the root in seconds. This parameter controls how old the Merkle root used in the proof can be. Minimum value is 3600 (1 hour) and maximum value is 604800 (7 days). Defaults to 7200 (2 hours).

Possible Responses

  • 200 OK - The proof was successfully verified.
  • 400 Bad Request - The proof was invalid or the user has already verified for this action.

Request

POST
/api/v2/verify/{app_id}
curl -X POST "/api/v2/verify/{app_id}" \
    -H "Content-Type: application/json" \
    -d '{
        "nullifier_hash": "0x2bf8406809dcefb1486dadc96c0a897db9bab002053054cf64272db512c6fbd8",
        "merkle_root": "0x2264a66d162d7893e12ea8e3c072c51e785bc085ad655f64c10c1a61e00f0bc2",
        "proof": "0x1aa8b8f3b2d2de5ff452c0e1a83e29d6bf46fb83ef35dc5957121ff3d3698a1119090fb...",
        "verification_level": "orb",
        "action": "my_action",
        "signal_hash": "0x00c5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a4",
        "max_age": 3600
    }'

Response

{
	"success": true,
	"action": "my_action",
	"nullifier_hash": "0x2bf8406809dcefb1486dadc96c0a897db9bab002053054cf64272db512c6fbd8",
	"created_at": "2023-02-18T11:20:39.530041+00:00"
}

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. May contain emojis.

  • Name
    message
    Type
    string
    Required
    REQUIRED
    Description

    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.

  • 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": "Hello ${username}, your transaction is complete!", "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": "USDC",
    "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.

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

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

  • 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. USDC,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"
                },
            },
            "USDC": {
                "USD": {
                    "asset": "USD",
                    "amount": "1000058",
                    "decimals": 6,
                    "symbol": "USD"
                },
            }
        }
    }
}

Get User Grant Cycle

GEThttps://developer.worldcoin.org/api/v2/minikit/user-grant-cycle

This endpoint lets you retrieve the next grant claim date for a user of your mini app. You will only be able to query for users who have installed your app and have an active grant cycle.

Query Params

  • Name
    wallet_address
    Type
    string
    Required
    REQUIRED
    Description

    The wallet_address of the user to query. Must be exactly 42 characters long.

  • Name
    app_id
    Type
    string
    Required
    REQUIRED
    Description

    The app_id of your mini app.

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/user-grant-cycle
curl -X GET "https://developer.worldcoin.org/api/v2/minikit/user-grant-cycle?wallet_address={wallet_address}&app_id={app_id}" \
    -H "Authorization: Bearer {api_key}"

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
    object
    Description

    The result object containing:

    • nextGrantClaimUTCDate (string): The UTC date when the user's next grant can be claimed, in ISO 8601 format

Error Responses

  • Name
    user_not_found_for_wallet_address
    Type
    error
    Description

    The specified wallet address was not found in the system.

  • Name
    app_not_installed
    Type
    error
    Description

    The user has not installed the specified mini app.

  • Name
    no_active_grant_cycles
    Type
    error
    Description

    The user does not have any active grant cycles.

Response

{
    "success": true,
    "status": 200,
    "result": {
        "nextGrantClaimUTCDate": "2024-12-31T00:00:00.000Z"
    }
}