Fractal Credentials API
Authorize transactions by including a Fractal proof in their payload.
Last updated
Was this helpful?
Authorize transactions by including a Fractal proof in their payload.
Last updated
Was this helpful?
Credentials API enable you to verify the credentials associated with a wallet address in your smart contract (on-chain) or in your dApp. With Credentials API, your dApp makes a call to the API with a wallet address.
The API replies with a credential proof if it exists associated with that wallet address. Your dApp includes the proof with the transaction sent to your smart contract which can verify the credential by importing our CredentialVerifier.sol
contract to inherit its requiresCredential
modifier. To get more details and examples check our documentation.
Using the Credentials API, you can leverage our existing user base with a quick and easy solution to access the provably verifiable KYC/KYB status of the identity behind a wallet address and validate it on-chain.
For compliance purposes, you may be required to access the user data supporting the issued Credential. In order to do this, make sure to follow the directions in in the Message format section.
You can play around with a demo on . Its full source code is available at .
Staging
credentials.next.fractal.id
0x2fCAb633adFA6aF8266025D63228047033c3ceD0
Production
credentials.fractal.id
0xacD08d6714ADba531beFF582e6FD5DA1AFD6bc65
You are required to create an application using our Developer Dashboard in order to use this API. See how .
Before a user interacts with your contract, ask them to sign a message authorizing Fractal to respond on their behalf.
Send this message and signature to Fractal's API, which returns an expiry timestamp (24 hours in the future), a proof (Fractal's signature of the user's credential) and other relevant fields.
Use this these fields and the proof as arguments to your contract's method.
GET
credentials.fractal.id
message*
String
Message that authorizes sharing KYC/KYB data and defines credential requirements
signature*
String
Signature of message using personal_sign
<application_name>
Name of your Fractal ID application
<verification_type>
KYB or KYC
<client_id>
UID of your Fractal ID application
<level>
Requested KYC/KYB level
<citizenship_country_list>
Citizenship country blocklist
<residency_country_list>
Residency country blocklist
Choose or verification type — KYB
or KYC
.
You must choose 1 level and any number of addons in the following format:
You can define which countries should not be accepted for citizenship and/or residency. If a user matches your other requirements but is a citizen of or resides in one of the define countries, a credential will not be issued — it will result in a 404 response.
The format for each country list is the following:
Note that, currently, country blocklists only apply to individuals. In case of KYB, these are applied to the individual person representing the company.
Example #1 — citizenship and residency restrictions, and access to user data
Example #2 — citizenship and residency restrictions (no access to user data)
Example #3 — citizenship restriction (no access to user data)
Example #4 — no country restrictions (no access to user data)
Example response
approvedAt
UNIX timestamp
User approval timestamp
address
EVM address
User address
fractalId
Hex string
User unique identifier
validUntil
UNIX timestamp
Credential expiry timestamp (24h after issuance)
proof
Hex string
Signed proof of KYC/KYB
credential
String
The expectedCredential
this proof is for
error: invalid_params
Why? The message
and/or signature
query parameter is missing.
Fix: Both parameters are required.
error: invalid_signature
Why? The signature
you supplied is invalid.
Fix: Please make sure to use personal_sign
when requesting the user to sign the message.
error: user_pending
Why? There is a user in our system that matches your KYC/KYB requirements and is identified by the wallet address that signed the message. However, their verification has not yet been approved.
Fix: Direct the user to Fractal ID — if they're waiting on Fractal to approve their verification, there's no further action; if they've been contacted by Fractal's Identity Specialists to update their data, they should do so in Fractal ID.
error: user_not_found
Why? There is no user in our system that matches your KYC/KYB requirements and is identified by the wallet address that signed the message.
Fix: Use your authorization link to direct the user to our KYC/KYB journey.
You can easily generate a valid message using the .
These can be found in the .
Choose your required . Please reach out to if you don't know what to choose.
The country code and name is checked against the list.
For compliance purposes, you might want to be able to access the user data supporting the issued Credential. In order to do this, you should include the last string described in the .
By including this string, you'll have access to the user's data in the .
You can easily generate a message by using this and inputting your own values.
error: invalid_configuration
Why? You've tried to add country restrictions that are not supported by the level you chose.
Fix: Use only valid country restrictions — see .
error: invalid_client_id
Why? The application_uid
you have supplied is not in the system.
Fix: Check if there's a typo; or if you have not done so.
error: invalid_country
Why? The country list(s) you supplied contain invalid country names or codes.
Fix: Please refer to the list or use our .
error: invalid_level
Why? The level
you supplied is not valid.
Fix: Please refer to the .
error: invalid_message_schema
Why? The message
you supplied is not valid.
Fix: Please use our or make sure that the message that you created matches the format described above.
Please refer to for an example on how to use the KYC/KYB proof in your smart contract.