Construct Address

POST /addresses

status: stable

Construct any address by specyfying credential for payment or delegation.

In Cardano, Addresses are made of three parts:

*---------*---------*-----------*
| NETWORK | PAYMENT | DELEGATION |
*---------*---------*-----------*

The NETWORK part allows for distinguishing addresses between different networks like the mainnet or the testnet. It is implicitly handled by the server without you having to worry about it. The PAYMENT and DELEGATION parts however can be constructed similarly, using either:

  • A public key
  • A script

The script itself is either constructed out of a public key, one of two timelocks, or one of the three following primitives:

  • all
  • any
  • some

The timelock can determine validity as respect to the slot. active_from slot means the script is valid from the specified slot and onward. active_until slot means the script is valid until (not included) the specified slot.

Each of which contains one or more script(s) that can be either keys or primitives, and so on. Schematically:

                                   ┏─────────┓
SCRIPT = ──┬───────────────────────┤ pub key ├─────────────────────┬──
           │                       ┗─────────┛                     │
           │                       ┏──────────────────┓            │
           ├───────────────────────┤ ACTIVE_FROM slot ├──── ───────┤
           │                       ┗──────────────────┛            │
           │                       ┏───────────────────┓           │
           ├───────────────────────┤ ACTIVE_UNTIL slot ├───────────┤
           │                       ┗───────────────────┛           │
           │                                                       │
           │  ╭─────╮   ╭────────╮                                 │
           ├──┤ ALL ├───┤ SCRIPT ├─┬───────────────────────────────┤
           │  ╰─────╯ ^ ╰────────╯ │                               │
           │          │   ╭───╮    │                               │
           │          └───┤ , ├────┘                               │
           │              ╰───╯                                    │
           │  ╭─────╮   ╭────────╮                                 │
           ├──┤ ANY ├───┤ SCRIPT ├─┬───────────────────────────────┤
           │  ╰─────╯ ^ ╰────────╯ │                               │
           │          │   ╭───╮    │                               │
           │          └───┤ , ├────┘                               │
           │              ╰───╯                                    │
           │  ╭──────╮ ╭──────────╮ ┏───┓ ╭──────╮   ╭────────╮    │
           └──┤ SOME ├─┤ AT_LEAST ├─┤ n ├─┤ FROM ├───┤ SCRIPT ├─┬──┘
              ╰──────╯ ╰──────────╯ ┗───┛ ╰──────╯ ^ ╰────────╯ │
                                                   │   ╭───╮    │
                                                   └───┤ , ├────┘
                                                       ╰───╯
application/json

Body

  • payment string(bech32) | object

    One of:
    public key string(bech32) extended public key string(bech32) key hash string(bech32) Key Hash string(bech32) All object Any object Some object Active from slot object Active until slot object script hash string(bech32)

    A public key (public key without chain code) for credential - 32 bytes

    Format should match the following pattern: ^((addr_vk)|(stake_vk))1[0-9a-z]*$.

    An extended public key (public key with chain code) for credential - 64 bytes

    Format should match the following pattern: ^((addr_xvk)|(stake_xvk))1[0-9a-z]*$.

    A key hash for credential - 28 bytes

    Format should match the following pattern: ^((addr_vkh)|(stake_vkh))1[0-9a-z]*$.

    Leaf value for a script designating a required verification key hash.

    Format should match the following pattern: ^((addr_shared_vkh)|(stake_shared_vkh)|(policy_vkh))1[0-9a-z]*$.

    A script hash - 28 bytes

    Format should match the following pattern: ^(script)1[0-9a-z]*$.

  • stake string(bech32) | object

    One of:
    public key string(bech32) extended public key string(bech32) key hash string(bech32) Key Hash string(bech32) All object Any object Some object Active from slot object Active until slot object script hash string(bech32)

    A public key (public key without chain code) for credential - 32 bytes

    Format should match the following pattern: ^((addr_vk)|(stake_vk))1[0-9a-z]*$.

    An extended public key (public key with chain code) for credential - 64 bytes

    Format should match the following pattern: ^((addr_xvk)|(stake_xvk))1[0-9a-z]*$.

    A key hash for credential - 28 bytes

    Format should match the following pattern: ^((addr_vkh)|(stake_vkh))1[0-9a-z]*$.

    Leaf value for a script designating a required verification key hash.

    Format should match the following pattern: ^((addr_shared_vkh)|(stake_shared_vkh)|(policy_vkh))1[0-9a-z]*$.

    A script hash - 28 bytes

    Format should match the following pattern: ^(script)1[0-9a-z]*$.

  • validation string

    Script validation level. Required validation sifts off scripts that would not be accepted by the ledger. Recommended level filters out scripts that do not pass required validation and additionally when:

    • 'all' is non-empty
    • there are redundant timelocks in a given level
    • there are no duplicated verification keys in a given level
    • 'at_least' coefficient is positive
    • 'all', 'any' are non-empty and `'at_least' has no less elements in the list than the coefficient after timelocks are filtered out.

    Values are required or recommended.

Responses

  • 415 application/json

    Unsupported Media Type

    Hide response attributes Show response attributes object
    • message string Required

      A descriptive error message.

    • code string Required

      A specific error code for this error, more precise than HTTP ones.
  • 406 application/json

    Not Acceptable

    Hide response attributes Show response attributes object
    • message string Required

      May occur when providing an invalid 'Accept' header.

    • code string Required

      Value is not_acceptable.
  • 400 application/json

    Bad Request

    Hide response attributes Show response attributes object
    • message string Required

      May occur when a request is not well-formed; that is, it fails to parse successfully. This could be the case when some required parameters are missing or, when malformed values are provided.

    • code string Required

      Value is bad_request.
  • 202 application/json

    Accepted

    Hide response attribute Show response attribute object
    • address string(bech32) Required

      A Shelley address representing either enterprise, reward account or delegating address

      Format should match the following pattern: ^((addr)|(stake)|(addr_test)|(stake_test))1[0-9a-z]*$.
POST /addresses 
curl \
 --request POST https://localhost:8090/v2/addresses \
 --header "Content-Type: application/json" \
 --data '{"payment":["stake_vk16apaenn9ut6s40lcw3l8v68xawlrlq20z2966uzcx8jmv2q9uy7qau558d","addr_vk16apaenn9ut6s40lcw3l8v68xawlrlq20z2966uzcx8jmv2q9uy7q3yvuv2"],"stake":["stake_vk16apaenn9ut6s40lcw3l8v68xawlrlq20z2966uzcx8jmv2q9uy7qau558d","addr_vk16apaenn9ut6s40lcw3l8v68xawlrlq20z2966uzcx8jmv2q9uy7q3yvuv2"],"validation":"required"}'
Request examples 
{
  "payment": [
    "stake_vk16apaenn9ut6s40lcw3l8v68xawlrlq20z2966uzcx8jmv2q9uy7qau558d",
    "addr_vk16apaenn9ut6s40lcw3l8v68xawlrlq20z2966uzcx8jmv2q9uy7q3yvuv2"
  ],
  "stake": [
    "stake_vk16apaenn9ut6s40lcw3l8v68xawlrlq20z2966uzcx8jmv2q9uy7qau558d",
    "addr_vk16apaenn9ut6s40lcw3l8v68xawlrlq20z2966uzcx8jmv2q9uy7q3yvuv2"
  ],
  "validation": "required"
}
Response examples (415) 
{
  "message": "string",
  "code": "an_error_code"
}
Response examples (406) 
{
  "message": "string",
  "code": "not_acceptable"
}
Response examples (400) 
{
  "message": "string",
  "code": "bad_request"
}
Response examples (202) 
{
  "address": [
    "stake17xt2z3pa7etaxp7jurdg0m8jhsmtp4r2z56pd3a5q3jhxycdxzmx9",
    "addr1wy5np0m5x03tax3kcdh6e2cet98qcfs80wtv4cyvl5taclc6dnd8e",
    "addr1xy5np0m5x03tax3kcdh6e2cet98qcfs80wtv4cyvl5tacluk59zrmajh6vra9cx6slk090pkkr2x59f5zmrmgpr9wvfs37hjk4"
  ]
}