# Link API

## 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](/integration-guides/apis-and-sdks/rest-api/api-overview.md)

### Example Link API usage

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

<img src="/files/NW30TGCf6uiUPReylMhy" alt="" class="gitbook-drawing">

## Link API endpoints

### `GET` Link tag status

## Current status of a Link tag by tag & batch ID

<mark style="color:blue;">`GET`</mark> `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<mark style="color:red;">\*</mark> | Number |             |
| tag\_id<mark style="color:red;">\*</mark>   | Numbrt |             |

{% tabs %}
{% tab title="200: OK Link Tag status" %}
Link Tag status response:

```typescript
{
    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
}
```

{% endtab %}
{% endtabs %}

### `GET` Link tag status (batch)

## Current status of a list of Link tags by batch ID

<mark style="color:blue;">`GET`</mark> `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<mark style="color:red;">\*</mark> | Number | Link tag batch ID |

#### Query Parameters

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

{% tabs %}
{% tab title="200: OK Link Tag batch status" %}
Link Tag batch status response:

```typescript
{
    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
        }
    ]
}
```

{% endtab %}
{% endtabs %}

### `POST` Validate a Link Tag tap (by code)

## Validate authenticity of a tapped Link tag with forwarding code

<mark style="color:green;">`POST`</mark> `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*](/integration-guides/apis-and-sdks/web-notifications-and-forwarding.md) 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<mark style="color:red;">\*</mark> | String | Short-lived validation code |

{% tabs %}
{% tab title="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:

```typescript
{
    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
}
```

{% endtab %}
{% endtabs %}

### `POST` Validate a Link Tag tap (by tag params)

## Validate authenticity of a tapped Link tag with tag params

<mark style="color:green;">`POST`</mark> `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<mark style="color:red;">\*</mark>         | String |             |
| project\_id<mark style="color:red;">\*</mark> | String |             |

{% tabs %}
{% tab title="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:

```typescript
{
    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
}
```

{% endtab %}
{% endtabs %}

### `POST` Claim a Link Tag

## Claim a Bounce Link phygital asset

<mark style="color:blue;">`GET`</mark> `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](#validate-authenticity-of-a-tapped-link-tag-with-forwarding-code) or [Tap-based validation](#validate-authenticity-of-a-tapped-link-tag-with-tag-params) 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 <support@letsbounce.gg> for OAuth app integration or non-EVM wallet claims.

#### Request Body

| Name                                        | Type   | Description                                   |
| ------------------------------------------- | ------ | --------------------------------------------- |
| claimCode<mark style="color:red;">\*</mark> | 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              |

{% tabs %}
{% tab title="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](/integration-guides/apis-and-sdks/bounce-sdk.md) will manage delayed claims automatically and pull for status updates until a claim succeeds or fails.

Link Tag claim response:

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

{% endtab %}
{% endtabs %}

### `GET` Link Tag claim status

## Current status of a Link Tag claim

<mark style="color:blue;">`GET`</mark> `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<mark style="color:red;">\*</mark> | String | A claim ID received by a [claim request](#post-claim-a-link-tag) API call |

{% tabs %}
{% tab title="200: OK Tag claim status details" %}
Link Tag claim status response:

```typescript
{
    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
}
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.letsbounce.gg/integration-guides/apis-and-sdks/rest-api/link-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.