Account Stats

curl -X GET "https://account.gw3.io/api/v0/stats?ts=$(date +%s)" \
   -H "X-Access-Key: YOUR_ACCESS_KEY" \
   -H "X-Access-Secret: YOUR_ACCESS_SECRET"

Get the usage stats for a given account.

ts
- Required: Yes
- Description: a query parameter that represents the current unix timestamp
- Example: 1688644825

Response body

{
    "code": 200,
    "msg": "ok",
    "data": {
        "name": "John Doe",
        "provider": "gw3",
        "email": "example@example.com",
        "email_verified": true,
        "eth_addr": "0x4838b106fce9647bdf1e7877bf73ce8b0bad5f97",
        "token_amount": "0.00",
        "plan": "Advanced",
        "next_plan": "Starter",
        "next_bill_at": 1689902000,
        "pinned_count": 23,
        "pinned_count_limit": 100,
        "pinned_bytes": 374182,
        "pinned_bytes_limit": 1073741824,
        "ingress": 3687091,
        "ingress_limit": 5368709120,
        "egress": 536870,
        "egress_limit": 5368709120,
        "ipns": 1,
        "ipns_limit": 1
    }
}

List Pin

curl -X GET "https://account.gw3.io/api/v0/pin?status=pinned&limit=10&start=0&ts=$(date +%s)" \
   -H "X-Access-Key: YOUR_ACCESS_KEY" \
   -H "X-Access-Secret: YOUR_ACCESS_SECRET"

List all the pins under the account. There are four pin statuses: pinning, pinned, failure, and unpinning.

ts
- Required: Yes
- Description: A query parameter that represents the current UNIX timestamp.
- Example: 1688644825
status
- Required: No
- Description: Filter the specific type of pin to list.
- Example: pinned
limit
- Required: No
- Description: The maximum number of records returned for pagination. The default is 10.
- Example: 5
start
- Required: No
- Description: Skips the first n results for pagination. Default is 0.
- Example: 10

Response Body

{
    "code": 200,
    "data": [
        {
            "name": "",
            "cid": "bafybeig6ka5mlwkl4subqhaiatalkcleo4jgnr3hqwvpmsqfca27cijp3i",
            "status": "unpinning",
            "size": 623,
            "created_at": 1690821977
        },
        {
            "name": "Unknow CID",
            "cid": "QmNYERzV2LfD2kkfahtfv44ocHzEFK1sLBaE7zdcYT2GAZ",
            "status": "failure",
            "size": 16,
            "created_at": 1690821971
        },
        {
            "name": "996.png",
            "cid": "bafybeiafyvqlazbbbtjnn6how5d6h6l6rxbqc4qgpbmteaiskjrffmyy4a",
            "status": "pinned",
            "size": 711,
            "created_at": 1690821965
        },
        {
            "name": "123.txt",
            "cid": "QmS2zdgve11D6Qg3yCne4pozZPs99TEXDNCNrct4mwSeKf",
            "status": "pinning",
            "size": 4297,
            "created_at": 1690821900
        }
    ],
    "total": 14
}

Get Pin

curl -X GET "https://account.gw3.io/api/v0/pin/{cid}?ts=$(date +%s)" \
   -H "X-Access-Key: YOUR_ACCESS_KEY" \
   -H "X-Access-Secret: YOUR_ACCESS_SECRET"

Retrieve the pin status of a specific CID.

cid
- Required: Yes
- Description: A CID that has been previously pinned by GW3.
- Example: bafybeidsanbjcw4nzqh275lfz4zqssztgbz2zpzz76glkz34dbwfhyfnxy
ts
- Required: Yes
- Description: A query parameter representing the current UNIX timestamp.
- Example: 1688644825

Response Body

{
    "code": 200,
    "msg": "ok",
    "data": {
        "name": "my_codes",
        "cid": "bafybeidsanbjcw4nzqh275lfz4zqssztgbz2zpzz76glkz34dbwfhyfnxy",
        "status": "pinned",
        "size": 53695,
        "created_at": 1690978958
    }
}

Update Pin Name

curl -X POST "https://account.gw3.io/api/v0/pin/rename?ts=$(date +%s)" \
   -H "X-Access-Key: YOUR_ACCESS_KEY" \
   -H "X-Access-Secret: YOUR_ACCESS_SECRET"

To update the name of your pinned CID

ts
- Required: Yes
- Description: A query parameter representing the current UNIX timestamp.
- Example: 1688644825

Request body

{
    "cid": "k51qzi5uqu5dlfmf1hd70bi1nqnzdsebu5n1ajtfhmx1blbexpiblpp5knvepe",
    "name": "hello.html"
}

Response Body

{
    "code": 200,
    "msg": "ok",
}

List IPNS

curl -X GET "https://account.gw3.io/api/v0/ipns?limit=10&start=0&ts=$(date +%s)" \
   -H "X-Access-Key: YOUR_ACCESS_KEY" \
   -H "X-Access-Secret: YOUR_ACCESS_SECRET"

List all the ipns under the account.

ts
- Required: Yes
- Description: A query parameter that represents the current UNIX timestamp.
- Example: 1688644825
limit
- Required: No
- Description: The maximum number of records returned for pagination. The default is 10.
- Example: 5
start
- Required: No
- Description: Skips the first n results for pagination. Default is 0.
- Example: 10

Response Body

{
    "code":200,
    "data":[
        {
            "name":"k51qzi5uqu5dgvei2o3pp7kkz4a6tyj5hp2fdvl2l32wpk5quy657lzh1yaqe0",
            "value":"QmNYERzV2LfD2kkfahtfv44ocHzEFK1sLBaE7zdcYT2GAZ",
            "alias":"My first IPNS",
            "created_at": 1690217292, // Created Unix timestamp.
            "publish_at": 1692526344  // Last timestamp, the user updated the record's CID
        }
    ],
    "total":1
}

Get IPNS

curl -X GET "https://account.gw3.io/api/v0/ipns/{name}?ts=$(date +%s)" \
   -H "X-Access-Key: YOUR_ACCESS_KEY" \
   -H "X-Access-Secret: YOUR_ACCESS_SECRET"

Retrieve the IPNS record by name.

name
- Required: Yes
- Description: The IPNS record name you’ve created or imported.
- Example: k51qzi5uqu5dj14wlw7kc5xlzqzy4u42og35hhhihi2v8551odsw7hlgwhskz2
ts
- Required: Yes
- Description: A query parameter representing the current UNIX timestamp.
- Example: 1688644825

Response Body

{
    "code": 200,
    "msg": "ok",
    "data": {
        "name": "k51qzi5uqu5dj14wlw7kc5xlzqzy4u42og35hhhihi2v8551odsw7hlgwhskz2",
        "value": "QmVJ4ZUSC9HS7H1P8TrqP5UDGByGraJwwMpKpUKQnYLqV5",
        "alias": "Test1",
        "created_at": 1690217292,
        "publish_at": 1691747064
    }
}

Search IPNS

curl -X GET "https://account.gw3.io/api/v0/ipns/search?alias={alias}&ts=$(date +%s)" \
   -H "X-Access-Key: YOUR_ACCESS_KEY" \
   -H "X-Access-Secret: YOUR_ACCESS_SECRET"

Search the IPNS record by alias.

alias
- Required: Yes
- Description: The IPNS alias.
- Example: first_record
ts
- Required: Yes
- Description: A query parameter representing the current UNIX timestamp.
- Example: 1688644825

Response Body

{
    "code": 200,
    "msg": "ok",
    "data": {
        "name": "k51qzi5uqu5dj14wlw7kc5xlzqzy4u42og35hhhihi2v8551odsw7hlgwhskz2",
        "value": "QmVJ4ZUSC9HS7H1P8TrqP5UDGByGraJwwMpKpUKQnYLqV5",
        "alias": "first_record",
        "created_at": 1690217292,
        "publish_at": 1691747064
    }
}

Update IPNS Alias

curl -X POST "https://account.gw3.io/api/v0/ipns/alias?ts=$(date +%s)" \
   -H "X-Access-Key: YOUR_ACCESS_KEY" \
   -H "X-Access-Secret: YOUR_ACCESS_SECRET"

To update the alias of your IPNS record

ts
- Required: Yes
- Description: A query parameter representing the current UNIX timestamp.
- Example: 1688644825

Request body

{
    "name": "k51qzi5uqu5dlfmf1hd70bi1nqnzdsebu5n1ajtfhmx1blbexpiblpp5knvepe",
    "alias": "icu"
}

Response Body

{
    "code": 200,
    "msg": "ok",
}

Plans

curl -X GET "https://account.gw3.io/api/v0/plans"

List all the available plans.

Response body

{
    "code": 200,
    "msg": "ok",
    "data": [
        {
            "id": 1,
            "name": "Free",
            "price": "0.00",
            "pinned_count_limit": 100,
            "pinned_bytes_limit": 1073741824,
            "ingress_limit": 5368709120,
            "egress_limit": 5368709120,
            "ipns_limit": 3
        },
        {
            "id": 3,
            "name": "Plan0",
            "price": "$ 9.99",
            "pinned_count_limit": 2000,
            "pinned_bytes_limit": 107374182400,
            "ingress_limit": 21474836480,
            "egress_limit": 21474836480,
            "ipns_limit": 1
        },
    ]
}

Create Access Key

curl -X POST "https://account.gw3.io/api/v0/key?ts=$(date +%s)" \
   -H "X-Access-Key: YOUR_ACCESS_KEY" \
   -H "X-Access-Secret: YOUR_ACCESS_SECRET"

Create an access key with the given permissions for a user. The available permissions are admin, read, write, pin, and unpin. The admin permission is equivalent to granting all the permissions.

ts
- Required: Yes
- Description: a query parameter that represents the current unix timestamp
- Example: 1688644825

Request body

{
    "name": "test_key",
    "permissions": ["read", "write", "pin", "unpin"]
}

Response body

{
    "code": 200,
    "msg": "ok",
    "data": {
        "access_key": "d2e8c7c1-f2cd-4768-b8cd-2c10ea940f64",
        "access_secret": "LQTT4T5XzNtm9tXzUoLoknsYDif64Zr2W6zwrwFYRD35egaGq+WGkPbderrgr+9bPP9fhozhAwu7Zv6YByVaMXdQklxu4wMb6WUnss4+BIzDlfJx2m2a3EBGCs3PMSwsICp5XwJ/Qe3YdFA8JuA5NwiMQ03GXyjN8fFBYNa0UYA="
    }
}

List Access Key

curl -X GET "https://account.gw3.io/api/v0/keys?ts=$(date +%s)" \
   -H "X-Access-Key: YOUR_ACCESS_KEY" \
   -H "X-Access-Secret: YOUR_ACCESS_SECRET"

List all access keys.

ts
- Required: Yes
- Description: a query parameter that represents the current unix timestamp
- Example: 1688644825

Response body

{
    "code": 200,
    "msg": "ok",
    "data": [
        {
            "name": "k3",
            "access_key": "05e8d09b-cc5c-4429-8bb5-2fee6c26b244",
            "permissions": [
                "read"
            ]
        },
        {
            "name": "k4",
            "access_key": "99e12dbb-1824-4885-8917-f1f64d4df8b1",
            "permissions": [
                "admin"
            ]
        }
    ]
}

Delete User Access Key

curl -X DELETE "https://account.gw3.io/api/v0/key?ts=$(date +%s)" \
   -H "X-Access-Key: YOUR_ACCESS_KEY" \
   -H "X-Access-Secret: YOUR_ACCESS_SECRET"

Delete the access key by name.

ts
- Required: Yes
- Description: a query parameter that represents the current unix timestamp
- Example: 1688644825

Request body

{
    "name": "test_key"
}

Response body

{
    "code": 200,
    "msg": "ok"
}