🏷️Link API

Bounce Link RESTful Web API documentation

Overview

The Link API provides methods for interacting with Link phygital tags, verifying authenticity and ownership of connected collectibles, and managing their claim state.

For details on API authentication, limits and environments see API Overview

Example Link API usage

Link API interaction flow to validate and claim a Bounce Link tag.

Link API endpoints

GET Link tag status

Current status of a Link tag by tag & batch ID

GET https://api.letsbounce.gg/v1/link/status/{batch_id}/{tag_id}

This endpoint returns the status of a single Bounce Link tag by the tag's ID in the specified batch.

Path Parameters

Name	Type	Description
batch_id*	Number
tag_id*	Numbrt

200: OK Link Tag status

Link Tag status response:

{
    batchId: number, // Link Tag batch ID
    tagId: number,   // Link Tag tag ID in batch
    counter: number, // Current tap counter value
    lastTap: number, // Last time a tag was tapped (UNIX timestamp)
    owner: string,   // user ID of the current owner
}

GET Link tag status (batch)

Current status of a list of Link tags by batch ID

GET https://api.letsbounce.gg/v1/link/status/{batch_id}

This endpoint returns the status of a list of Bounce Link tags by an ID range in a specified batch.

Path Parameters

Name	Type	Description
batch_id*	Number	Link tag batch ID

Query Parameters

Name	Type	Description
offset	Number	query offset
count	Number	batch query size

200: OK Link Tag batch status

Link Tag batch status response:

{
    batch: number,  // current batch ID
    offset: number, // first tag ID in status response
    count: number,  // number of tags in status response
    end: boolean,   // is this the last page in the batch?
    tags: [
        {
            batchId: number, // Link Tag batch ID
            tagId: number,   // Link Tag tag ID in batch
            counter: number, // Current tap counter value
            lastTap: number, // Last time a tag was tapped (UNIX timestamp)
            owner: string,   // user ID of the current owner
        }
    ]
}

POST Validate a Link Tag tap (by code)

Validate authenticity of a tapped Link tag with forwarding code

POST https://api.letsbounce.gg/v1/link/validate/code

This endpoint can be used to validate the authenticity, currentness and validity (non-expiry) of a Link tap based on a code received from a Secure Forwarding redirection or deep-link.

In addition to an origin check, this can be used to pass tag verifiable details to a custom hosted page that is redirected to by a Bounce Link Tag tap.

Use this API to generate a short-lived claimCode to use for claiming a Link phygital via the API.

Request Body

Name	Type	Description
code*	String	Short-lived validation code

200: OK Tag validation details

If a code is valid, tag details will be available in the response.

If a tag is open for claim (unclaimed), a claimCode will be provided that you can use to trigger a claim with the Link API.

Link Tag tap validation response:

{
    valid: boolean,  // is the claim code provided valid for a claim
    tag?: {
            batchId: number, // Link Tag batch ID
            tagId: number,   // Link Tag tag ID in batch
            counter: number, // Current tap counter value
            lastTap: number, // Last time a tag was tapped (UNIX timestamp)
            owner: string,   // user ID of the current owner
    },
    claimCode?: string    // optional tag claim code, if tag is unclaimed
    claimExpiry?: number: // the expiration timestamp of the claimCode
}

POST Validate a Link Tag tap (by tag params)

Validate authenticity of a tapped Link tag with tag params

POST https://api.letsbounce.gg/v1/link/validate/tap

This endpoint can be used to validate the authenticity, currentness and validity (non-expiry) of a Link tag tap based on parameters received directly from the tag's dynamic URL.

Rather than extracting the URL params one-by-one, you may provide the entire URL of your claim page, including all dynamic parameters, and these will be parsed on the server.

The tag's batch ID and tag ID may be available as route params in the URL, and must be provided if they are (depending on project setup).

Use this API to generate a short-lived claimCode to use for claiming a Link phygital via the API.

Request Body

Name	Type	Description
url*	String
project_id*	String

200: OK Tag validation details

If a code is valid, tag details will be available in the response.

If a tag is open for claim (unclaimed), a claimCode will be provided that you can use to trigger a claim with the Link API.

Link Tag tap validation response:

{
    valid: boolean,  // is the claim code provided valid for a claim
    tag?: {
            batchId: number, // Link Tag batch ID
            tagId: number,   // Link Tag tag ID in batch
            counter: number, // Current tap counter value
            lastTap: number, // Last time a tag was tapped (UNIX timestamp)
            owner: string,   // user ID of the current owner
    },
    claimCode?: string    // optional tag claim code, if tag is unclaimed
    claimExpiry?: number: // the expiration timestamp of the claimCode
}

POST Claim a Link Tag

Claim a Bounce Link phygital asset

GET https://api.letsbounce.gg/v1/link/claim

This endpoint can be used to claim an asset to a user account using a claimCode received from either a Code-based validation or Tap-based validation Link API calls.

User accounts can be either an Ethereum-compatible wallet addresses, or OAuth-compatible user IDs.

If a wallet is provided, it must be a string formatted hex with a 0x prefix. For example: 0xb794f5ea0ba39494ce839613fffba74279579268. Non-EVM wallets are currently not supported by the API.

Please contact the team at [email protected] for OAuth app integration or non-EVM wallet claims.

Request Body

Name	Type	Description
claimCode*	String	A valid claim code from a validation response
user_account	String	A user's OAuth shared identifier
user_wallet	String	A user's Ethereum wallet address

200: OK Tag claim details

In most cases claims are instant and a claim attempt will return as completed.

However, in some cases (and some blockchains), a claim might take longer than the request window, and a pending state will be returned.

In that case, please follow up on the claim request with a claim status request using the provided claimId

The Bounce SDK will manage delayed claims automatically and pull for status updates until a claim succeeds or fails.

Link Tag claim response:

{
    claimed: boolean, // status of the claim (completed successfuly)
    pending: boolean, // is claim still pending?
    claimId: string,  // claim record ID
}

GET Link Tag claim status

Current status of a Link Tag claim

GET https://api.letsbounce.gg/v1/link/claim/status/{claim_id}

This endpoint can be used in cases where a claim request is long-running, or to verify the status of a claim request by claimId.

Path Parameters

Name	Type	Description
claim_id*	String	A claim ID received by a claim request API call

200: OK Tag claim status details

Link Tag claim status response:

{
    claimed: boolean, // status of the claim (completed successfuly)
    pending: boolean, // is claim still pending?
    claimId: string,  // claim record ID
    tag: {
            batchId: number, // Link Tag batch ID
            tagId: number,   // Link Tag tag ID in batch
            counter: number, // Current tap counter value
            lastTap: number, // Last time a tag was tapped (UNIX timestamp)
            owner: string,   // user ID of the current owner
    },
    owner?: string, // user ID of tag owner, if claim is completed
}