Technical Reference
API Reference
Base URL
https://developer.worldcoin.org
Verify Proof
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
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
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 formatworldapp://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 theapi_key
for your app from the Developer Portal. Make sure to prefix it withBearer {api_key}
.
Request
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 tosent
(boolean): Whether the notification was successfully sent to this wallet addressreason
(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
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
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
{
"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
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 theapi_key
for your app from the Developer Portal. Make sure to prefix it withBearer {api_key}
.
Request
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 transactioncreatedAt
(string): The timestamp when the transaction was created, in ISO 8601 formatblock
(number): The block number where the transaction was attemptedsimulationRequestId
(string): The ID of the simulation requestsimulationError
(string): The error message from the simulation, if anywalletAddress
(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
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
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
{
"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
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 theapi_key
for your app from the Developer Portal. Make sure to prefix it withBearer {api_key}
.
Request
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"
}
}